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
- Setting up your SP in Shibboleth
- Setting up Apache
- Configuring the SP in OpenConext
- Setting up test page
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!