Bilateral Identity Provider Configuration

The following page describes the technical steps that are required when an Identity Provider (IdP) shall be configured to allow its users access to a non-SWITCHaai Service Provider (SP). This allows bilateral (inter-federation) cooperations with non-SWITCHaai federation members even before European or global solutions like eduGAIN are used in production. Any legal or policy-related issues are up to the administrator of the service to deal with and are subsequently not covered here.

Prerequisites

It is assumed that the IdP is a Shibboleth Service Provider 2.x which is fully configured and working according to our deployment guides.

Step 1: Add metadata of non-SWITCHaai Service Provider(s)

The Service Provider (SP) as well as the Identity Provider (IdP) need to know each other in order to communicate. Knowing each other means having the other component's metadata. Therefore, the IdP must be configured to load the SP's metadata. There are two ways of loading the IdP's metadata

Load a metadata of a single SP
On first sight it may make sense to configure the IdP to load metadata for only the relevant SP. A Shibboleth SP's metadata usually can be downloaded from
https://#FQDN#/Shibboleth.sso/Metadata
The risk of this solution lies in the fact that changes in the setup of the SP require a notification and manual update of the metadata. Although one also could configure the SP to load metadata directly from the above-mentioned URL, this option would fail if the host name of the SP changes. This method is also less secure even if metadata is loaded over https and therefore not recommended.
Load metadata of federation that SP is part of
Generally, the better approach is to configure the IdP to load metadata of a federation that the SP is part of. The advantage of this solution is that federation metadata most-likely will always be up-to-date, stay at a known URL and that this file is signed by a federation. Another advantage is that it is very easy to configure access for additional IdPs of the same federation. Therefore, this is the recommended way to go.

In the following the bold values surrounded by ## stand for:

##METADATA-URL##
URL to the metadata file of a federation.
##METADATA-BACKUP-FILE##
Path to the file where the downloaded and verified metadata shall be stored. This usually is a file in /opt/shibboleth-idp/metadata/.
##METADATA-SIGNING-CERT-FILE##
Path to the X.509 certificate file that shall be used to verify the metadata signature. This usually is a file in /etc/shibboleth/.
##SP-ENTITYID##
EntityID of the SP that shall be bilaterally configured.

In order to configure an IdP to load additonal metadata, proceed with the following steps:

  1. Download the signing certificate of the federation that the SP is part of and store the certificate file in
    ##METADATA-SIGNING-CERT-FILE##
  2. Compare the fingerprint of this signing certificate to verify that the correct one was downloaded
  3. Open the Shibboleth configuration file relying-party.xml
  4. Look for the element MetadataProvider with type="ChainingMetadataProvider", which should be the outmost of all instances of MetadataProvider elements
  5. Within that element, add the following snippet and substitute the bold values with correct ones:

  6. <MetadataProvider 
      id="OtherFederationURLMD" 
      xsi:type="FileBackedHTTPMetadataProvider" 
      xmlns="urn:mace:shibboleth:2.0:metadata" 
      metadataURL="##METADATA-URL##"
      backingFile="##METADATA-BACKUP-FILE##" 
      maintainExpiredMetadata="false" 
      cacheDuration="3600">
        <MetadataFilter xsi:type="SignatureValidation" 
          xmlns="urn:mace:shibboleth:2.0:metadata" 
          trustEngineRef="shibboleth.OtherFederationMetadataTrustEngine" 
          requireSignedMetadata="true" />
    </MetadataProvider>
    

    Next, in the same file look for the element TrustEngine. After this element add:

    <security:TrustEngine 
      id="shibboleth.OtherFederationMetadataTrustEngine" 
      xsi:type="security:StaticExplicitKeySignature">
        <security:Credential
          id="OtherFederationCredentials" 
          xsi:type="security:X509Filesystem">
            <security:Certificate>##METADATA-SIGNING-CERT-FILE##</security:Certificate>
        </security:Credential>
    </security:TrustEngine>
    

    Federations Table

    The following listing contains links to federation metadata and other relevant files of some federations that SWITCHaai Federation Members may cooperate with. Fingerprints of signing certificates can be compared with the command:
    openssl x509 -fingerprint -sha1 ##METADATA-SIGNING-CERT-FILE##

    DFN-AAI (Germany)
    Metadata URL: https://www.aai.dfn.de/fileadmin/metadata/DFN-AAI-metadata.xml
    Metadata backup file name: DFN-AAI-metadata.xml
    Signing certificate: dfn-aai.pem
    Signing certificate SHA1 Fingerprint: 3C:4F:37:88:21:F0:4A:88:AE:AE:78:71:61:B4:6A:F7:45:ED:45:D7
    ACOnet-AAI (Austria)
    Metadata URL: https://wayf.aco.net/aconet-aai-metadata.xml
    Metadata backup file name: aconet-aai-metadata.xml
    Signing certificate: aconet-aai-metadata-signing.crt
    Signing certificate SHA1 Fingerprint: EE:37:0A:C2:77:56:F8:8B:45:3A:9B:7D:F2:F0:CA:24:C2:14:33:72
    Éducation-Recherche (France)
    Metadata URL: https://services-federation.renater.fr/metadata/renater-metadata.xml
    Metadata backup file name: renater-metadata.xml
    Signing certificate: metadata-federation-renater.crt
    Signing certificate SHA1 Fingerprint: CD:14:DE:02:64:31:53:B6:3B:4E:EB:48:42:E0:66:EC:69:33:68:98

    Step 2: Adapt attribute resolver and filter

    Service Providers from other federations sometimes use and require different attribute names and values than the ones defined in the SWITCHaai attribute specification. Therefore, it may be necessary to make the IdP generate these attributes and release them to the SP. In order to do so, it may be necessary to edit the two files attribute-resolver.xml and attribute-filter.xml or better add a file local-attribute-filter.xml.
    The attribute resolver defines from wich data sources attributes are fetched from. Usually the data sources will be LDAP/AD directories and relationcal databases like MySQL or similar. In addition the Identity Provider can create new or modify existing attributes from these sources by using scripted attributes. Very often it is required to release to the SP the attribute eduPersonPrincipalName, which is not available in SWITCHaai. However, we have the swissEduPersonUniqueID attribute that has almost the same format and thus could be used instead. Alternatively, the mail attribute could be used as well in cases where the eduPersonPrincipalName is used as displayName. In order to encode and use the swissEduPersonUniqueID as eduPersonPrincipalName, add the followign AttributeDefinition to attribute-resolver.xml:

    <resolver:AttributeDefinition
     id="eduPersonPrincipalName" 
     xsi:type="Simple" 
     xmlns="urn:mace:shibboleth:2.0:resolver:ad"
     sourceAttributeID="swissEduPersonUniqueID">
      <resolver:Dependency ref="myLDAP" />
      <resolver:AttributeEncoder 
       xsi:type="SAML1ScopedString"
       xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
       name="urn:mace:dir:attribute-def:eduPersonPrincipalName" />
      <resolver:AttributeEncoder 
       xsi:type="SAML2ScopedString"
       xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
       name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
       friendlyName="eduPersonPrincipalName" />
    </resolver:AttributeDefinition>
    
    To make sure that the Service Provider receives the attributes it needs, an attribute filter rule that permits the release must be added as well. Because the Identity Provider according to the SWITCHaai deployment guideline is already configured to load the attribute-filter.xml from the Resource Registry, it's best to add an additional local file that can be managed by hand. This can be accomplished by editing the service.xml and another ConfigurationResource element within the Service element that has id="shibboleth.AttributeFilterEngine":

      <ConfigurationResource 
       xsi:type="resource:FilesystemResource"
       file="/opt/shibboleth-idp/conf/local-attribute-filter.xml"/>
    

    The additional attribute filter file /opt/shibboleth-idp/conf/local-attribute-filter.xml containing one single rule for the SP then could look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- 
       Locally managed attribute filter file
    -->
    
    <AttributeFilterPolicyGroup 
     id="LocalShibbolethFilterPolicy" 
     xmlns="urn:mace:shibboleth:2.0:afp"
     xmlns:basic="urn:mace:shibboleth:2.0:afp:mf:basic" 
     xmlns:saml="urn:mace:shibboleth:2.0:afp:mf:saml"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="urn:mace:shibboleth:2.0:afp classpath:/schema/shibboleth-2.0-afp.xsd
      urn:mace:shibboleth:2.0:afp:mf:basic classpath:/schema/shibboleth-2.0-afp-mf-basic.xsd
      urn:mace:shibboleth:2.0:afp:mf:saml classpath:/schema/shibboleth-2.0-afp-mf-saml.xsd">
    
    <!-- 
       Example attribute filter rule
       More information about rules can be found here:
       https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAddAttribute
    -->
      <AttributeFilterPolicy id="afp_##SP-ENTITYID##">
        <PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="##SP-ENTITYID##" />
        <AttributeRule attributeID="email">
          <PermitValueRule xsi:type="basic:ANY" />
        </AttributeRule>
        <AttributeRule attributeID="eduPersonAffiliation">
          <PermitValueRule xsi:type="basic:ANY" />
        </AttributeRule>
        <AttributeRule attributeID="eduPersonPrincipalName">
          <PermitValueRule xsi:type="basic:ANY" />
        </AttributeRule>
        <AttributeRule attributeID="surname">
          <PermitValueRule xsi:type="basic:ANY" />
        </AttributeRule>
        <AttributeRule attributeID="givenName">
          <PermitValueRule xsi:type="basic:ANY" />
        </AttributeRule>
      </AttributeFilterPolicy>
    
    </AttributeFilterPolicyGroup>
    

    Step 3: Test the configuration

    In order to test whether a user from the IdP can access the remote SP, it's best to log in on the service the SP protects:

    1. First make sure the configuration is still ok by restarting the container (e.g. Tomcat) as root user and then examine the log file for any ERROR messages or stack traces.
    2. Then go to the SWITCH login URL composer and complete the form. As Service Provider target URL one can use https://sp.to.test/Shibboleth.sso/Session in case the SP is a Shibboleth SP. As Identity Provider entityID provide the entityID of the IdP that shall be tested.
    3. Click on the generated link and authenticate at the Identity Provider. In case uApprove is installed, a first check should be the list of attributes that is shown after successful authentication. If all went well, one should see the attributes configured in the above attribute filter rule.
    4. If something doesn't work as expected or if not all attributes are available that one would suspect, have a look at the idp-process.log file and consult the Shibboleth trouble shooting page for help. If all fails, contact us for assistance.

    Assistance

    Please feel free to contact us for assistance and recommendations in case of difficulties or problems.