Enabling Interfederation Support for a Shibboleth Identity Provider (IdP) in SWITCHaai

Table of contents

  1. Introduction
  2. Identity Provider Configuration Changes
  3. Changes in Resource Registry
  4. Interfederation Test
  5. Troubleshooting
  6. References

1. Introduction

This guide describes the steps to enable interfederation support for a Shibboleth 2 Identity Provider in the SWITCHaai federation. After the following steps have been successfully applied, users from this Identity Provider will be able to access interfederation-enabled resources from outside the SWITCHaai federation. In particular, eduGAIN resources will be accessible.

Note

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

For Shibboleth Identity Provider v3 administrators who want to enable their IdP for interfederation:
Instead of applying the steps in chapter 2 below, check out the IdPv3 installation guide that includes interfederation enabling as default option. You mainly need to load the additional metadata file and make sure you configure all attributes that are required for interfederation interoperability.

1.1 Process Overview of Enabling Interfederation

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

IdP Interfederation Enabling Process

SWITCHaai Interfederation Access Declaration
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.
Enable user consent
SWITCH strongly recommends to deploy a user consent module on the Identity Provider before interfederation support is enabled. A user consent module like uApprove ensures that users explicitly give their consent when releasing attributes to services outside the legal framework of SWITCHaai and jurisdiction of Switzerland. From a data protection point of view, it should be ensured that the Identity Provider is configured following the legal recommendations as described on the page Legal Templates for SWITCHaai.
Adapt Identity Provider configuration
In order to communicate with services outside of the SWITCHaai federation, it is necessary to provide some attributes that are normally not used in SWITCHaai. These attributes are however very similar to attributes that are already used in SWITCHaai. Therefore, the required changes in order to support these attributes are limited to the Identity Provider configuration. The necessary steps are described below in the section Identity Provider Configuration Changes.
Adapt entry in Resource Registry
Before interfederation support gets active, the Home Organisation description in the Resource Registry must be adapted. It is for instance necessary to extend the list of supported attriutes with the ones that are required for interfederation support. The necessary steps are described below in the section Changes in Resource Registry.
Pass Interfederation Test
In order to ensure that the Identity Provider is properly set up, there is an interfederation test that SWITCH operates. This test will check that an Identity Provider can release all the recommended attributes in the correct format. Identity Provider Configuration Changes

2. Identity Provider Configuration Changes

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

  • Load the interfederation metadata
  • Release all the attributes recommended for interfederation support

2.1 Prerequisites

Please ensure that the following prerequisites are met before proceeding with the installation of the Shibboleth Identity Provider:
Required Software
This guide assumes that the Identity Provider is using Shibboleth Identity Provider 2.3.x or 2.4.x or a newer version. Other SAML implementations are not covered in this guide.
Configured for SWITCHaai
This guide assumes that the Identity Provider is already part of the SWITCHaai federation. It is assumed that the Identity Provider is fully functional and that it was deployed according to the SWITCHaai deployment guides for Identity Providers.
Attribute Release Consent
After having completed this guide, the Identity Provider will be able to release information to services outside of Switzerland and outside of the SWITCHaai federation. Therefore, it is assumed that a user consent module like uApprove is installed on the Identity Provider. To configure uApprove to be active only for non-Swiss resources adapt the following two settings in uApprove.properties:
services = ^https?://[^/]*\.ch.*$
services.blacklist          = true
Alternatively, if uApprove also should be enabled if users access resources operated outside your organization's domain, one could use a rule like:
services = ^https?://[^/]*\.example\.ch.*$ \
           ^https?://[^/]*\.example\.edu.*$ \ 
           ^https?://[^/]*\.other-domain\.net.*$
services.blacklist          = true

2.2 Considerations

Before starting the configuration, please consider the following:

Do you have permission from your organisation's management to enable interfederation support?
Adding interfederation support to an Identity Provider means releasing information about users from your organization to services outside of the Swiss or SWITCHaai jurisdiction. Therefore, it is recommended to consult the organization's management before taking this step.
Were users informed in advance about possible service disruptions?
The configuration steps below will require at least one restart of the Identity Provider. If there is an error in the configuration, multiple restarts may be necessary. During these possible service disruptions during no user will be able to authenticate at the Identity Provider.
Is there a backup of all Identity Provider configuration files?
Multiple configuration files of the Shibboleth Identity 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 Identity Provider. Having backup files ensures that a fallback to a working configuration is quickly possible.
Does your IdP run with enough memory?
The inclusion of the metadata of the Service Providers from other federations increases the overall size of the metadata file. The IdP needs to load more data and needs to keep this data in memory. Currently, the recommended size of heap space of 512M for Tomcat should be enough. But depending on the number of Service Providers contained in the metadata, memory needs may rise in the future. Therefore, we recommend a minimal size of heap space for Tomcat of 1G if Interfederation is supported.

2.3 Add Attribute Definitions

There are a few additional attributes that should be supported by an Identity Provider in order to allow its users to access international AAI services offered by content providers or in eduGAIN.

Please follow the guide that explains how to add these international attributes to your Identity Provider.

2.4 Configure Interfederation Metadata

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

  1. Go to the Shibboleth configuration directory and create a backup file of the relying-party.xml file.
    cd /opt/shibboleth-idp/conf/
    cp relying-party.xml relying-party.xml.bak
  2. Open the file relying-party.xml as root user in a text editor.
  3. Look for the existing MetadataProvider element which loads the SWITCHaai metadata and insert just after it the following snippet:
            <metadata:MetadataProvider id="InterfederationURLMD"
                                       xsi:type="metadata:FileBackedHTTPMetadataProvider"
                                       metadataURL="http://metadata.aai.switch.ch/entities/interfederation+sp"
                                       backingFile="/opt/shibboleth-idp/metadata/metadata.interfederation-sps.xml"
                                       requireValidMetadata="true"
                                       maxRefreshDelay="PT1H">
                <metadata:MetadataFilter xsi:type="metadata:ChainingFilter">
                    <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil"
                                             maxValidityInterval="P7D"/>
                    <metadata:MetadataFilter xsi:type="metadata:SignatureValidation"
                                             trustEngineRef="shibboleth.InterfederationMetadataTrustEngine"
                                             requireSignedMetadata="true"/>
                </metadata:MetadataFilter>
             </metadata:MetadataProvider>
    

    Note

    Make sure that the added MetadataProvider inserted above is added within a MetadataProvider element of type="ChainingMetadataProvider". Otherwise the Identity Provider won't be able to start. Also ensure that the namespace (in the above example metadata) is set like for your existing MetadataProvider elements.
    This metadata provider will use the same trust anchor to verify the metadata signature as is used for the SWITCHaai metadata.
  4. Look for the TrustEngine element with id="shibboleth.MetadataTrustEngine", which defines the metadata signature validation. Insert just after another trust engine with in form of the following configuration snippet:

    For IdP version 2.3.x, use the following snippet:

        <security:TrustEngine id="shibboleth.InterfederationMetadataTrustEngine"
                              xsi:type="security:StaticPKIXSignature">
            <security:TrustedName>SWITCHaai Interfederation Metadata Signer</security:TrustedName>
    	<security:ValidationInfo id="SWITCHaaiFederationCredentials" 
                                     xsi:type="security:PKIXFilesystem"
                                     verifyDepth="2">
                <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate>
            </security:ValidationInfo>
    	<security:ValidationOptions xsi:type="security:CertPathValidationOptionsType"
                                        forceRevocationEnabled="true"/> 
        </security:TrustEngine>
    

    For IdP version 2.4.x, use the following snippet:

        <security:TrustEngine id="shibboleth.InterfederationMetadataTrustEngine"
                              xsi:type="security:StaticPKIXSignature">
            <security:TrustedName>SWITCHaai Interfederation Metadata Signer</security:TrustedName>
    	<security:ValidationInfo id="SWITCHaaiFederationCredentials"
                                     xsi:type="security:PKIXFilesystem"
                                     verifyDepth="2">
                <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate>
            </security:ValidationInfo>
    	<security:ValidationOptions xsi:type="security:CertPathValidationOptionsType"
                                        forceRevocationEnabled="true"
                                        policyMappingInhibit="true"
                                        anyPolicyInhibit="true">
                <security:PolicyOID>2.16.756.1.2.6.8</security:PolicyOID>
            </security:ValidationOptions>
        </security:TrustEngine>
    
  5. Save the file and exit the text editor

2.5 Increase the heap size (memory) of Tomcat (optional)

For support of Interfederation, we recommend to configure Tomcat with a minimal heap size of 1G. While the current recommendation for a standard setup of 512M might still be enough at the moment, memory requirements might increase in the future. If your Tomcat runs with a heap size of 512M or below, and if your server has enough memory available or if you have the possibility to increase the memory of your server, we recommend to increase the heap size of Tomcat to at least 1G.

If required, you need to increase the overall memory of your server or virtual machine first.

Then, you can increase the heap size of Tomcat by changing the option -Xmx512M to -Xmx1024M in your Tomcat startup configuration. On a Debian system, this is done by adapting the value of the JAVA_OPS variable in the file /etc/default/tomcat6:

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024M -XX:MaxPermSize=128M -Dcom.sun.security.enableCRLDP=true"

2.6 Check and Restart Identity Provider

The Identity Provider should now be ready to restart:

  1. Check that the edited XML files are still well-formed. For instance with:
    xmlwf relying-party.xml
    If no output is shown, the configuration files are well-formed. Alternatively, it is also possible to open the files in Firefox, which will display a warning message if a file is not well-formed.
  2. If you are confident that the configuration is correct and that the short service disruption of the Identity Provider restart won't cause problems, restart the Identity Provider by restarting the servlet container (e.g. Tomcat). For instance with:
    $ /etc/init.d/tomcat restart
  3. Inspect the Shibboleth log file during startup for example with the command:
    $ tail -f /var/log/shibboleth/idp-process.log
    Check that there are no ERROR, CRIT or WARN messages during startup. If there are, you might want to restart the Identity Provider again with the backup version of relying-party.xml
  4. After startup, access an AAI service like the AAI Viewer to test whether the Identity Provider still is working as expected. The AAI Viewer displays all the attributes that were released by the Identity Provider. You should see all mandatory attributes but you can not yet see the newly configured attributes because they are not yet released!

3. Changes in Resource Registry

Before the Identity Provider can release the set of attributes which is recommended to support for interfederation services, the Home Organisation description in the SWITCH Resource Registry has to be adapted to:

  • Activate this Identity Provider for interfederation support
  • Review the attributes configured above as supported attributes
  • Adapt the attribute release policies for interfederation
  • Configure the Entity Category Polices
  • configure Specific Attribute Release Policies when required

3.1. Enable Identity Provider for Interfederation

The following changes assume that you already have contacted the SWITCHaai team with the request to enable interfederation. Only then interfederation can be enabled for a particular Service or Identity Provider.

  1. Go to the Resource Registry using the URL https://rr.aai.switch.ch and log in using a SWITCHaai account for which you have administrative privileges for the Home Organisation description of the Identity Provider.
  2. After authentication, click on the tab "Home Organisation Admin" in order to see the Home Organisation description for which you have administrative privileges.
  3. Click on the link "Edit Home Organization Description" below the Home Organisation that you want to enable for interfederation. You then should be in the Home Organisation menu and see all the sections of the Home Organisation description. The sections within the red rectangles in the image below are relevant for interfederation.
    Resource Registry Edit Home Organization Sections
  4. Click on the link "General Information". On the following page you should find a checkbox labelled "Interfederation" like shown below. Read the information below. If you understand and agree with the terms, enable the checkbox. You then will be asked to confirm. If there is no checkbox, this means that your organization has not been enabled for interfederation support by SWITCH.
    Resource Registry Interfederation Checkbox
  5. Finally click on "Save and Continue" to return to the page with all Home Organisation sections.

Once interfederation support is enabled for the Identity Provider, its metadata will be included in the metadata file that is used by interfederation-enabled entities outside of the SWITCHaai federation. For example in the eduGAIN metadata. However, unless the Identity Provider will adapt its Attribute Release Policy as explained in the next steps, no attributes will be released to any interfederation-enabled entity. There are basically three ways to release attributes to interfederation SPs which are explained in the following section. They differ in the level of control and the amount of work involved.

  1. Default attribute release rules are the easiest to define, as they are valid for all interfederation SPs and no changes have to be made if new SPs are added. However, they do not offer the possibility to distinguish between different SPs at all.
  2. Entity categories allow to filter SPs by a type that has been agreed on on an international level. SPs have to apply for an entity category in order to enable attribute release.
  3. Specific attribute release rules offer the highest level of control and are the most flexible. However, they have to be defined for each SP which leads to a huge amount of work for the IdP administrator.

Note

All changes applied to any of the three possible sections only will become active when the Identity Provider downloads the attribute-filter.xml the next time from the Resource Registry. This may take up to one hour. The Resource Registry will send an email containing all changes to the administrative contacts of the Home Organisation when the attribute-filter.xml is downloaded.

3.2. Review the additional Supported Attributes

Click on "Supported Attributes" and review the settings as they were enabled above in chapter 2.3 with the 'International Attribute Support for SWITCHaai Identity Providers'.

3.3. Default Attribute Release Policies

In the following steps, the default Attribute Release Policy is changed such that the newly added attributes can be released to all interfedereated resources.

  1. Back in the Home Organisation description menu, click on the link "Attribute Release Settings"
  2. First closely read the top part that explains how the attribute release settings affect the attribute release.
  3. Configure the default attribute release policy rules in the section "Default Policies for Individual Attributes". For each required or desired attribute an individual default release scope can be set. As for SWITCHaai resources, it is generally recommended to release required non-personal attributes from the core set to "interfederation resources" as interfederation resources typically are operated by education and research organisations abroad. This includes universities, research instutions, international research projects or content publishers. Your users benefit from access to these services. Defining a too restrictive default attribute policy can result in your user's not getting access to interfederated services that require some of these attributes.
    Note that some attributes like Affiliation and Scoped Affiliation as well as Common Name, Display Name, Given Name with Surname basically contain the same information. Therefore, it makes sense to configure the same release rules for these related attributes.
    Resource Registry Default Attribute Release Policy
  4. Then click on "Save and Continue" to return to the Home Organisation menu.

3.4. Configure Entity Category Policies

Entity categories are a classification of SPs under the control of the federation operator of the SP's home federation. There are currently two entity categories configurable in the Resource Registry:

  • GÉANT Data Protection Code of Conduct (CoCo)
    CoCo SPs claim to adhere to European data protection standards
  • REFEDS Research and Scholarship (R&S)
    R&S SPs offer services supporting collaboration specifically to the research community.

Setting up attribute release policies based on entity categories allows to minimise the workload for verifying each individual SP (this is in fact delegated to the federation operator of the originating federation). At the same time it allows to control the attribute release in a more fine-grained way that with default release rules. IdPs and SPs supporting entity categories will improve interoperability.

Resource Registry Entity Category Section

For the GÉANT Data Protection Code of Conduct (CoCo) entity category, the Resource Registry offers three options:

  1. Do not release any attributes at all
  2. Release required attributes
  3. Release required and desired attributes

CoCo SPs claim to request only attributes that are needed by them, but there is no formal restriction on a specific set. If it passes the control of the federation operator a CoCo SP could request any attribute.

In the REFEDS Research and Scholarship entity category, two sets of attributes have been defined: a minimal set and a complete set. SPs have to pick one of the two sets. The Resource Registry offers the following settings:

  1. Do not release any attributes at all
  2. Release the minimal set of principal name, email and name
  3. Release the complete set containing (additionally to the above) the targeted ID and the scoped affiliation

3.5. Configure Specific Attribute Release Policies

  1. At the bottom of the Attribute Release Settings page in the section named "3. Resource Specific Policies" click on "Resource Specific Attribute Release Policy rules."
  2. This page allows creating specific attribute release policies that override the default attribute policy in order to release fewer or more attributes to very specific resources. The screenshot below shows such a specific attribute release policy for the Interfederation Test mentioned below. Please ensure that the resource https://attribute-viewer.aai.switch.ch/interfederation-test/shibboleth receives all attributes it requires. Otherwise, the test in the next chapter will fail.
    Resource Registry Specific Attribute Release Policy
  3. After having created one or more specific rules, click on "Save and Continue" to return to the Home Organisation menu.

4. Interfederation Test

In order to ensure that the Identity Provider configuration was performed correctly and that the changes in the Resource Registry settings were applied properly, we strongly recommend to perform the following test:

  1. Access the Interfederation Test page and authenticate with AAI
  2. If the following page looks like on the screenshot below, something is not yet working correctly:
    Failed Interfederation Test
    Contact aai@switch.ch for assistance if you have questions or if there is a problem that you cannot solve on your own.
  3. In order to pass the test, you should see a page like below:
    Successful Interfederation Test
    Congratulations, if you see the above "Passed" logo, the Identity Provider is ready to allow its users to access interfederation resources. In order to access a real interfedreated service, you may try to login to the eduGAIN Wiki, a federated wiki operated by GÉANT.

5. Troubleshooting

This section lists some common problems and possible solutions.

Identity Provider complains that there is "No return endpoint available for relying party ..."
Make sure the Identity 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 servlet container (e.g. tomcat) has sufficient privileges to write the interfederation metadata file to the configured directory (see above).
Interfederation-enabled service complains that attribute X is not present
Check the attribute requirements of that Service Provider according to its entry in the Resource Registry (search it in the interfederation tab) and compare it with your default attribute relese rules. You might need to add a specific rule for that SP.
Another error not listed above
Please have a look at the Common Identity Provider Errors page of the Shibboleth Wiki. If you don't find an error description that matches yours, contact the AAI team.

6. References