Skip to McMaster Navigation Skip to Site Navigation Skip to main content
McMaster Logo McMaster logo

Configuring The Shibboleth SP

Basic familiarity and ability to read and edit XML files with a text editor is a requirement to understand this section.

Server Preparation and Installation

      1. Designate a system to be set up as your SP Shibboleth server.This server should be hosted in an appropriate environment that follows recommended practices around security and maintenance protocols.
      2. Open firewall ports, if needed. Ports 80 and 443 must be open to inbound traffic, and 8443 must be open for outbound traffic.

    For Linux users, notice that currently supported distributions of Linux are listed on the Linux Install page of the Shibboleth Project site. Be aware of the Shibboleth warning regarding SELinux.

    1. The supported distributions of Linux can be installed from RPM via Yum. Installation instructions are also provided to build from SRPM or to build from Source, but doing so is not recommended.
    2. As McMaster Identity Providers are running at Version 3.x, it is recommended to choose the SP version within the 3.0.x family, the latest the better.
    3. The installation will build and install an apache module and the shibd daemon.

1. Verify Installation

Before configuring your server, verify that Shibboleth has been properly installed on your server.

      1. Confirm Shibboleth functionality:

        sudo shibd -t

        Which should return a response that ends with:

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

      2. Confirm Apache functionality:

        sudo apache2ctl configtest

        Which should return a response of:

        Syntax OK

      3. Confirm shibd functionality:

        Restart the web server, then navigate to https://my-sp-site.mcmaster.ca/Shibboleth.sso/Session

        This should return a page response of:

        A valid session was not found.

        This message means that Shibboleth has been loaded by the web server and is successfully communicating with the shibd process.

See here for an even more detailed example how to deploy an SP in a Linux Environment. If you need more complete instructions visit the Shibboleth Wiki – Installation page

2. Configuration

Update shibboleth2.xml File

The shibboleth2.xml file will need to be configured for your Service Provider (SP). The file comes with the Shibboleth SP software, and is located by default in /etc/shibboleth.

Refer to a sample shibboleth2.xml file with McMaster specific comments, or follow these instructions to make the appropriate changes to the file to configure it for your SP.

Note Before making changes, save a copy of the original shibboleth2.xml file.

      1. Update the entityID:

        In the ApplicationDefaults element, the entityID value should be updated from entityID=”sp.example.org” to the host name, or a static identifier of your website. The entity ID does not need to resolve to a webpage. Ensure that the DNS name used has been properly registered and linked in DNS.

        In the SessionInitiator element within the ApplicationDefaults element, the entityID there should be updated to the McMaster specific entity ID for your case. The entity IDs for the staging and production environments should be different as they would be using different IdPs.

      2. Update the support contact:
        • In the Errors element, update the supportContact value to a valid email address for the person managing the SP configuration. This email address is used by the IT Security Team to communicate any changes made to the SP owners.
      3. Update the IdP metadata provider:

        Update the MetadataProvider element (as there are 2) by changing the uri value to the McMaster IdP metadata. The metadata address is different for staging and production, so be sure to update it to the appropriate value. Until you have tested, use the staging value.

      4. Save shibboleth2.xml.

Modify httpd.conf

Modify httpd.conf to protect your website. On RedHat/Fedora type distros the configuration file is located by default at /etc/sysconfig/httpd.

      1. Set the appropriate handler in Apache.

        <Location /Shibboleth.sso>
        SetHandler shib
        </Location>

      2. Protect the appropriate content on your site.

        <Location /secure>
        AuthType shibboleth
        ShibtRequestSetting requireSession true
        Require valid-user
        </Location>

Install an X509 certificate

As Shibboleth requires a certificate and key to encrypt and decrypt attribute assertions, an X509 certificate must be installed for it to work. The Service Provider signing certificate (sp-cert.pem) and key (sp-key.pem) were generated in the installation process and do not need to be modified. They are located in the /conf/ directory.

Logging

Two different sets of Shibboleth-related log files are included with the installation.

      1. shibd (shibd.log) logging is located in the /var/log/shibboleth directory and can be configured in the /etc/shibboleth/shibd.logger directory.
      2. apache module (native.log) logging is located in the /var/log/httpd directory and can be configured in the /etc/shibboleth/native.logger directory.

Modify attribute-map.xml

Your SP’s attribute-map.xml file decodes the attributes released by the Identity Provider (IdP). Keep in mind that the default Shibboleth SP attribute-map.xml configuration file will not recognize some of the McMaster specific attributes unless the file is modified.

Refer to the SAML/Shibboleth Attribute Release page, for specifics on attributes available or see below for relevant excerpts from the file.

The ePPN attribute is this section:

<Attribute name=”urn:mace:dir:attribute-def:eduPersonPrincipalName” id=”eppn”>
<AttributeDecoder xsi:type=”ScopedAttributeDecoder”/>
</Attribute>
<Attribute name=”urn:oid:1.3.6.1.4.1.5923.1.1.1.6? id=”eppn”>
<AttributeDecoder xsi:type=”ScopedAttributeDecoder”/>
</Attribute>

The affiliation attribute is this section:

<Attribute name=”urn:mace:dir:attribute-def:eduPersonScopedAffiliation” id=”affiliation”>
<AttributeDecoder xsi:type=”ScopedAttributeDecoder” caseSensitive=”false”/>
</Attribute>
<Attribute name=”urn:oid:1.3.6.1.4.1.5923.1.1.1.9? id=”affiliation”>
<AttributeDecoder xsi:type=”ScopedAttributeDecoder” caseSensitive=”false”/>
</Attribute>

The unscoped affiliation attribute is this section:

<Attribute name=”urn:mace:dir:attribute-def:eduPersonAffiliation” id=”unscoped-affiliation”>
<AttributeDecoder xsi:type=”StringAttributeDecoder” caseSensitive=”false”/>
</Attribute>
<Attribute name=”urn:oid:1.3.6.1.4.1.5923.1.1.1.1? id=”unscoped-affiliation”>
<AttributeDecoder xsi:type=”StringAttributeDecoder” caseSensitive=”false”/>
</Attribute>

The McMaster specific attributes are shown in this section to map the MacID and the email of the person (just samples):

<Attribute name=”urn:mace:dir:attribute-def:uid” id=”uid”/>
<Attribute name=”urn:oid:0.9.2342.19200300.100.1.1? id=”uid”/>
<Attribute name=”urn:oid:0.9.2342.19200300.100.1.3? id=”mail”/>

3. Register Service Provider

Generate SP metadata

Before registering your SP, you must generate your SP metadata:

      1. Restart shibd:

        sudo service shibd stop
        sudo service shibd start

      2. Download your metadata from the server:

        curl -o sample-app-partner-metadata.xml -k https://my-sp-site.mcmaster.ca/Shibboleth.sso/Metadata

        Where my-sp-site.mcmaster.ca is the entityID of your SP configuration.

        Note -o specifies the appropriate filename, and -k ignores any SSL errors.

Contact the UTS IT-Security team

Once you have your SP metadata, submit the file via a UTS Service Desk ticket. Someone from the IT-Security team will contact you when you can begin testing.

Important If you make changes to your metadata at any time, you will need to provide the new version of the metadata file to be loaded again into either test or production.

4. Test Installation

Test SP integration with the IdP server

After the IT-Security team has contacted you and has added your metadata to one of the McMaster IdPs, you can test your SP to ensure it is properly integrated with IdP server. Confirm that you are able to log in with your account or a test account, and that attributes are properly released.

      1. Use the following commands in a protected document in the /secure directory of your SP, or the protected location you set.
        1. If server side includes (SSI) are enabled, use the following:

          <!–#printenv–>

        2. If PHP is enabled, use the following:

          <?php
          phpinfo();
          ?>

      2. Using a web browser, visit the /secure directory (or other protected location) of your SP. You should be prompted to log in, and after logging in, you should see the attributes associated with the account that you used to log in to the secure directory.
      3. If you are prompted to log in, your SP is properly integrated with the staging IdP.
      4. If the appropriate attributes are displayed, attributes are being properly released to your SP and that the attribute-map.xml file is properly configured.

Moving To Production

After your SP passes testing:

Update your shibboleth2.xml file with production IdP values in place of staging values. Also, make sure you update your entityID in the SessionInitiator element, and the metadata source in the MetadataProvider element.

Contact the IT-Security team to schedule the loading up of your production metadata file and to coordinate the move of your application to production.