Installing Shibboleth SP for Apache

These notes apply to Ubuntu or Debian, but should be adaptable to other Linux distributions.

For the configuration below, we assume an Apache server on FQDN ssp.unit.ox.ac.uk (fully qualified domain name) will provide a Shibboleth protected service at location: https://ssp.unit.ox.ac.uk/my-service/

Remember to change to your own FQDN in the configurations below!

To get a minimal Shibboleth/Apache2 host running, we first install and configure a basic secure (https) Apache server and then "protect" the my-service site with Shibboleth authentication.

Expand All

Below, we assume that the FQDN ssp.unit.ox.ac.uk has already been registered as a DNS entry. You will need to do this, as https://localhost/my-service/ will not work, even just for testing.

You'll also need to obtain a valid Certificate Authority signed digital certificate and install that along with the openssl package. See Certificates for more on the certificate service.

For testing however, you could also just use the default certificate (/etc/ssl/certs/ssl-cert-snakeoil.pem). See the Apache2 configuration files and especially /etc/apache2/sites-available/default-ssl for detailed instructions on correctly configuring a secure https host.

Install Apache2 and enable the ssl modules:

sudo apt-get install apache2
sudo a2enmod ssl
sudo a2ensite default-ssl

The next step is to create a directory which will contain (at least) the main index.html page for the protected site. Depending on your system version, these should be under /var/www for older versions or /var/www/html for more recent versions. Check the DocumentRoot entry in /etc/apache2/sites-available/default-ssl.

Create the site directory:
sudo mkdir /var/www/my-service

or depending on DocumentRoot,

sudo mkdir /var/www/html/my-service

Create an index.html file, say /var/www/html/my-service/index.html, to contain something like:

<html>
<body>
<h1>My Secure Site</h1>
</body>
</html>

Next, edit /etc/apache2/sites-available/default-ssl and set/add the following within the VirtualHost section:

       ServerName ssp.unit.ox.ac.uk # use your own FQDN

and add:

        Alias /my-service/ /var/www/html/my-service/
         <Location /my-service/>
                 # nothing here for now
         </Location>

Now, you can test that your basic secure site works correctly:

sudo service apache2 restart

From a browser, check that <span>https</span>://ssp.unit.ox.ac.uk/my-service/ opens the above index.html page.

The next step is to install a Network Time Protocol (NTP) server. This is needed to ensure correct time synchronisation between your host and other servers participating in the federated network. It is also used in preventing "replay" authentication attack attempts.

sudo apt-get install ntp

Edit /etc/ntp.conf and add the line:

server ntp.ox.ac.uk

Next we install Shibboleth, which is implemented as an Apache module:

sudo apt-get install libapache2-mod-shib2
sudo a2enmod shib2

Set up a Shibboleth certificate (n.b. this is different to the Apache certificate). On Debian and its derivatives, run the command:

sudo shib-keygen -h ssp.unit.ox.ac.uk

On other Linux distributions:

sudo /etc/shibboleth/keygen.sh -f -h ssp.unit.ox.ac.uk -e https://ssp.unit.ox.ac.uk/shibboleth -o /etc/shibboleth -u shibd -g shibd

If you are running version 3 of the Shibboleth SP software (e.g. Debian buster or the RPM packages from the Shibboleth Consortium), you will need to generate separate encryption and signing certificates using:

sudo shib-keygen -h ssp.unit.ox.ac.uk -e https://ssp.unit.ox.ac.uk/shibboleth -n sp-encrypt
sudo shib-keygen -h ssp.unit.ox.ac.uk -e https://ssp.unit.ox.ac.uk/shibboleth -n sp-signing

on Debian, or:

sudo /etc/shibboleth/keygen.sh -f -h ssp.unit.ox.ac.uk -e https://ssp.unit.ox.ac.uk/shibboleth -o /etc/shibboleth -u shibd -g shibd -n sp-encrypt
sudo /etc/shibboleth/keygen.sh -f -h ssp.unit.ox.ac.uk -e https://ssp.unit.ox.ac.uk/shibboleth -o /etc/shibboleth -u shibd -g shibd -n sp-signing

 

elsewhere.

Check the certificate as follows:

openssl x509 -text -noout -in /etc/shibboleth/sp-cert.pem

(or if you have separate encryption and signing certificates you will need to substitute sp-cert.pem with sp-encrypt-cert.pem & sp-signing-cert.pem)

You should see something like:

Certificate:
     Data:
         Version: 3 (0x2)
         Serial Number: 14443061105682691989 (0xc8700f8d917a3795)
     Signature Algorithm: sha1WithRSAEncryption
         Issuer: CN=ssp.unit.ox.ac.uk
         Validity
             Not Before: May  6 13:43:49 2013 GMT
             Not After : May  4 13:43:49 2023 GMT
         Subject: CN=ssp.unit.ox.ac.uk
         Subject Public Key Info:
             Public Key Algorithm: rsaEncryption
                 Public-Key: (2048 bit)
                 Modulus:
                     <<..Hex Numbers..>>
                 Exponent: 65537 (0x10001)
         X509v3 extensions:
             X509v3 Subject Alternative Name:
                 DNS:ssp.unit.ox.ac.uk
             X509v3 Subject Key Identifier:
                 <<..Hex Numbers..>>
     Signature Algorithm: sha1WithRSAEncryption
                 <<..Hex Numbers..>>

Check the certificate fingerprint(s) as follows (you will need to confirm this with IAM later as part of the registration process):

Single certificate:

openssl x509 -fingerprint -in /etc/shibboleth/sp-cert.pem -sha256

Separate encryption and signing certificates :

openssl x509 -fingerprint -in /etc/shibboleth/sp-encrypt-cert.pem -sha256
openssl x509 -fingerprint -in /etc/shibboleth/sp-signing-cert.pem -sha256

Now edit /etc/apache2/sites-available/default-ssl again and add the entries under Location:

        Alias /my-service/ /var/www/html/my-service/
         <Location /my-service/>
                 AuthType shibboleth
                 ShibRequestSetting requireSession 1
                 Require valid-user
         </Location>

Recommended if you are new to this. Experienced users can skip to the next section.

First, make a copy of your (installed) shibboleth2.xml config file for restoring later.

sudo cp /etc/shibboleth/shibboleth2.xml /etc/shibboleth/shibboleth2.orig.xml

Next, add the following to shibboleth2.xml:

<MetadataProvider type="XML" validate="true"
         url="https://samltest.id/saml/idp"
         backingFilePath="SAMLtest.xml">
     <!-- Replace "url=" with "uri=" on Shibboleth SP version 2.x -->
      <!-- You should always check the signature and freshness of remote
              metadata.  It's commented out until you get the basics working.
           <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
           <MetadataFilter type="Signature" certificate="signet.crt" verifyBackup="false"/>
         -->
 </MetadataProvider>

Comment out the sample SSO element:

       <!--SSO entityID="https://idp.example.org/idp/shibboleth"
                  discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
               SAML2 SAML1
             </SSO-->

and add a new SSO element including the SAMLTEST IdP's entityID:

            <SSO entityID="https://samltest.id/saml/idp" discoveryProtocol="SAMLDS"

                discoveryURL="https://wayf.ukfederation.org.uk/DS"> SAML2 SAML1 </SSO>

Edit the ApplicationDefaults element to include the entityID of your Service Provider:

       <ApplicationDefaults entityID="https://ssp.unit.ox.ac.uk/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

Restart both shibd and apache2:

sudo service shibd restart
sudo service apache2 restart

Visit https://ssp.unit.ox.ac.uk/Shibboleth.sso/Metadata and download the file as ssp.unit.ox.ac.uk.Metadata.xml. Open the file and check that it contains the certificate key and that the entityID is entityID="https://ssp.unit.ox.ac.uk/shibboleth".

Then upload this file to https://samltest.id/upload.php to register the SP. Visiting https://ssp.unit.ox.ac.uk/my-service/ should now redirect to the TestShib IDP login page.

If you are using the TestShib config, restore the default configuration from backup

sudo cp /etc/shibboleth/shibboleth2.orig.xml /etc/shibboleth/shibboleth2.xml

Otherwise, take a backup of your current config:

sudo cp /etc/shibboleth/shibboleth2.xml /etc/shibboleth/shibboleth2.backup.xml

Edit the /etc/shibboleth/shibboleth2.xml file as follows, or see the attached shibboleth2.xml.d.txt file for an example.

Edit the ApplicationDefaults element to include the entityID of your Service Provider:

       <ApplicationDefaults entityID="https://ssp.unit.ox.ac.uk/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

Edit the Sessions element to use SSL (avoids warning messages in the logs):

       <Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https" redirectLimit="exact">

Comment out the sample SSO element:

        <!--SSO entityID="https://idp.example.org/idp/shibboleth"
                  discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF">
               SAML2 SAML1
             </SSO-->

and add a new SSO element including the Oxford IdP's entityID:

            <SSO entityID="https://registry.shibboleth.ox.ac.uk/idp" discoveryProtocol="SAMLDS"

                discoveryURL="https://wayf.ukfederation.org.uk/DS"> SAML2 SAML1 </SSO>

Set an appropriate support contact in the Errors element:

        <Errors supportContact="it-support@unit.ox.ac.uk"
             helpLocation="/about.html"
             styleSheet="/shibboleth-sp/main.css"/>

Add a MetadataProvider element to use the UK Federation metadata:

        <MetadataProvider type="XML" uri="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
              backingFilePath="ukfederation-metadata.xml" reloadInterval="14400">
                 <MetadataFilter type="RequireValidUntil" maxValidityInterval="2592000"/>
                 <MetadataFilter type="Signature" certificate="ukfederation.crt"/>
         </MetadataProvider>

If you are running Shibboleth SP version 3, replace "uri=" with "url=". Save the modified /etc/shibboleth/shibboleth2.xml file.

Get the UK Federation certificate:

sudo wget -O /etc/shibboleth/ukfederation.crt http://metadata.ukfederation.org.uk/ukfederation.pem

Check the Fingerprint:

openssl x509 -fingerprint -in /etc/shibboleth/ukfederation.crt -sha256

and then contact the Federation Helpdesk http://www.ukfederation.org.uk/content/Documents/UKFederationHelpdesk to verify it.

Finally, the SP will need to be registered with IT Services (IAM) by completing the Register a SAML Service Provider OSM Service Request.

IAM will call you up and ask you to confirm the fingerprint of your key. You get this by running the command:

openssl x509 -fingerprint -in /etc/shibboleth/sp-cert.pem -sha256

 

IAM will then register your service provider with the UK Access Management Federation http://www.ukfederation.org.uk/ The Federation will add your SP metadata to their metadata. You can see when this has been done by inspecting the Federation's metadata http://metadata.ukfederation.org.uk/ukfederation-metadata.xml. IT Services pull down this metadata regularly (using the MDQ protocol). Once the Oxford IdP has pulled down the metadata, then communications between the Oxford IdP and your SP should work.

If required for your application, IAM can release attributes from Oak LDAP as SAML assertions. These can be presented to your web application as headers or environment variables (as configured in the attribute-map.xml and attribute-filter.xml files). To request attribute release, please complete the SAML SP Attribute Release in IT self service.

Access to the location can be restricted to individuals or groups by a variety of mechanisms:

 

Allow access only to Oxford users

(Apache 2.4 configuration):

       <Location /my-service/>
                AuthType shibboleth
                ShibRequestSetting requireSession 1
                Require shib-attr affiliation ~ ^.+@ox\.ac\.uk$
        </Location>

 

Allow access to specified users

(Apache 2.4 configuration):

       <Location /my-service/>
                AuthType shibboleth
                ShibRequestSetting requireSession 1
                <RequireAny>
                        Require user unit1234@ox.ac.uk
                        Require user unit5678@ox.ac.uk
                </RequireAny>
        </Location>

 

Allow access to users in a particular unit

First, uncomment the following lines in /etc/shibboleth/attribute-map.xml before restarting the shibd daemon:

    <Attribute name="urn:mace:dir:attribute-def:eduPersonPrimaryOrgUnitDN" id="primary-orgunit-dn"/>
    <Attribute name="urn:mace:dir:attribute-def:eduPersonOrgUnitDN" id="orgunit-dn"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.8" id="primary-orgunit-dn"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.4" id="orgunit-dn"/>

Find the dn for your unit. You can see a list of all unit DNS by running the command:

ldapsearch -x -H ldaps://ldap.oak.ox.ac.uk -b ou=units,dc=oak,dc=ox,dc=ac,dc=uk dn

(Authentication is not required to run this command.)

Next add the following to your Apache 2.4 configuration (adjust the Require shib-attr orgunit-dn line as appropriate):

       <Location /my-service/>
                AuthType shibboleth
                ShibRequestSetting requireSession 1

               <RequireAll>

                       Require shib-attr affiliation ~ ^.+@ox\.ac\.uk$
                        Require shib-attr orgunit-dn oakUnitCode=itserv,ou=units,dc=oak,dc=ox,dc=ac,dc=uk

               </RequireAll>
        </Location>

 

Using one Service Provider for multiple virtual hosts

Please refer to Using one Shibboleth Service Provider for multiple virtual hosts.

Shibboleth logs to /var/log/shibboleth/

To test the configuration, run :

sudo shibd -t

If all is well, you should see:

overall configuration is loadable, check console for non-fatal problems

You can see what attributes are being picked up by Shibboleth at https://ssp.unit.ox.ac.uk/Shibboleth.sso/Session. If you get the message A valid session was not found. then you need to go to a Shibboleth protected URL and log in to get a session.

On some recent Linux distributions (Ubuntu 16.04, for example), systemd may kill the Shibboleth daemon and restart it due to the initial metadata load taking too long.  If this happens to you, create the file /etc/systemd/system/shibd.service.d/override.conf and add the following contents:

[Service]

TimeoutStartSec=600

After creating the file, you need to reload the systemd daemon for it to notice the new file:

sudo systemctl daemon-reload

Once done, this will increase the timeout to 10 minutes.  Afterwards, stop and restart the daemon:

sudo service shibd stop; sudo service shibd start

An alternative option for SPs that only allow access from Oxford users is to use IdP-specific metadata from the UK Federation.  First, get the UK Federation MDQ certificate:

sudo wget -O /etc/shibboleth/ukfederation-mdq.crt http://mdq.ukfederation.org.uk/ukfederation-mdq.pem

Check the fingerprint:

openssl x509 -fingerprint -in /etc/shibboleth/ukfederation-mdq.crt -sha256

and then contact the Federation Helpdesk http://www.ukfederation.org.uk/content/Documents/UKFederationHelpdesk to verify the MDQ certificate fingerprint.

Once the fingerprint has been verified, replace the MetadataProvider element in /etc/shibboleth/shibboleth2.xml with the following:

        <MetadataProvider type="XML" uri="http://mdq.ukfederation.org.uk/entities/https:%2F%2Fregistry.shibboleth.ox.ac.uk%2Fidp"
              backingFilePath="ukfederation-metadata.xml" reloadInterval="14400">
                 <MetadataFilter type="RequireValidUntil" maxValidityInterval="2592000"/>
                 <MetadataFilter type="Signature" certificate="ukfederation-mdq.crt"/>
         </MetadataProvider>

Again, if you are running Shibboleth SP version 3, replace "uri=" with "url=" in the above configuration.  Save the modified /etc/shibboleth/shibboleth2.xml file and restart the shibd service:

sudo service shibd stop;

sudo service shibd start

More information on this option is available from the UK Federation's MDQ help pages.

For some use cases, it is desirable to work with the "descoped" SSO username ("unit1234" as opposed to "unit1234@ox.ac.uk").  The Shibboleth SP can be configured to remove the scope automatically by adding the following configuration entries to /etc/shibboleth/shibboleth2.xml:

Immediately inside the <SPConfig> element, but after any <Extensions> elements, add the following:

       <OutOfProcess>
            <Extensions>
                <Library path="plugins.so" fatal="true"/>
           </Extensions>
       </OutOfProcess>

On version 3, the <OutOfProcess> element already exists as:

       <OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a" />

This should be replaced with:

       <OutOfProcess tranLogFormat="%u|%s|%IDP|%i|%ac|%t|%attr|%n|%b|%E|%S|%SS|%L|%UA|%a">
            <Extensions>
                <Library path="plugins.so" fatal="true"/>
           </Extensions>
       </OutOfProcess>

Next, add eppn-descoped to the REMOTE_USER attribute of the <ApplicationDefaults> element:

       <ApplicationDefaults entityID="https://ssp.unit.ox.ac.uk/shibboleth" REMOTE_USER="eppn-descoped eppn persistent-id targeted-id">

(On version 3, the <ApplicationDefaults> element will also contain a cipherSuites attribute.  This should be kept.)

Finally, find the line:

        <!-- Default filtering policy for recognized attributes, lets other data pass. -->

and immediately above it, add the following:

        <AttributeResolver type="Transform" source="eppn">
            <Regex match="^(.+)@ox.ac.uk$" dest="eppn-descoped">$1</Regex>
        </AttributeResolver>

Restart both shibd and apache2:

sudo service shibd restart;
sudo service apache2 restart

This configuration will descope usernames if (and only if) the user is logging into the SP via an Oxford IdP.

Get support


If you cannot find the solution you need here then we have other ways to get IT support

Get IT support