Enabling Interfederation Support for a Shibboleth Service Provider (SP) in SWITCHaai

Table of contents

  1. Introduction
  2. Service Provider Configuration Changes
  3. Adapt Access Control Rules
  4. Adapt Discovery Service
  5. Changes in Resource Registry
  6. Testing
  7. Troubleshooting
  8. References

1. Introduction

This guide describes the steps to enable interfederation support for a Shibboleth 2 Service Provider in the SWITCHaai federation. After the following steps have been successfully applied, users from non-SWITCHaai federations are able to access the resources protected by this SWITCHaai Service Provider. In particular, users from Identity Providers participating in eduGAIN.

Note

This guide assumes that there already is a fully deployed Shibboleth Service Provider 2.x. For general information about the deployment of a Shibboleth Service Provider within the SWITCHaai Federation, please consult the SP Guides section of the SWITCHaai website.

1.1 Process Overview of Enabling Interfederation

The general process to enable interfederation looks as displayed in the graphic below.

SP Interfederation Enabling Process

SWITCHaai Interfederation Access Declaration
Provided your institution has not yet signed the SWITCHaai Interfederation Access Declaration (the entries without a green checkmark in this list of participating institutions), the first step to enable interfederation support is to inform SWITCH about the intentions and plans of your organisation to enable interfederation support. SWITCH then will send you the "SWITCHaai Interfederation Access Declaration". After understanding, signing and returning that document, SWITCH will enable interfederation support for the signing organisation.
Adapt Service Provider Configuration
In order accept identity assertions from Identity Providers not being part of the SWITCHaai federation, the Service Provider must load metadata from these Identity Providers. It also must be configured to handle the attributes that these Identity Providers might release about a user. The necessary steps are described below in the section Service Provider Configuration Changes
Adapt Access Control Rules
In order to allow users from non-SWITCHaai Identity Providers to access your resource the access control rules might have to be adapted. The necessary steps are described below in the section Adapt Access Control Rules
Adapt Discovery Service
When users intend to access your service, they first need to select the organization they are from. In order to enable interfederation support, the Discovery Service must be extended to also include entities from non-SWITCHaai federations. The necessary steps are described below in the section Adapt Discovery Service
Adapt entry in Resource Registry
Before interfederation support can be used, the Resource description in the Resource Registry must be adapted. It may for instance be necessary to extend the list of required or desired attributes because interfederation-enabled Identity Providers won't support any swissEduPerson specific attributes. The necessary steps are described below in the section Changes in Resource Registry

2. Service Provider Configuration Changes

The goal of the configuration changes is to make the Service Provider:

  • Load the interfederation metadata
  • Accept some of the most frequently used user attributes

2.1 Prerequisites

Please ensure that the following prerequisites are met before proceeding with the installation of the Shibboleth Service Provider:
Required Software
This guide assumes that the Service Provider is using a supported version of the Shibboleth Service Provider (i.e., a release either supported by the Shibboleth project or the operating system vendor). Other SAML implementations are not covered in this guide.
Configured for SWITCHaai
This guide assumes that the Service Provider is already part of the SWITCHaai federation. It is assumed that the Service Provider is fully functional and that it was deployed according to the SWITCHaai deployment guides for Service Providers.

2.2 Considerations

Before starting the configuration, please consider the following:

Were users informed in advance about possible service disruptions?
The configuration steps below will require you to restart the Service Provider. While this will take only a few seconds (provided the configuration is correct), users might lose their Shibboleth session. This will cause them to get redirected back to their Identity Provider for re-authentication. Therefore, it is recommended to first carry out the following steps on a test system, if possible.
Is there a backup of all Service Provider configuration files?
Multiple configuration files of the Shibboleth Service Provider will be edited in the following steps. Although the changes are not difficult to apply, there is a risk that errors in these files affect the availability or performance of the Service Provider. Having backup files ensures that a fallback to a working configuration is quickly possible.

2.3 Attributes Released by Interfederation-enabled Identity Provider

For an interfederation-enabled Identity Provider it is recommended to be able to release certain attributes about a user. Some of these attributes are already used and supported within SWITCHaai. No change is required for a Service Provider to accept them. These attributes are:

  • Affiliation (eduPersonAffiliation)
  • E-Mail (mail)
  • Targeted ID/Persistent ID (eduPersonTargetedID)

Consult the AAI Attribute Specification on further information about these attributes.

In SWITCHaai there are many attributes used which are defined in the swissEduPerson attribute schema. This schema is only used in Switzerland and, therefore, non-SWITCHaai Identity Providers are not likely to support these attributes. However, there are similar attributes that could be used instead. In particular:

Display Name
Description: Name to display for a user
Value: There is only one value, which typically corresponds to givenName + surname. For Spanish users there might be multiple surnames
SAML2 name: urn:oid:2.16.840.1.113730.3.1.241
Shibboleth header name: displayName (formerly Shib-InetOrgPerson-DisplayName)
Common Name
Description: Multi-valued version of display name
Values: Like display name but can contain multipe values
SAML2 name: urn:oid:2.5.4.3"
Shibboleth header name: cn (formerly Shib-InetOrgPerson-CommonName)
Scoped Affiliation
Description: Affiliation attribute that includes a scope
Values: Multiple affiliation values that are followed by the scope in form of the organization's domain name. E.g. student@lmu.de
SAML2 name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9
Shibboleth header name: scopedAffiliation (formerly Shib-InetOrgPerson-ScopedAffiliation)
eduPerson Unique ID
Description: A long-lived, non re-assignable, omnidirectional identifier suitable for a person, mainly for inter-institutional user identification. International version of the swissEduPerson Unique ID.
SAML2 name: urn:oid:1.3.6.1.4.1.5923.1.1.1.13
Shibboleth header name: eduPersonUniqueId (formerly Shib-EP-UniqueID)
SCHAC Home Organisation
Description: Internationally used form of the Home Organisation attribute used in SWITCHaai. Can be used exactly like the swissEduPersonHomeOrganization attribute. More information about the SCHAC schema.
Values: Domain name of an organization, e.g. univie.ac.at, tu-berlin.de, etc.
SAML2 name: urn:oid:1.3.6.1.4.1.25178.1.2.9
Shibboleth header name: schacHomeOrganization (formerly Shib-SCHAC-HomeOrganization)
SCHAC Home Organisation Type
Description: Attribute similar to the swissEduPersonHomeOrganizationType but with a prefix scope. More information about the SCHAC schema
Values: One value as defined on the SCHAC URN registry. The value is prefixed with urn:schac:homeOrganizationType: + country code + : + national extension. Typical values are urn:schac:homeOrganizationType:ch:university, urn:schac:homeOrganizationType:fi:researchInstitution
SAML2 name: urn:oid:1.3.6.1.4.1.25178.1.2.10
Shibboleth header name: schacHomeOrganizationType (formerly Shib-SCHAC-HomeOrganizationType)

Note

The above list is not complete and may be extended in the future with other attributes.

2.4 Add Attribute Map

The goal of the following steps is to configure the Service Provider to accept some additional attributes that are typically sent by interfedrated Identity Providers. None of these attributes are usually used within SWITCHaai. However, they are internationally standardized and some of them are very similar to SWITCHaai attributes as explained above.

In order to support these additional attributes the Shibboleth Service Provider attribute map has to be adapted as follows:

  1. Login to the host that runs the Shibboleth Service Provider that you want to enable for interfederation.
  2. Go to the Shibboleth configuration directory and make a backup of the file attribute-map.xml :
    cd /etc/shibboleth/
    cp -p attribute-map.xml attribute-map.bak
  3. Open the file attribute-map.xml in a text editor.
  4. Insert the following XML snippet within the <Attributes> element, unless they are already in the file if you recently installed your SP.
       <!-- Attributes for Interfederation support -->
    
       <!-- displayName -->
       <Attribute name="urn:oid:2.16.840.1.113730.3.1.241" id="displayName"/>
    
       <!-- commonName -->
       <Attribute name="urn:oid:2.5.4.3" id="cn"/>
    
       <!-- eduPersonUniqueId -->
       <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.13" id="eduPersonUniqueId"/>
    
       <!-- schacHomeOrganization -->
       <Attribute name="urn:oid:1.3.6.1.4.1.25178.1.2.9" id="schacHomeOrganization"/>
    
       <!-- schacHomeOrganizationType -->
       <Attribute name="urn:oid:1.3.6.1.4.1.25178.1.2.10" id="schacHomeOrganizationType"/>
    
    

    The above snippet will add attribute definitions of all attributes that are recommended to support. If your application needs further attributes, you may need to bilaterally agree on the support and usage of these attributes with the administrators of the Identity Providers whose users should access your resource.

    Note

    The specification for the schacHomeOrganizationType is incomplete at the moment. Therefore, it cannot be relied on for now.

2.5 Configure Interfederation Metadata

In order to communicate with Identity Providers from other federations, the Service Provider requires metadata about these Identity Providers. Therefore, the goal of the following steps is to add a MetadataProvider that loads the interfederation metadata.

  1. Go to the Shibboleth configuration directory and create a backup file of the shibboleth2.xml file.
    cd /etc/shibboleth/
    cp -p shibboleth2.xml shibboleth2.xml.bak
  2. Open the file shibboleth2.xml as root user in a text editor.
  3. Look for the existing MetadataProvider element that loads the SWITCHaai metadata and insert below it the following snippet:
            <!-- Interfederation Metadata -->
            <MetadataProvider type="XML" 
                              validate="true"
                              uri="http://metadata.aai.switch.ch/entities/interfederation+idp"
                              backingFilePath="metadata.interfederation-idps.xml"
                              reloadInterval="3600">
                <MetadataFilter type="RequireValidUntil" 
                                maxValidityInterval="604800"/>
                <MetadataFilter type="Signature">
                    <TrustEngine type="StaticPKIX"
                                 certificate="SWITCHaaiRootCA.crt.pem"
                                 verifyDepth="2"
                                 checkRevocation="fullChain"
                                 policyMappingInhibit="true"
                                 anyPolicyInhibit="true">
                          <TrustedName>SWITCHaai Interfederation Metadata Signer</TrustedName>
                          <PolicyOID>2.16.756.1.2.6.8</PolicyOID>
                   </TrustEngine>
                </MetadataFilter>
            </MetadataProvider>
    

    Note

    If you are still using an unsupported(!) Shibboleth 2.3/2.4 version, you must add "verifyName="false"" to the MetadataFilter element of type="Signature".
    The metadata provider above uses the same trust anchor to verify the metadata signature as is used for the SWITCHaai federation metadata.
  4. Save the file and exit the text editor

2.4 Check and Restart Service Provider

The Service Provider should now be ready to restart:

  1. Check that the edited XML files are still well-formed and the configuration is intact. As root user execute:
    shibd -t -c /etc/shibboleth/shibboleth2.xml
    
    You should see a message like:
    overall configuration is loadable, check console for non-fatal problems
    
    You should neither see ERROR nor CRIT messages. If there are any WARN messages, you should examine and correct the problems but in general, these messages are not critical.
  2. If you are confident that the configuration is correct and that the short service disruption of the Service Provider and lost user sessions won't cause problems, restart the Service Provider daemon. Usually this is achieved with:
    $ /etc/init.d/shibd restart
  3. Inspect the Shibboleth log file during startup for example with the command:
    $ tail -f /var/log/shibboleth/shibd.log
    Check that there are no ERROR, CRIT or WARN messages during startup. If there are, you might want to restart the Service Provider again with the backup version of shibboleth2.xml.
  4. After startup, access a protected page of your service to ensure that Shibboleth authentication still works in general. Usually one can access a Shibboleth SessionInitiator URL like /Shibboleth.sso/Login to make Shibboleth initiate a session. After authentication, you may access the Shibboleth session handler using /Shibboleth.sso/Session to inspect the attributes that were received.

The Service Provider should now be properly configured for interfederation support. However, it may be that you also have to adapt your web application to make use of the non-SWITCHaai attributes to properly authorize users from other federations!

3. Adapt Access Control Rules

Enabling interfederation for a resource also means that the range of users who access the resource becomes broader. If the resource so far was accessed by users from SWITCHaai, the interfederation-enabled resource can be accessed by university users from all over the world in theory. Therefore, it is strongly recommended to ensure that the access control rules are properly set, which means not too strict but sufficiently strict. In particular you may check the following places where you could find access control rules:

  • All Apache configuration files
  • All Apache .htaccess files in the web server root and sub directories
  • RequestMap in shibboleth2.xml
  • Code in your applications that enforces access control

Check out the Shibboleth Service Provider Access Control guide.

4. Adapt Discovery Service

In order to enable Interfederation users to access your service, users must be able to log in using their Home Organisation. Therefore, they must in some way be supported to choose their Home Organisation. In SWITCHaai, users typically would use the SWITCHaai WAYF service or the Embedded WAYF service or they just would click on a direct login link. In an interfederation environment, the SWITCHaai WAYF cannot be used to let users select their Home Organisation outside of Switzerland. Depending on the number of non-SWITCHaai Home Organisations users should be able to pick from, there are the following solutions to solve this issue:

1 - 5 non-SWITCHaai Home Organisations:
You might use the Login Link Composer to generate direct login links. These links then can be used for login buttons that in the best case even use the organisations logo. This approach only works for a small number of non-SWITCHaai Home Organisations
1 - 20 non-SWITCHaai Home Organisations:
Using the Embedded WAYF one can set the configuration option wayf_additional_idps to add a few additional Home Organisation to the drop-down list of the Embedded WAYF.
1 - hundreds non-SWITCHaai Home Organisations:
When the Service Provider is a Shibboleth Service Provider 2.4 or newer, you have two options. You can use the Embedded WAYF and enable the configuration option wayf_use_disco_feed. It is also possible to use the Embedded Discovery Service (JavaScript/HTML/CSS) developed by the Shibboleth Consortium. Both solutions provide a search-as-you-type feature that lets users more easily find their Home Organisation the first time.

5. Changes in Resource Registry

Before the Service Provider can accept non-SWITCHaai users, its resource description in the SWITCH Resource Registry has to be adapted to:

  • Activate this Service Provider for interfederation support
  • Adapt the set of requested attributes
  • Apply for one or several entity categories (recommended to consider)

The following changes assume that your organization already has contacted the SWITCHaai team with the request to enable interfederation. Due to legal reasons, SWITCH has for now to manually enable each organisation for interfederation support. Only then interfederation can be enabled for a particular resource.

  1. Go to the Resource Registry using the URL https://rr.aai.switch.ch and log in using a SWITCHaai account that has administrative privileges for the Resource Description of the Service Provider which should be enabled for interfederation.
  2. After authentication, click on the tab "Resources " in order to see the Resource Descriptions for which you have administrative privileges.
  3. Click on the link "Edit" below the resource that you want to enable for interfederation. You then are in the resource menu and should see all the sections of the Resource Description. The last two sections within the red rectangles in the image below will have to be edited.
    Resource Registry - Resource Menu

5.1. Add Interfederation Attributes

  1. Click on the link "Requested Attributes". On this page you define the desired and required attributes of the resource.
  2. In the Section "Common Attribut Sets" you can easily mark the attributes that might be candidates, provided your resources really has need to get these attributes. Resource Registry Common Attribute Sets
  3. Check that the attributes the resource requests can be provided by interfederation enabled resources. The attributes that might be available for non-SWITCHaai users are marked in red in the screenshot below. Be aware that many IdentityProviders from other federations are very selective in which attributes they release! By supporting an EntityCategory as explained below, you will increase the chance to receive attributes your resource needs to function. All further attributes will most likely not be available for non-SWITCHaai users.
    Resource Registry Requested Attributes
  4. Finally click on "Save and Continue".

5.2. Enable Service Provider for Interfederation

  1. Click on the link "Intended Audience andInterfederation". On this page you define the intended audience for the resource.
  2. There should be a checkbox labelled "Interfederation" like shown below. If there is no checkbox, this means that your organization has not been enabled for interfederation support by SWITCH. Read the information that belongs to the checkbox. If you understand and agree with the conditions, enable the checkbox. You then will be asked to confirm.
    Resource Registry - Intended Audience

5.3 Apply for one or Several Entity Categories

An entity category allows IdPs to know specific universal properties of an SP. These can refer to data protection standards or the type of the SP. Based on this information, it may be more likely that IdPs release the necessary attributes for your SP. There are currently two entity categories available in the resource registry: GÉANT Data Protection Code of Conduct (CoCo) and REFEDS Research and Scholarship (R&S). Applications for entity categories are reviewed by SWITCH and become active when approved.

GÉANT Data Protection Code of Conduct

Before applying for the GÉANT Data Protection Code of Conduct entity category, an SP needs to create a web page with information on its data protection policy. The web page must be in English and it must contain a link to the GÉANT Data Protection Code of Conduct. The URL of this web page has to be entered in the resource description as "Privacy URL". You can then apply for the entity category by selecting the corresponding check box on the "Intended Audience and Interfederation" page. Resource Registry - SP Entity Categories

REFEDS Research and Scholarship

The first step of applying for the R&S entity category consists of creating a service information page. This page has to be in English and describe the purpose of the service. Its URL has to be entered in the "Descriptive Information" section under "Information URL". In order to be considered a candidate for the R&S category, an SP should not request other attributes than those contained in the R&S attribute set. If that's the case, the resource registry will show a warning. Finally, you can apply for the entity category by selecting the checkbox on the "Intended Audience and Interfederation" page.

5.4 Submit Resource for Approval

  1. Click on "Save and Continue" to return to the Resource Description menu.
  2. Back on the Resource Description menu, you still have to submit the Resource Description for approval before it becomes active.

Once interfederation support was enabled and approved for the Service Provider, its metadata will be included in the metadata file that is used by interfederation-enabled entities outside of SWITCHaai. For example in the eduGAIN metadata.

Note

When the change of the Resource Description has been approved by a Resource Registration Authority administrator, a notification email is sent to the resource admin. From then on, it may take between two hours and one day until a user from an interfederation-enabled Identity Provider is able to access your service. The reason for this is that the metadata with the applied changes is aggregated, processed and published several times until it is downloaded by an interfederation-enabled Identity Provider.

6. Testing

Login to your Service Provider should not work different for an user that access your resource via eduGAIN/Interfederation than for a user accessing your resource via SWITCHaai. However, what might be different is the set of attributes that a user from another federation releases to your Service Provider. Therefore, it is recommended that login is tested with user accounts from other federations before announcing interfederation support more widely. How can this be done?

Ask real users from other federations to test
The easiest option is to directly ask users from other federations to log in and report you if all works as expected. This should be a one-time effort for these real test users and often resource administrators already are in touch with users from other federations.
Use eduGAIN Access Check service
However, if you don't know real users and maybe want to test your resource with different type of accounts, we recommend you to use the eduGAIN Access Check. This service allows administrators of a Service Provider registered in eduGAIN, to create short-lived test identities (e.g. with typical attributes for a staff member or student) in order to test access to your own resource. How to use this is described on the eduGAIN Access Check page. This option is also recommended in case you don't have an AAI account yourself and thus cannot test access yourself.
Deploy an own Test Identity Provider
Deploying a Test Identity Provider to test access to your own resource requires quite advanced SAML knowledge, is quite time-consuming and it does not help testing access with real user identities. Therefore, this option is not recommended in general.

7. Troubleshooting

This section lists some common problems and possible solutions.

Service Provider complains that there is "Unknown or Unusable Identity Provider"
Make sure the Service Provider loads the interfederation metadata file as described above. Also ensure that the file is up-to-date and not older than 5 days. It should also be ensured that the user that runs the shibd process (e.g. _shibd in Debian) has sufficient privileges to write the interfederation metadata file to the configured directory (see above).
Applications complains that attribute X is not available or Shibboleth shows a "Authorization Denied"
The most likely reason for this error is that the Shibboleth Service Provider did not receive a necessary attribute or that the access control rule was not fulfilled for the given URL. First make sure all attributes that the application needs are available. This can be done by accessing the Shibboleth session handler, which normally is accessible via the URL /Shibboleth.sso/Session. On that page you should see all available attributes for the current user. If attribute X is not among the displayed attributes it could be that:
  • Attribute is filtered out: This could be because there is no rule for this attribute in the attribute-map.xml file or there is a rule in the attribute-policy.xml file, which filters out the attribute based on its origin or on its value. In both cases, you should have a look at the /var/log/shibboleth/shibd.log file in order to spot any signs of filtering. If an attribute is filtered out by the Service Provider it will look like shown below:
    ... WARN Shibboleth.AttributeFilter [126]: removed value at position (0) of attribute (schacHomeOrganization) from ...
    ... WARN Shibboleth.AttributeFilter [126]: no values left, removing attribute (schacHomeOrganization) from ...
    
  • Attribute is not released by the Identity Provider: In this case, look up the technical contact of the Identity Provider by having a look at the interfederation metadata file. The administrator may know more why a certain attribute is not released.
Another error not listed above
Please have a look at the Common Service Provider Errors page of the Shibboleth Wiki. If you don't find an error description that matches yours, contact the AAI team.

8. References