Recipe for connecting 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 3.x. Note that this is a complete, but minimal configuration; real world installations may 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 Shibboleth package for your OS, either from Shibboleth directly or a package from your OS vendor (e.g. the security/shibboleth-sp port on FreeBSD)

  3. You'll need a new private key and self-signed X.509 certificate. The Shibboleth package may have generated them automatically (check for sp-key.pem or sp-encrypt-key.pem and sp-signing-key.pem), or you may need to 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 or /usr/local/etc/shibboleth (as appropriate to your OS). Make a note of the filenames (changeme.key and changeme.crt) for later.

  4. Configure your SP to download Rhodes' IdP's metadata from https://login.ru.ac.za/idp/shibboleth. Ideally you should do this automatically with a file-backed HTTP metadata provider in shibboleth2.xml. For example:

    <MetadataProvider type="XML" 
    url="https://login.ru.ac.za/idp/shibboleth"
    backingFilePath="rhodes-metadata.xml"
    maxRefreshDelay="7200">
</MetadataProvider>

  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>, the self-signed SSL certificates in <CredentialResolver> and the supportContact in <Errors>. 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 service 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. Your Shibboleth package may have provided an example configuration for configuring Apache which can be included into your Apache configuration. At a minimum, the configuration would load the mod_shib module, have /Shibboleth.sso handled by mod_shib and protect at least one directory like this:

    <Location /secure>
    AuthType shibboleth
    ShibRequireSession On
    require shib-session
</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 canonical 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.