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

Because Shibboleth functions at the level of the HTTP server, no language-specific configuration is required. Therefore, any web application can use Shibboleth for authentication, regardless whether it is written in PHP, Perl, Java, VB.NET, or C#.NET, etc. In some cases, however, it might be required to use Apache (or IIS) as a reverse proxy to shield the actual web application (which might for example be running on Apache Tomcat). An example setup for this scenario is described elsewhere.

In this document, we will set up Shibboleth 2 for use with Apache and connect it to OpenConext. 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.

In this document, we will show you step by step how to set up an SP.

Set up Shibboleth

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

<VirtualHost _default_:443>
 Servername demo.openconext.org
 ServerAdmin your.email@address.com
 
 
 DocumentRoot /home/user/www/public/
 <Directory />
 Options FollowSymLinks
 AllowOverride None
 </Directory>
 <Directory /home/user/www/>
 Options Indexes FollowSymLinks MultiViews
 AllowOverride None
 </Directory>
 
 
 SSLEngine on
 SSLCertificateFile /etc/ssl/certs/yourhost.crt
 SSLCertificateKeyFile /etc/ssl/private/yourhost.key
</VirtualHost>

Then, install Shibboleth 2. In Red Hat and CentOS this can be done with:

(32-bit OS)

[user]$ yum install shibboleth

(64-bit OS)

[user]$ yum install shibboleth.x86_64

If everything is set up correctly, you should be able to reach https://demo.openconext.org/Shibboleth.sso/Status. This should show Shibboleth status information in XML form.

If you try to access the Shibboleth status page from an external machine and you get a 403 Error, then you have to add your ip-address to the access control list (ACL).

If you use the same machine to access the url as you use to SSH into the OpenConext server, you can get see your ip-address by entering the following command:

[user]$ pinky

Another option is check the native.log file where the ip-addresses are logged that access the status page by using the following command:

[user]$ sudo tail -100f /var/log/httpd/native.log

To add your ip-address to the ACL open the shibboleth2.xml file:

[user]$ sudo vi /etc/shibboleth/shibboleth2.xml

search for the following line and add you ip-address space separated after acl= as shown below:

<!-- Status reporting service. -->

Now, restart shibd and you should see the status page when you navigate to the url above:

[user]$ sudo /etc/init.d/shibd restart

Setting up your SP in Shibboleth

Shibboleth needs to be set up as an SP; the instructions below should get you up to speed quickly.

Start by generating a new SSL key pair. This key pair will be used to sign metadata and SAML messages that are exchanged between OpenConext and your SP.

Navigate to /ect/shibboleth/ and create keys:

[user]$ openssl req -newkey rsa:4096 -new -x509 -days 365 -nodes -text -out shib.crt -keyout shib.key

Protect keys:

[user]$ chmod 600 /etc/shibboleth/shib.key

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

Change the entityID in the section to the URI of your SP.

 <ApplicationDefaults entityID=https://demo.openconext.org/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.

 <CredentialResolver type="File" key="shib.key" certificate="shib.crt"/>

Inside the <ApplicationDefaults> section, add a MetadataProvider for OpenConext. This tells Shibboleth where to find OpenConext SAML metadata:

 <MetadataProvider type="XML"
 uri="https://engine.demo.openconext.org/authentication/idp/metadata”
 backingFilePath="metadata-openconext.xml"
 reloadInterval="7200">
 <MetadataFilter type="RequireValidUntil" maxValidityInterval="172800"/>
</MetadataProvider>

Inside the <ApplicationDefaults> section should be a <Sessions> section. In there, add a Single Sign-On entry for OpenConext. This tells Shibboleth that OpenConext users can use Single Sign-On and that authentication information with OpenConext should be exchanged using SAML2.

<SSO entityID="https://engine.demo.openconext.org/authentication/idp/metadata”>SAML2</SSO>

Now, restart shibd:

[user]$ sudo /etc/init.d/shibd restart

The log under /var/log/shibboleth/ should tell you that it is fetching metadata from OpenConext:

2013-12-04 13:49:15 INFO OpenSAML.MetadataProvider.XML : loaded XML resource https://engine.demo.openconext.org/authentication/idp/metadata)

Setting up Apache

Apache has to be configured so that a specific location requires shibboleth authentication. Edit your Apache Virtual host configuration (probably the manage.conf file under /etc/httpd/conf.d/ )

Add the following code:

 <Location /secure>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  require valid-user
 </Location>

Then restart Apache:

[user]$ sudo /etc/init.d/httpd restart

In your browser, navigate to: https://sp.demo.openconext.org/secure

You should see an OpenConext page with an error message about an Unknown Application.

Configuring the SP in OpenConext

The next step is to add an entry in OpenConext for this new demo SP. First step is to get the Metadata from Shibboleth. Navigate to the following URL and save the metadata.xml

https://sp.demo.openconext.org/Shibboleth.sso/Metadata

Go to http://demo.openconext.org/ and click on the ServiceRegistry tool, log in via the Mujina IdP (admin/secret).

From the Connections tab, select ‘Create connection’, paste the XML in the ‘Create entity from XML’ text field and press the ‘Create’ button. The new connection ‘https://sp.demo.openconext.org’ will appear in the list at the bottom of the page.

Click on the link of that new connection and on the following page change the ‘State’ from ‘Test’ to ‘Production’, then click ‘Save’ (bottom-right).

Click on the ‘Metadata’ tab and put a name in the ‘name:en’ and ‘name:nl’ fields (e.g. ‘Shibboleth SP), then press Save.

Go to the ‘Identity Provider (IdP)’ tab and make sure that the ‘Allow All’ box is checked, if needed check the box and then save it. This ensures that all IdPs that are currently configured in OpenConext can be used to login to our Shibboleth SP. This tab can also be used to restrict the IdPs that can be used to login to (an) SP by only selecting the ones allowed.

Setting up test page

The following php script can be put in the ../public/secure/ directory as defined in the Apache Virtual Hosts configuration file. When you navigate to https://sp.demo.openconext.org/secure/test.php and authenticate successful, the list of attributes that is forwarded by OpenConext is shown.

Save the following script as test.php:

<html>
<head><title>Shibboleth test</title></head>
<body><pre><?php print_r($_SERVER); ?></pre></body>
</html>

The attributes shown can be configured via the file: /etc/shibboleth/attribute-map.xml. If you replace its content with the following, all known attributes are printed on the test.php page.

 <?xml version="1.0"?>
 <Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi=">
 <Attribute name="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" id="persistent-id">
 <AttributeDecoder xsi:type="NameIDAttributeDecoder" formatter="$Name" defaultQualifiers="true"/>
 </Attribute>
 <Attribute name="urn:oid:1.3.6.1.4.1.1076.20.40.40.1" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-user"/>
 <Attribute name="urn:mace:dir:attribute-def:displayName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-displayName"/>
 <Attribute name="urn:mace:dir:attribute-def:sn" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-surName"/>
 <Attribute name="urn:mace:dir:attribute-def:cn" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-commonName"/>
 <Attribute name="urn:mace:dir:attribute-def:givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-givenName"/>
 <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-eduPersonPN"/>
 <Attribute name="urn:mace:dir:attribute-def:mail" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-email"/>
 <Attribute name="urn:mace:terena.org:attribute-def:schacHomeOrganization" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-HomeOrg"/>
 <Attribute name="urn:mace:dir:attribute-def:uid" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-uid"/>
 <Attribute name="urn:oid:1.3.6.1.4.1.1076.20.100.10.10.1" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-userStatus"/>
 <Attribute name="urn:oid:1.3.6.1.4.1.1076.20.100.10.10.2" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-voName"/>
 <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" id="Shib-memberOf"/>
</Attributes>

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