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).

...

In this document, we will set up Shibboleth 2 for use with Apache and connect it to SURFconext. We use a recent Debian GNU/Linux system, but instructions should carry over to other UNIX-like system pretty straightforwardly. The Shibboleth Wiki describes installation of Shibboleth on other systems and platforms more extensively.

...

Info
A security checklist for Shibboleth can be found here.

Setting up Shibboleth

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

Warning

title	SURFconext Metadata

Take note that the metadata and the metadata locations used for the test and production environments of SURFconext differ. Use them accordingly:

Test: https://metadata.test.surfconext.nl/idp-metadata.xml
Production: https://metadata.surfconext.nl/idp-metadata.xml

Setting up Shibboleth

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

Code Block

controls	true
theme	Default

<VirtualHost _default_:443>

Code Block

controls	true
theme	Default

<VirtualHost _default_:443>
        Servername mfsp.gadgets.surfconext.nl
        ServerAdmin bas.zoetekouw@surfnet.nl

        DocumentRoot /var/www/mfsp
        <Directory /Servername mysp.example.org
        ServerAdmin server-admin@example.org

        DocumentRoot /var/www/mysp
        <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 2. In In Debian and Ubuntu, the package is called libapache2called libapache2-mod-shib2, and simply apt-getting will work fine. However, this will currently install an older version, non-supported version of Shibboleth SP (namely version 2.4.3). If you want a newer version (currently 2.5.1), you should add a different Ubuntu repository from SWITCH. Follow the instructions here.Note that in this tutorial, we assume that Shibboleth Service Provider v2.4.3 is used. Older versions of Shibboleth use different options in the configuration file. The Shibboleth developers provide packages for Redhat Linux, CentOS, SUSE, and OpenSUSE. Installation instructions for these platforms can be found at the Shibboleth wiki.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 shib2a2enmod 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.12.1" XML-Tooling-C="13.40.23" XML-Security-C="12.60.12" OpenSAML-C="23.40.30" Shibboleth="23.40.3"/>
  <NonWindows sysname="Linux" nodename="mfspmysp" release="23.610.37-1-6860-862.14.4.el7.x86_64" version="#1 SMP TueWed Sep Feb26 15 18:2112:5011 UTC 20112018" 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 eloborately elaborately at https://wiki.shibboleth.net/confluence/display/SHIB2SP3/NativeSPGettingStartedGettingStarted, but the instructions below should get you up to speed quickly.

...

Start by generating a new SSL RSA key pair and a self signed certificate. This This key pair will be is used by Shibboleth to sign its SAML metadata and 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

...

The public and private keys should be placed in /etc/shibboleth. Protect

Change owner of the private key file against unauthorized access with the following commandso shibd can read it:

Code Block

language	bash

chown _shibdchmod 600 /etc/shibboleth/shib.key

Then download the SURFconext signing certificate:metadata from https://metadata.surfconext.nl/idp-metadata.xml (production) or https://metadata.test.surfconext.nl/idp-metadata.xml (test).

Code Block
wget https://enginemetadata.surfconext.nl/authentication/idp/certificate -O idp-metadata.xml --output-document=/etc/shibboleth/surfconext-idp-metadata.pemxml

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"/ REMOTE_USER="eppn persistent-id targeted-id">

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
theme	Default

      <MetadataProvider type="XML"
                        uri="https://engine.surfconext.nl/authentication/idp/metadata<MetadataProvider type="XML"
                        backingFilePathpath="metadata-surfconext/etc/shibboleth/surfconext-idp-metadata.xml"
                        reloadInterval="7200">
        <MetadataFilter type="RequireValidUntil" maxValidityInterval="172800"/>
         <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="/DiscoFeedStatus"/>
    </Sessions>
  <Handler  <Errors supportContacttype="root@localhostSession" logoLocation           Location="/shibboleth-sp/logo.jpgSession" styleSheetshowAttributeValues="/shibboleth-sp/main.cssfalse"/>
    <MetadataProvider type="XML" uri="https://engine.surfconext.nl/authentication/idp/metadata" backingFilePath="metadata-surfconext.xml" reloadInterval="7200">
  <Handler type="DiscoveryFeed"     Location="/DiscoFeed"/>
    </Sessions>
    <Errors <MetadataFilter type="RequireValidUntil" maxValidityInterval="172800supportContact="root@localhost" logoLocation="/shibboleth-sp/logo.jpg" styleSheet="/shibboleth-sp/main.css"/>
    <MetadataProvider  <MetadataFilter type="SignatureXML" certificatepath="/etc/shibboleth/surfconext-idp-metadata.pemxml"</>
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>

...

Code Block
2011-10-17 13:49:15 INFO OpenSAML.MetadataProvider.XML : loaded XML resource (https://enginemetadata.surfconext.nl/authentication/idp/-metadata.xml)

Setting up Apache

Now we need to setup Apache to require Shibboleth-based authentication. Add the following entry to your apache vhost configuration:

...

to enable Shibboleth-authentication for all files under https://mfsp.gadgets.surfconext.nl/secure. See the Shibboleth wiki for more information about the available configuration options.
If you visit anything under https://mfsp.gadgets.surfconext.nl/secure., Apache and Shibboleth should now try to authenticate using the SURFconext IdP. As your SP is not yet registered with SURFconext, you should get the following error message:

...

At this point you should contact support@surfconext.nl and request a login for the SP registration formDashboard. With this Self Service form dashboard you will be able to configure a SP on the Connect test environment of SURFconext.

Details which have to be filled out comprise

the name of your service as will be presented to endusers;
a description of the functionality your SP offers;
a link to your SP's metadata (e.g, https://mfsp.gadgets.surfconext.nl/Shibboleth.sso/Metadata);a list of IdPs (institutions) that will need access to your SP;
A name and email address of a technical contact person responsible for the service;
the attrubtes you wish to use for this service.

...

Code Block

    [Shib-Application-ID] => default
    [Shib-Session-ID] => _51601ddffbb5537cc24295a8f5804d11
    [Shib-Identity-Provider] => https://engine.surfconext.nl/authentication/idp/metadata
    [Shib-Authentication-Instant] => 2011-11-02T12:36:03Z
    [Shib-Authentication-Method] => urn:oasis:names:tc:SAML:2.0:ac:classes:Password
    [Shib-AuthnContext-Class] => urn:oasis:names:tc:SAML:2.0:ac:classes:Password
    [Shib-Session-Index] => 82a98744094c34a839f91800239d7a10
    [Shib-HomeOrg] => surfnet.nl
    [Shib-commonName] => Bas Zoetekouw
    [Shib-displayName] => Bas Zoetekouw
    [Shib-eduPersonPN] => bas@surfnet.nl
    [Shib-email] => Bas.Zoetekouw@surfnet.nl
    [Shib-givenName] => Bas
    [Shib-surName] => Zoetekouw
    [Shib-uid] => bas
    [Shib-userStatus] => member
    [Shib-memberOf] => urn:collab:org:surf.nl
    [Shib-user] => urn:collab:person:surfnet.nl:bas
    [persistent-id] => 8e01d4e3965255f4e3beeeae42e84f357fa87a84

...

That's all folks!

At this point, your SP is successfully coupled to SURFconext. Congratulations!

Page tree

Versions Compared

Old Version 18

New Version Current

Key

Setting up Shibboleth

Setting up Shibboleth

Setting up Apache

That's all folks!