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

Introduction
Service Provider Configuration Changes
Adapt Access Control Rules
Adapt Discovery Service
Changes in Resource Registry
Testing
Troubleshooting
References

1. Introduction

This guide describes the steps to enable interfederation support for a Shibboleth 2 Service Provider registered 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 Shibboleth Service Provider 3.x and general information about the deployment of a Shibboleth Service Provider within the SWITCHaai Federation, please consult the SP Guides section of the SWITCHaai website.
Thereafter, return back here and continue with chapter 3 Adapt Access Control Rules.

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: This is no longer required, it is now integrated into the SWITCH edu-ID Service Description.
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. The SP 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 SAML SP 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)
Scoped Affiliation (eduPersonScopedAffiliation
E-Mail (mail)
Targeted ID (eduPersonTargetedID), preferrably requested as SAML NameID format persistent

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

In SWITCHaai there are many attributes used that 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 SP 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 SP header name: cn (formerly Shib-InetOrgPerson-CommonName)
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 SP 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 SP 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 SP 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 interfederated 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:

Login to the host that runs the Shibboleth Service Provider that you want to enable for interfederation.
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
```
Open the file attribute-map.xml in a text editor.

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">
       <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
   </Attribute>

   <!-- schacHomeOrganizationType -->
   <Attribute name="urn:oid:1.3.6.1.4.1.25178.1.2.10" id="schacHomeOrganizationType">
       <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="false"/>
   </Attribute>

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> element that loads the interfederation metadata.

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
```
Open the file shibboleth2.xml as root user in a text editor.

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>
            <MetadataFilter type="EntityRole">
                <RetainedRole>md:IDPSSODescriptor</RetainedRole>
                <RetainedRole>md:AttributeAuthorityDescriptor</RetainedRole>
            </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.

Save the file and exit the text editor

2.4 Check and Restart Service Provider

The Service Provider should now be ready to restart:

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.
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
```
Inspect the Shibboleth log file during start-up for example with the command:
```
$ tail -f /var/log/shibboleth/shibd.log
```
Check that there are no ERROR, CRIT or WARN messages during start-up. If there are, you might want to restart the Service Provider again with the backup version of shibboleth2.xml.
After start-up, access a protected page of your service to ensure that Shibboleth authentication still works in general. Usually, one can access a Shibboleth SP SessionInitiator URL like /Shibboleth.sso/Login to make the Shibboleth SP 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 only by users from SWITCHaai, the interfederation-enabled resource can in theory be accessed by university users from all over the world. 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

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 central SWITCHaai Discovery Service/WAYF service or the Embedded Discovery Service/WAYF service or they just would click on a direct login link.
In the interfederation context, the central SWITCHaai Discovery Service/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 Discovery Service/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 Discovery Service/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.

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.
After authentication, click on the tab "Resources " in order to see the Resource Descriptions for which you have administrative privileges.
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.

5.1. Add Interfederation Attributes

Click on the link "Requested Attributes". On this page you define the desired and required attributes of the resource.
In the Section "Common Attribute Sets" you can easily mark the attributes that might be candidates, provided your resources really has need to get these attributes.
Check that the attributes the resource requests can be provided by interfederation enabled Identity Providers. The attributes that might be available for non-SWITCHaai users are marked with a yellow background in the screenshot below. Be aware that many Identity Providers from other federations are very selective in which attributes they release!
By supporting an Entity Category 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.

Instead of requesting the attribute Targeted ID, set the SAML NameID Format to persistent.
Finally click on "Save and Continue".

5.2. Enable Service Provider for Interfederation

Click on the link "Intended Audience and Expert Settings". On this page you define the intended audience for the resource.
Note: For resources of an organization with SWITCHaai Federation Partner Basic status, contact the SWITCHaai team by mail to activate that checkbox.
If there is no "Interfederation" checkbox as shown below, your organization has not yet been enabled by SWITCH for interfederation support.
Read the information in the checkbox. If you understand and agree with the conditions, enable the checkbox. You then will be asked to confirm.

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 Expert Settings" 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 Expert Settings" page.

5.4 Submit Resource for Approval

Click on "Save and Continue" to return to the Resource Description menu.
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 pretty big eduGAIN metadata XML file.

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 to even several days until a user from an interfederation-enabled Identity Provider is able to access your service.
The reason is that the metadata with the applied changes gets aggregated, processed and published more than once before it is downloaded by an interfederation-enabled Identity Provider. The frequency of how long it takes depends of the federation in which the Identity Provider is registered.

6. Testing

Login to your Service Provider should not work differently for users who 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 an Identity Provider from another federation releases for its users 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 to test?

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.

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 has sufficient privileges to write the interfederation metadata file to the configured directory (see above).

Application 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 SP 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 that 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 gets 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 SWITCHaai team.