Recipe for connecting Ubuntu Linux/Apache to login.ru.ac.za

Rhodes' identity provider service makes use of SAML2 to provide a secure way of verifying identity. Our IdP is based on SimpleSAMLphp.

Shibboleth is a brand of SAML2 software. Most notably, it includes a native service provider that is tightly integrated with the Apache web server.

The following is a step-by-step recipe for configuring a Shibboleth service provider to make use of Rhodes' IdP. It was correct at the time of writing, and refers to Shibboleth Native SP 2.5.x running on Ubuntu Linux. Note that this is a complete, but minimal configuration; real world installations will need to be a bit more complex.

And now the recipe…

  1. Choose a unique entityID for your service provider entity. At Rhodes you should use either the URL of your web site on www.ru.ac.za or the canonical hostname of your web server as a URL. By convention, your URL should end with /shibboleth-sp (for example http://www.ru.ac.za/informationtechnology/shibboleth-sp). This URL does not have to actually exist, it's just a way of ensuring uniqueness and consitency. Make a note of this for later.

  2. Install the libapache2-mod-shib2 package from the Ubuntu apt repository. This will install shibboleth-sp (shibd & mod_shib) version 2.5.x

  3. Use openssl to generate a new private key and a self-signed X.509 certificate. Do not re-use an existing certificate, and do not used a certificate signed by a third party! These should be saved in /etc/shibboleth. Make a note of the filenames (changeme.key and changeme.crt) for later.

  4. Download Rhodes' IdP's metadata from https://login.ru.ac.za/idp/shibboleth and save it as /etc/shibboleth/metadata.xml. Make some plan to keep this updated. (Ideally you should do this automatically with a file-backed HTTP metadata provider in shibboleth2.xml).

  5. Edit the shibboleth2.xml configuration file to suite your needs. In particular, you'll need to change the entityID in <ApplicationDefaults> (should be your entity ID from step 1.), the entityID in <SSO> (should be https://login.ru.ac.za/idp/shibboleth), the <MetadataProvider>, and the SSL certificates in <CredentialResolver>. It is also a good idea to remove SAML1 from within the <SSO> stanza to disable the use of SAML1.

  6. Now configure shibboleth to handle any identity attributes you may need by editing /etc/shibboleth/attribute-map.xml. A complete list of attributes the IdP supports is available as is a sample attribute-map.xml. (Note that not all these attributes may be made available to your particular service provider.)

  7. Optionally edit the error message files (/opt/shibboleth/*.html) to customise them for your site layout. Note that you should direct users to yourself (not the IT&S Division) for support with problems relating to your service provider.

  8. Restart shibboleth-sp using /etc/init.d/shibd restart

  9. Ideally you should configure Apache to only serve your application over a secure (SSL) connection. How do do this is beyond the scope of this document, but is well documented elsewhere. Do not use the same certificate as your shibboleth-sp. If you need a certificate, see here.

  10. Configure Apache to protect your resources. At a minimum, the configuration would look like:

    <Location /secure>
    AuthType shibboleth
    ShibRequireSession On
    require valid-user
    </Location>

  11. Send the IT&S Division a request to add a new SAML service provider. The request should include the following information:

    • the name of the person responsible for maintaining the shibboleth service provider;
    • the department or division they represent;
    • a brief description of the application you're trying to protect;
    • the cannonical end-user URL of the application that's going to be protected by login.ru.ac.za;
    • your SP's entityID; and
    • your SP's metadata. The basic metadata can often be downloaded from https://your.server/Shibboleth.sso/Metadata, however you'll need to review the file before sending it to us.
    This information will be used to establish a trust relationship between the service provider and IdP.

  12. Once your service provider's meta data has been added to the IdP, test your application works in the way you expect.