Bilateral Service Provider Configuration (deprecated)

This guide is deprecated because Service Provider should use the Interfederation deployment guide instead.

The following page describes the technical steps that are required when a Service Provider (SP) shall be configured to allow access for users from a non-SWITCHaai Identity Provider (IdP). 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 SP is a Shibboleth Service Provider 2.x which is fully configured and working according to our deployment guides. For the sake of simplicity it is assumed that one single foreign IdP is to be added to the SP's configuration.

Step 1: Add metadata of non-SWITCHaai Identity Provider

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 SP must be configured to load the IdP's metadata. There are two ways of loading the IdP's metadata

Load a metadata of a single IdP
On first sight it may make sense to configure the SP to load metadata for only the relevant IdP. A Shibboleth IdP's metadata usually can be downloaded from:
https://#FQDN#/idp/profile/Metadata/SAML
The risk of this solution lies in the fact that changes in the setup of the IdP 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 IdP changes. This method is also less secure even if metadata is loaded over https and therefore not recommended.
Load metadata of federation that IdP is part of
Generally, the better approach is to configure the SP to load metadata of a federation that the IdP is part of and then filter out all other IdPs except the relevant one. 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 /etc/shibboleth/.
##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/.
##IDP-ENTITYID##
EntityID of the IdP whose users shall be able to access the service. All other IdPs in the downloaded metadata file will be filtered out.

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

  1. Download the signing certificate of the federation that the IdP 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 shibboleth2.xml
  4. Look for the element MetadataProvider with type="chaining"
  5. Within that element, add the following snippet and substitute the bold values with correct ones. Then save the file and restart shibd and apache2.
  6. <MetadataProvider type="XML"
       uri="##METADATA-URL##"
       backingFilePath="##METADATA-BACKUP-FILE##" reloadInterval="3600">
      <MetadataFilter type="Signature" verifyName="false">
      <TrustEngine type="StaticPKIX" verifyDepth="5">
        <CredentialResolver type="File">
        <Certificate format="PEM">
          <Path>##METADATA-SIGNING-CERT-FILE##</Path>
        </Certificate>
        </CredentialResolver>
      </TrustEngine>
      </MetadataFilter>
      <MetadataFilter type="Whitelist">
        <Include>##IDP-ENTITYID##</Include>
      </MetadataFilter>
    </MetadataProvider>
    

    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 policy and map

    Identity Providers in non-SWITCHaai federations sometimes use and release different attribute names and values than the ones defined in the AAI attribute specification. Therefore, it may be necessary to make the SP accept these attributes and map them onto attributes that are required by the application protected by the SP. In order to do so, it may be necessary to edit the two files attribute-map.xml and attribute-policy.xml.
    The attribute map defines how attributes from a SAML assertion are mapped to the web server environment. It is possible to map multiple SAML attributes onto the same attribut that is made available to the application. This allows for example to compensate for the fact that other federations don't use the attribute swissEduPersonUniqueID to identifiy users. Rather they use the eduPersonPrincipalName, which looks almost the same as the swissEduPersonUniqueID but generally is not opaque. In this case, it may be convenient to map the eduPersonPrincipalName onto the same header as the swissEduPersonUniqueID so that the application doesn't have to care what unique attribute it shall use for identifying users. This could be accomplished for example with an entry in the attribute-map.xml like the following, which maps the eduPersonPrincipalName onto the same header as the swissEduPersonUniqueID:

    <!-- eduPersonPrincipalName-->
    <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName"
    id="Shib-SwissEP-UniqueID" aliases="principalName uniqueID"/>
    <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6"
    id="Shib-SwissEP-UniqueID" aliases="principalName uniqueID"/>
    
    The attribute mapping also is thye first place where filtering occurs. All attributes in SAML assertions with no definition in the attribute map are filtered out. Therefore, one must make sure that a definition in the attribute map for all attributes that the application requires exists.

    The attribute policy on the other hand defines which attributes and values are accepted by the SP. One could for instance create a rule that will make the SP accept a certain attribute or value only from specific Identity Providers. Or it can be enforced that attributes can only have certain values or that the values must match a regular expression. The default behaviour is to pass all attributes which are not referenced specifically by a rule in this file.

    In order to find out whether the attribute map and policy must be adapted, one has to find out which attributes the in question service requires. Since most federations use attributes based on the eduPerson attribute schema or the SCHAC schema, they mostly use the same attribute names and value definitions. For a list of available eduPerson attributes, have a look at the file /etc/shibboleth/attribute-map.xml.dist that should contain a complete listing of (commented out) attribute mappings.

    Step 3: Test the configuration

    In order to test whether a user from the bilaterally configured IdP can access the service, it's best to try the following procedure:

    1. First make sure the configuration is still ok by running the command (as root):
      shibd -tc /etc/shibboleth/shibboleth2.xml
      The output should be overall configuration is loadable, check console for non-fatal problems. There should be no ERROR or CRIT messages and best no WARN messages either. If this is the case, continue with the next step.
    2. Go to the SWITCH login URL composer and complete the form. As Service Provider target URL once should use https://my.host.ch/Shibboleth.sso/Session. As Identity Provider entityID one should provide the entityID of the bilaterally configured IdP that shall be tested.
    3. If a test account is at hand on the IdP, click on the generated login link and authenticate. If all goes well, one should be back on the URL that was provided as target URL. All attributes that are available for this user account should then be shown on that page.
    4. If something doesn't work as expected or if not all attributes are available that one would suspect, have a look at the shibd.log file and consult the Shibboleth trouble shooting page for help. If all fails, please contact us for assistance.

    Step 4: Define access control rules

    Once access from the Non-SWITCHaai IdP was successfully tested and all attributes that the service requires are available, one can adapt the access control rules. This is done like one would do it for any SWITCHaai IdP because it is purely based on attributes. For details how to define access rules, please have a look at the page that explains access control. Just keep in mind that all attributes that are used for access control rules must be available and contain one or more values. Otherwise the rule won't match and access will be denied.

    Step 5: Adapt WAYF/Login links

    In order for users of non-SWITCHaai IdPs to being sent to the login page of the Non-SWITCHaai IdP to log in, it is necessary to either provide a special login link for them or to extend the Embedded WAYF with entries for the other IdPs.

    Assistance

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