Page History

Info
Please start here if you want to connect your service to the SURFconext platform

Shibboleth is a free, open-source web single sign-on system with rich attribute-exchange based on open standards, principally SAML. It supports both Apache (on several platforms, notably Linux, OSX, Solaris, and Windows), and several versions of Microsoft IIS (5, 6, 7).

...

Start by setting up Apache as you normally would. The The SP to connect to SURFconext should be using HTTPS with valid certificates (self-signed certificates do not suffice). An An example configuration file for the SP could look like this:

Code Block

controls	true
theme	Default

<VirtualHost _default_:443>
        Servername mfspmysp.gadgetsexample.surfconext.nlorg
        ServerAdmin bas.zoetekouw@surfnet.nlserver-admin@example.org

        DocumentRoot /var/www/mfspmysp
        <Directory />
                Options FollowSymLinks
                AllowOverride None
        </Directory>
        <Directory /var/www/>
                Options Indexes FollowSymLinks MultiViews
                AllowOverride None
        </Directory>

        SSLEngine on
        SSLCertificateFile    /etc/ssl/certs/yourhostmy_https_server.crt
        SSLCertificateKeyFile /etc/ssl/private/yourhostmy_https_server.key
</VirtualHost>

Then, install Shibboleth. In In Debian and Ubuntu, the package is called libapache2called libapache2-mod-shib (or libapache2-mod-shib2 in older releases), and simply apt-getting will work fine.

Shibboleth consists of two parts: a daemon (shibd) that handles communication with the SP and IdPs, and an Apache module that handles the authentication in the web server. Make Make sure that the daemon is running, and that the Apache module is loaded (a2enmod shiba2enmod shib; apachectl -k graceful).

If everything is set up correctly, you should be able to reach https://mfspmysp.gadgetsexample.surfconext.nlorg/Shibboleth.sso/Status (substitute your local host name, obviously). This should show Shibboleth status information in XML form. Note Note that this link will only work from a remote machine if you modify the access control list (acl) attribute of the <Handler type="Status"> entry in the /etc/shibboleth/shibboleth2.xml file (the file is named shibboleth2.xml also in version 3 and later).
The file should look like this:

Code Block

controls	true
language	xml
theme	Default

<StatusHandler time="2011-10-14T14:06:55Z">
  <Version Xerces-C="3.2.1" XML-Tooling-C="3.0.3" XML-Security-C="2.0.2" OpenSAML-C="3.0.0" Shibboleth="3.0.3"/>
  <NonWindows sysname="Linux" nodename="mfspmysp" release="3.10.0-862.14.4.el7.x86_64" version="#1 SMP Wed Sep 26 15:12:11 UTC 2018" machine="i686"/>
  <SessionCache>
    <OK/>
  </SessionCache>
  <Application id="default" entityID="https://spmysp.example.org/shibboleth"/>
  <Handlers>
    <Handler type="ArtifactResolutionService" Location="/Artifact/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/POST-SimpleSign" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
    <Handler type="AssertionConsumerService" Location="/SAML2/ECP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS"/>
    <Handler type="AssertionConsumerService" Location="/SAML/POST" Binding="urn:oasis:names:tc:SAML:1.0:profiles:browser-post"/>
    <Handler type="AssertionConsumerService" Location="/SAML/Artifact" Binding="urn:oasis:names:tc:SAML:1.0:profiles:artifact-01"/>
    <Handler type="SessionInitiator" Location="/Login"/>
    <Handler type="SingleLogoutService" Location="/SLO/SOAP" Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"/>
    <Handler type="SingleLogoutService" Location="/SLO/Redirect" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
    <Handler type="SingleLogoutService" Location="/SLO/POST" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
    <Handler type="SingleLogoutService" Location="/SLO/Artifact" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"/>
    <Handler type="LogoutInitiator" Location="/Logout"/>
    <Handler type="MetadataGenerator" Location="/Metadata"/>
    <Handler type="Status" Location="/Status"/>
    <Handler type="Session" Location="/Session"/>
    <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
  </Handlers>
  <Status>
    <OK/>
  </Status>
</StatusHandler>

...

Next, Shibboleth needs to be set up as an SP. The The configuration process is described more elaborately at https://wiki.shibboleth.net/confluence/display/SP3/GettingStarted, but the instructions below should get you up to speed quickly.

...

Start by generating a new SSL RSA key pair . This and a self signed certificate. This key pair will be is used by Shibboleth to sign its SAML metadata and to sign SAML messages that are exchanged between SURFconext and your SPit sends to other partie like SURFconext.

Code Block
openssl req -newkey rsa:4096 -new -x509 -days 3652 -nodes -text -out shib.crt -keyout shib.key

...

Change owner of the private key so shibd can read it:

Code Block

language	bash

chown _shibd /etc/shibboleth/shib.key

Then download the SURFconext metadata signing certificate. The wget command downloads the certificate and writes is to a filename of your choice, e.g:

...

from https://metadata.surfconext.nl/

...

idp-metadata

...

.xml (production) or https://metadata.test.surfconext.nl/idp-metadata.xml (test).

Code Block
wget https://metadata.surfconext.nl/idp-metadata.xml --output-document=/etc/shibboleth/surfconext-idp-metadata.xml

...

Edit /etc/shibboleth/shibboleth2.xml and make the following changes:

Change the entityID in the <ApplicationDefaults> section to the URI of your SP. This defines the name by which SURFconext will refer to your SP. The value should be a proper URL, for example
Code Block
<ApplicationDefaults entityID="https://mfspmysp.gadgetsexample.surfconext.nlorg/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
In the <ApplicationDefaults> section, add the names of the key and certificate file that you have just created.
Code Block
<CredentialResolver type="File" key="shib.key" certificate="shib.crt"/>

Inside the <ApplicationDefaults> section, add a MetadataProvider for SURFconext. This This tells Shibboleth where to find SURFconext's SAML metadata:. In this step we use the meatadata that you just downloaded

Code Block

controls	true
language	xml
theme	Default
	xml
theme	Default

      <MetadataProvider type="XML"
                        url="https://metadata.surfconext.nl/idp-metadata.xml<MetadataProvider type="XML"
                        backingFilePathpath="metadata-surfconext/etc/shibboleth/surfconext-idp-metadata.xml"
                        reloadInterval="7200">
        <MetadataFilter type="Signature" certificate="surfconext.pem"/>
      </MetadataProvider>

Inside the <ApplicationDefaults> section should be a <Sessions> section. In there, add a Single Sign-On entry for SURFconext. This tells Shibboleth that SURFconext users can use Single Sign-On and that authentication information with SURFconext should be exchanged using SAML2.
Code Block
language xml
<SSO entityID="https://engine.surfconext.nl/authentication/idp/metadata">SAML2</SSO>

Inside the <ApplicationDefaults> section should be a <Sessions> section. In that section. a MetadataGenerator handler should be defined. Here, you need to add additional information about your service and your organization. Edit the section to look like this:

Code Block

language	xml

 <Handler type="MetadataGenerator" Location="/Metadata" signing="true">
    <mdui:UIInfo>
        <mdui:DisplayName xml:lang="nl">Voorbeelddienst</mdui:DisplayName>
        <mdui:DisplayName xml:lang="en">Example Service</mdui:DisplayName>
        <mdui:Description xml:lang="nl">Een mooie voorbeelddienst om te laten zien hoe Shibboleth werkt</mdui:Description>
        <mdui:Description xml:lang="en">A nice example Service to show how to work with Shibboleth and SURFconext</mdui:Description>
        <mdui:Logo height="300" width="500">https://plaatjes.example.com/media/plaatje.png</mdui:Logo>
    </mdui:UIInfo>
    <md:Organization>
        <md:OrganizationName xml:lang="nl">Voorbeeld BV</md:OrganizationName>
        <md:OrganizationName xml:lang="en">Example BV</md:OrganizationName>
        <md:OrganizationDisplayName xml:lang="nl">Voorbeeld</md:OrganizationDisplayName>
        <md:OrganizationDisplayName xml:lang="en">Example</md:OrganizationDisplayName>
        <md:OrganizationURL xml:lang="nl">http://www.example.org</md:OrganizationURL>
        <md:OrganizationURL xml:lang="en">http://www.exampler.org/en</md:OrganizationURL>
    </md:Organization>
    <md:ContactPerson contactType="support">
        <md:GivenName>Piet</md:GivenName>
        <md:SurName>Jansen</md:SurName>
        <md:EmailAddress>piet.Jansen@example.org</md:EmailAddress>
    </md:ContactPerson>
    <md:ContactPerson contactType="technical">
        <md:GivenName>Klaas</md:GivenName>
        <md:SurName>Jansen</md:SurName>
        <md:EmailAddress>klaas.jansen@example.org</md:EmailAddress>
    </md:ContactPerson>
    <md:ContactPerson contactType="administrative">
        <md:GivenName>Jans</md:GivenName>
        <md:SurName>Jansen</md:SurName>
        <md:EmailAddress>jans.jansen@example.org</md:EmailAddress>
    </md:ContactPerson>
</Handler>

Additionally, make sure the md and mdui xml namespaces are defined in the <SPConfig> tag on the top of shibboleth.xml:

Code Block

<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:mdui="urn:oasis:names:tc:SAML:metadata:ui"
    clockSkew="180">

...

Code Block

controls	true
language	xml
theme	Default

<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
  xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  clockSkew="180">

  <ApplicationDefaults entityID="https://mfsp.gadgets.surfconext.nl/shibboleth"
             REMOTE_USER="eppn persistent-id targeted-id">
    <Sessions lifetime="28800" timeout="3600" checkAddress="false" redirectLimit="exact" relayState="ss:mem" handlerSSL="false">
      <SSO entityID="https://engine.surfconext.nl/authentication/idp/metadata">SAML2</SSO>
      <Logout>SAML2 Local</Logout>
      <Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
      <Handler type="Status"            Location="/Status"/>
      <Handler type="Session"           Location="/Session" showAttributeValues="false"/>
      <Handler type="DiscoveryFeed"     Location="/DiscoFeed"/>
    </Sessions>
    <Errors supportContact="root@localhost" logoLocation="/shibboleth-sp/logo.jpg" styleSheet="/shibboleth-sp/main.css"/>
    <MetadataProvider type="XML" uripath="https:/etc/metadata.surfconext.nl/shibboleth/surfconext-idp-metadata.xml" backingFilePath="metadata-surfconext.xml" reloadInterval="7200">
      <MetadataFilter type="RequireValidUntil" maxValidityInterval="172800"/>
      <MetadataFilter type="Signature" certificate="surfconext.pem"/>
    </MetadataProvider></MetadataProvider>      
    <AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/>
    <AttributeResolver type="Query" subjectMatch="true"/>
    <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
    <CredentialResolver type="File" key="shib.key" certificate="shib.crt"/>
  </ApplicationDefaults>
  <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
  <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
</SPConfig>

...

Page tree

Versions Compared

Old Version 31

New Version Current

Key