Configuring a Shibboleth 2.x Identity Provider for the UK Federation

Installation

This document is intended to serve as a guide for configuring a Shibboleth 2.x identity provider (IdP) to operate within the UK federation. It is assumed that you have downloaded and installed the current version of the Shibboleth 2.x software, and other supporting software, as described in the Shibboleth documentation, and tested its basic functionality using the testshib test SP.

The Shibboleth 2 Identity Provider (IdP) is a Java web application. It must be run in a Java servlet container; Tomcat, from the Apache Software Foundation is the most commonly used supported container. Other supported containers are Jboss Tomcat and Jetty. In turn, the Java servlet container requires Sun Java to run.

The Shibboleth Windows .msi installer installs a "captive" Tomcat for you, so you only need to have Java installed before you start. For other platforms you need to start with Java and the servlet container being installed. Some organisations use the Apache httpd web server as a proxy front end, although this is no longer necessary, nor recommended by the Shibboleth developers. For those who are using it, the Apache httpd configuration is included here.

In general, the most recent software versions should be used, but ensure that you check the Shibboleth documentation for any caveats. For documentation on the supporting software please see the developers' websites as appropriate at:

The normal installation order would be [httpd —>] Java —> Tomcat —> Shibboleth.

There is an alternative installation package that we recommend for Windows users, that results in a standard Tomcat-only Shibboleth installation, and takes a lot of the effort out of the configuration. Please see the Windows installer section below. If you decide to use the Windows installer you should start out with the latest 32 bit version of Java only. All other required software is bundled with the installer.

You can use testshib to get to the stage where you can log in to the IdP and authenticate against your organisation's LDAP/Active Directory. Please see the following sections up to and including the DefaultRelyingParty section for configuration information.

Please note the following important points:

• All references to testshib should be removed from the IdP configuration files before configuring it for the UK federation, otherwise the IdP may be vulnerable to a security exploit.
• The UK federation strongly recommends the IdP to have the traditional configuration of keeping a separate port, normally port 8443, for "back channel" communications with service providers. This is because a recent vulnerability in SSL has resulted in a patch to some dependent libraries being issued. An IdP which relies on single host/port operation will cease to work when it encounters this patch, whether the patch is installed on the IdP itself or on the SP it is communicating with.
• Your network firewall and the firewall on the IdP server will need to be open to incoming and outgoing traffic on ports 443 and 8443.
• If you decide to use the Windows installer you should start out with the latest 32 bit version of Java only. Tomcat is included with the Windows installer, and Apache httpd is not required.
• Tomcat's default heapspace memory allocation is not likely to be sufficient for the IdP. At least 1024MB is needed, perhaps more.

Windows Installer

Windows users can use the Windows .msi installer as an alternative to the .zip archive. It can save the installer a considerable amount of work at configuration time, so long as they enter the required information accurately at installation time. The most recent release can be downloaded from the Shibboleth download site.

Please read the Windows installer documentation before you run it. In particular it is important to ensure in advance that you have all the values required as input to the installer. If these values are entered correctly at installation time it can save a considerable amount of time and effort later.

When the installation is complete you can test against testshib in the first instance, then configure the IdP with an SSL certificate and configure the IdP to operate in the UK federation.

Please note that the Windows installer is not intended for upgrading an existing Shibboleth 2.x installation to a later Shibboleth 2.x release. The latest release of the standard Shibboleth 2.x software should be used for that. Please refer to the Shibboleth 2 upgrade 2.x documentation.

Tomcat Configuration (without Apache)

If Apache is not being used to proxy the IdP then you must ensure that Tomcat has a connector configured in the Tomcat conf/server.xml file for each of ports 443 and 8443. Please note that you need to use SSL certificates to protect the IdP's endpoint URLs, and these are configured in the connectors in server.xml.

Please see our Tomcat server.xml configuration page for the recommended configuration. You can then proceed to Shibboleth Configuration Files below.

Apache httpd Configuration

As already noted, it is not necessary to proxy the Shibboleth 2 IdP behind the Apache httpd web server. However, if you wish to do so then please note that you need to use an SSL certificate to protect the IdP's endpoint URLs, and these are configured in the Apache httpd configuration.

We recommend you configure the httpd SSL VirtualHost directives according to the federation IdP Apache httpd configuration documentation. You can then proceed to Shibboleth Configuration Files below.

Registration

Once you can log in successfully to the IdP in tests with testshib it is time to register the IdP in the UK federation.

When the IdP is registered you can configure it for the UK federation using the information in the sections from Metadata onwards. Please do not use production service providers for testing your configuration, as this may cause problems for the service providers: please see the Testing section for links to dedicated federation test SPs.

Shibboleth Configuration Files

The Shibboleth 2.x IdP configuration files will normally be in the conf subdirectory of the Shibboleth installation directory, eg. /opt/shibboleth-idp/conf. The files you will need to edit are:

• attribute-filter.xml
• attribute-resolver.xml
• logging.xml
• relying-party.xml
• handler.xml
• login.config

Please note that the names and syntax of the configuration files have changed between Shibboleth versions 1.3 and 2.x. For those upgrading from Shibboleth 1.3 it may be helpful to note the approximate functional equivalence between 1.3 and 2.x configuration files as follows:

After making changes to the files you will need to ensure that the IdP picks up the changes by restarting Tomcat (or by restarting the IdP from the Tomcat Manager). It is advisable to work on one file at a time, making the necessary changes then restarting Tomcat, and then checking the Shibboleth and Tomcat logs for possible errors and to confirm that the IdP is running correctly.

logging.xml

At the top of logging.xml there are three loggers defined for Shibboleth, SAML and LDAP messages, and the PROTOCOL_MESSAGE logger in comments. When you are just starting out, or trying to resolve a problem, it is a good idea to change the log level to DEBUG in all of these, and remove the comments from around the PROTOCOL_MESSAGE logger. Specifying DEBUG causes the log file produced to be more comprehensive and informative, but much larger, so you should turn the log level to INFO or WARN once you are happy with the configuration or the problem is resolved.

Unlike the other IdP configuration files, the logging.xml file is re-read every 10 minutes (in the default configuration). So you can alter the logging level on a production deployment without restarting the servlet container. For more information, see IdP logging on the Shibboleth wiki

The Shibboleth log files are written to the logs subdirectory of the Shibboleth installation directory; the idp-process.log is usually the most informative.

In case you no longer have the distribution version of logging.xml for some reason, here are the most useful loggers, all at DEBUG level. You should change them to INFO or WARN when you have finished debugging. You may wish to comment out the PROTOCOL_MESSAGE logger during normal operation.

 
    <!-- Logs IdP, but not OpenSAML, messages -->
    <logger name="edu.internet2.middleware.shibboleth" level="DEBUG"/>

    <!-- Logs OpenSAML, but not IdP, messages -->
    <logger name="org.opensaml" level="DEBUG"/>

    <!-- Logs LDAP messages -->
    <logger name="edu.vt.middleware.ldap" level="DEBUG"/>

    <!-- Logs inbound and outbound protocols messages at DEBUG level -->
    <logger name="PROTOCOL_MESSAGE" level="DEBUG" />

handler.xml

To configure authentication against an organisational LDAP, edit handler.xml, ensure that the UsernamePassword login handler is not commented out, and add the unspecified authentication method to it as below (the triple slash is intentional). You may need to change /opt/shibboleth-idp to refer to the IdP installation directory on your system.

 
 <ph:LoginHandler xsi:type="ph:UsernamePassword"
               jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config">
     <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
     </ph:AuthenticationMethod>
     <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
     </ph:AuthenticationMethod>
 </ph:LoginHandler>

Check that the jaasConfigurationLocation correctly points to the location of the login.config file, which is included in the Shibboleth distribution (in the conf directory).

login.config

The login.config file contains an example JAAS configuration to connect to an LDAP service using the LDAP authentication module shipped as part of the IdP. Ensure it is uncommented and make changes appropriate to your local configuration, consulting your directory maintainers as necessary, eg:

 
 ShibUserPassAuth {
    edu.vt.middleware.ldap.jaas.LdapLoginModule required
       host="ldap.uni.ac.uk"
       port="389"
       ssl="true"
       base="OU=Users,DC=uni,DC=ac,DC=uk"
       subtreeSearch="true"
       userField="uid"
       serviceUser="CN=ldapuser,DC=ldaphost,DC=uni,DC=ac,DC=uk"
       serviceCredential="ldapuser's password";
 };

An example Kerberos authentication configuration is also included. The login.config file can be modified to suit your needs, and can contain multiple login modules. More information is provided at:

Please note: if you are deploying against Active Directory you should make yourself aware of the Active Directory configuration issues described on the Shibboleth documentation site. If your users are all in one Active Directory OU then you can use port 389. If your users span more than one OU or more than one domain then you can probably use the Global Catalog port 3268 so that searches are performed against all OUs. If port 3268 is specified then "OU=Users," should be removed from the value of the base field in the JAAS configuration so it searches from the root. Also, the value of the "serviceUser" field should be specified in the form "ldapuser@ldaphost.uni.ac.uk" instead of "CN=ldapuser,DC=ldaphost,DC=uni,DC=ac,DC=uk".

relying-party.xml

The relying-party.xml file defines how your IdP should interact with service providers in the federation and how it gets the federation metadata. Some of it is set up for you by the Shibboleth installation script, but you will also need to make some manual changes.

DefaultRelyingParty

Look for the <rp:DefaultRelyingParty> definition, and check that the provider= attribute refers to the entity ID of your IdP (this should have been written by the Shibboleth installation script), eg:

 
 <rp:DefaultRelyingParty provider="https://idp.uni.ac.uk/idp/shibboleth"
                      defaultSigningCredentialRef="IdPCredential">

If the value of the provider= attribute does not match the entity ID that you wish to use then you should change it appropriately. For example, you may need to use an entity ID that you have been using for a previous IdP version, or one that you have been using in another federation.

Please note: The hostname component in the entity ID URI does not have to match the hostname of the IdP server. Please see the UK federation entity ID policy for more information.

Metadata

Shibboleth 2 has built-in support for metadata download, so a separate tool (such as metadatatool) is no longer needed. First, scroll down relying-party.xml and find the security:TrustEngine stanza with id="shibboleth.MetadataTrustEngine" and delete the surrounding comments.

Next, find the Metadata Configuration section, which is a little way up the file from the security:TrustEngine that we just uncommented. Look for the section starting <MetadataProvider id="URLMD", uncomment it, and edit it to make it the same as below. If necessary, edit the value of the backingFile element where highlighted below, changing /opt/shibboleth-idp to refer to the IdP installation directory on your system.

Important: for security reasons you should remove (or comment out) any reference to the testshib <MetadataProvider> from your relying-party.xml file before adding the <MetadataProvider> for the UK federation or any other federation.

Please note: if you have a recent version of the Windows installer then you should have used the post-install script supplied with it, as described in the example given in the installer documentation, and you shouldn't need to make any further changes here.

 
 <metadata:MetadataProvider id="URLMD" xsi:type="metadata:FileBackedHTTPMetadataProvider"
                   metadataURL="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
                   backingFile="/opt/shibboleth-idp/metadata/ukfederation-metadata.xml">
     <metadata:MetadataFilter xsi:type="metadata:ChainingFilter">
         <metadata:MetadataFilter xsi:type="metadata:SchemaValidation"/>
         <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil" maxValidityInterval="P30D"/>
         <metadata:MetadataFilter xsi:type="metadata:SignatureValidation"
             trustEngineRef="shibboleth.MetadataTrustEngine"
             requireSignedMetadata="true"/> 
         <metadata:MetadataFilter xsi:type="metadata:EntityRoleWhiteList">
             <metadata:RetainedRole>samlmd:SPSSODescriptor</metadata:RetainedRole>
         </metadata:MetadataFilter>
     </metadata:MetadataFilter>
 </metadata:MetadataProvider>
 

Note the change to the maxValidityInterval value. In the distribution version of relying-party.xml it is specified as P7D, which is seven days in period notation. We are changing this to P30D, which is 30 days. This means that the federation metadata will be rejected if its validity period exceeds 30 days.

In releases of the Shibboleth IdP software earlier than 2.2 the maxValidityInterval value is specified in seconds, and period notation is not supported. The equivalent value in seconds is 2592000. If you upgrade your IdP software from an earlier release to a version that supports the period notation the update script will preserve your existing configuration files if requested and generate a warning message in the idp-process.log advising that the configuration should be updated to use period notation, and specifying the appropriate values.

By default, the IdP will refresh the metadata if it is more than a day old. This behaviour can be modified by setting the optional cacheDuration attribute. More information about the IdP's metadata configuration is available here:

Credentials

Then go to the next section of relying-party.xml, Security Configurations. In the <security:Credential> element with id="IdPCredential", ensure that the private key and certificate pair that you intend to use for the UK federation trust fabric are referred to. The certificate will be registered in the UK federation metadata, but the contents of the private key file must be kept secret. Your options for the certificate are as follows:

• A self-signed certificate. The Shibboleth installation process generates a long-life self-signed certificate, with accompanying private key and Java keystore files. These are saved in the credentials subdirectory. The certificate file is named idp.crt, and the private key file is idp.key. This certificate is suitable for use in the federation trust fabric, and this is now the recommended trust fabric certificate for an IdP. (The keystore file is called idp.jks, and is needed if you are using the Tomcat servlet container and not proxying through Apache httpd.
• A commercial SSL certificate may be used as an alternative to a self-signed certificate.

The following restrictions must be observed:

• The CN of the certificate must match the hostname in the IdP's AttributeService and ArtifactResolutionService URLs (this will normally be the DNS hostname of the IdP server).
• A key length of at least 2048 bits is recommended for all certificates, and a key length of at least 2048 bits is mandatory for trust fabric certificates. We recommend 2048 bits, as longer keys provide no additional practical security but are more computationally expensive for all parties.

If you have just installed the IdP and you plan to use the self-signed certificate as recommended, then you don't need to change the <security:Credential> element because it is already correct. Also, its contents are embedded in the idp-metadata.xml file, which must be supplied to the federation team when the IdP is registered.

If you plan to use something other than the self-signed certificate created at installation, then when you have acquired it, save the certificate and private key files to the credentials subdirectory and edit the <security:PrivateKey> and <security:Certificate> lines inside the <security:Credential> element with id="IdPCredential" in relying-party.xml to refer to those files, so it looks like this:

    
    <security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
        <security:PrivateKey>/opt/shibboleth-idp/credentials/my-key.pem</security:PrivateKey>
        <security:Certificate>/opt/shibboleth-idp/credentials/my-cert.pem</security:Certificate>
    </security:Credential>

You also need to edit the idp-metadata.xml file in the metadata subdirectory, deleting the contents of both the <X509Certificate> elements and replacing them in each case with the contents of the SSL certificate file (not the private key file). You need to send the idp-metadata.xml file to the federation team when the IdP is registered.

When you submit the IdP registration the federation team will need to verify the origin of the certificate according to their standard procedure: currently an email procedure is used to verify the SHA1 fingerprint of the certificate. This means that you will need to determine the fingerprint yourself. On a Windows system you should be able to view the certificate and thus the SHA1 fingerprint simply by double-clicking the certificate file. On a Unix or Linux system you can view the fingerprint with the following OpenSSL command:

 openssl x509 -sha1 -noout -fingerprint -in idp.crt

TrustEngine

Finally, ensure that the <security:TrustEngine> element with id="shibboleth.MetadataTrustEngine" is uncommented. Edit it to read as follows. You may need to change /opt/shibboleth-idp to refer to the IdP installation directory on your system.

 
 <security:TrustEngine id="shibboleth.MetadataTrustEngine" 
                       xsi:type="security:StaticExplicitKeySignature">
     <security:Credential id="MyFederation1Credentials"
                          xsi:type="security:X509Filesystem">
         <security:Certificate>/opt/shibboleth-idp/credentials/ukfederation.pem
         </security:Certificate>
     </security:Credential>
 </security:TrustEngine>

Do not make any changes to any of the other <security:TrustEngine> elements, below the "DO NOT EDIT BELOW THIS POINT" comment.

Download into the credentials directory the certificate used to sign the UK federation metadata ukfederation.pem. To ensure that the copy you have has not been tampered with, you should verify the SHA-1 fingerprint of the certificate. To determine the fingerprint of your copy of the certificate, run this openssl command:

 
 openssl x509 -sha1 -noout -fingerprint -in ukfederation.pem

You should then compare this with the correct fingerprint value, which can be obtained from a member of the UK federation team by phoning the federation helpdesk. We recommend a phone call, as it provides a higher level of assurance than email.

Beware of duplicating entries for MetadataProvider, TrustEngine and Credential; if you copy these then change the IDs to ensure that each entry is unique.

attribute-resolver.xml

The attribute-resolver.xml file defines how the IdP generates SAML attributes for the IdP's users. It is common to configure the IdP to authenticate users against the organisation's LDAP, eg. OpenLDAP or Active Directory, use it to look up values associated with those users, and use these as the basis for attribute generation. However for early testing it may be easier to start by statically generating attributes, by means of the example static data connector near the end of the attribute-resolver.xml file. Note that this should only be used for testing; static attribute generation should not be used in a production IdP. There are many example attribute definitions provided in the distributed attribute-resolver.xml file which can be copied and edited as necessary.

The SAML attributes you are likely to use most in the UK federation are eduPersonScopedAffiliation and eduPersonTargetedID, so we will concentrate on those here.

The Transient Id or Name Identifier

The attribute-resolver.xml file in the V2.4.x IdP distribute contains an attribute definition with id="transientId". This should not be commented out or deleted; it is required for the correct release of attributes.

The Data Connector

Here we will look at using the example LDAP connector for attribute generation. This can be found near the bottom of the attribute-resolver.xml file. This should be edited as appropriate for your local configuration, in consultation with your local directory maintainers as necessary. The values of the principal and principalCredential should be the user ID and password of an appropriate LDAP user.

 
 <resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" 
                         ldapURL="ldap://ldap.uni.ac.uk" 
                         baseDN="OU=Users,DC=uni,DC=ac,DC=uk" 
                         principal="uid=myservice,ou=system"
                         principalCredential="Password">
     <dc:FilterTemplate>
            <![CDATA[
                (uid=$requestContext.principalName)
            ]]>
     </dc:FilterTemplate>
 </resolver:DataConnector>

Notes for Active Directory users:

1. If your users span more than one OU you can specify port 3268 in the LDAP URL so that it will search all the OUs, eg. ldapURL="ldap://ldap.uni.ac.uk:3268". If you do this then you should remove "ou=Users," from the baseDN field.
2. It has been reported that the line beginning 'principal=' in the above data connector definition does not work for Active Directory, and that it should be specified in the form 'principal=username@uni.ac.uk' or 'principal=username@ldaphost.uni.ac.uk'. The corresponding change also needs to be made to the "serviceUser" field in login.config.
3. The attribute used to look up the user is sAMAccountName in Active Directory (replacing uid in <FilterTemplate> in the example above and in login.config).
4. In the eduPersonTargetedID section below it is recommended for Active Directory users to use the objectSid to source eduPersonTargetedID. In order to work around Active Directory configuration issues described on the Shibboleth documentation site you need to add this property to the above <DataConnector> after the <FilterTemplate> element:

 <dc:LDAPProperty name="java.naming.ldap.attributes.binary" value="objectSid"/>

eduPersonScopedAffiliation

We provide here an example of how to generate the attribute eduPersonScopedAffiliation. This example appears in attribute-resolver.xml in the section titled Schema: eduPerson attributes. Note that the ref attribute to the <resolver:Dependency> element refers to the LDAP connector above by means of its id attribute with value myLDAP. Note also that it assumes that the myLDAP data source is populated with an unscoped attribute called eduPersonAffiliation (which might have values such as staff, student or member).

 
 <resolver:AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="ad:Scoped"
        scope="uni.ac.uk" sourceAttributeID="eduPersonAffiliation">
    <resolver:Dependency ref="myLDAP" />

    <resolver:AttributeEncoder xsi:type="enc:SAML1ScopedString"
        name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" />

    <resolver:AttributeEncoder xsi:type="enc:SAML2ScopedString"  
        name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" 
        friendlyName="eduPersonScopedAffiliation" />
 </resolver:AttributeDefinition>

Please note: as indicated above, this will generate eduPersonScopedAffiliaton from values of eduPersonAffiliation drawn from your LDAP or Active Directory. If you are using a script to generate values of eduPersonAffiliation from Groups in the LDAP, then you need to change the Dependency, thus:

 
 <resolver:AttributeDefinition id="eduPersonScopedAffiliation" xsi:type="ad:Scoped"
        scope="uni.ac.uk" sourceAttributeID="eduPersonAffiliation">
    <resolver:Dependency ref="eduPersonAffiliation" />

    <resolver:AttributeEncoder xsi:type="enc:SAML1ScopedString"
        name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" />

    <resolver:AttributeEncoder xsi:type="enc:SAML2ScopedString"  
        name="urn:oid:1.3.6.1.4.1.5923.1.1.1.9" 
        friendlyName="eduPersonScopedAffiliation" />
 </resolver:AttributeDefinition>

eduPersonTargetedID

You can use the ComputedId data connector (near the bottom of attribute-resolver.xml) to create a unique identifier per user per SP by computing an SHA1 hash given the requester's (the SP's) entity ID, the value of a specified directory attribute, and a "salt". The salt is an arbitrary value that you should keep secret, and must be at least 16 characters long. The values thus produced can be used as unique opaque identifiers. The directory attribute used as a source here is the uid, which equates to the user identifier or login name.

The algorithm used to compute these values is the same as in Shibboleth 1, so users' personalisation data on SPs does not have to be lost in an upgrade from version 1.3 to 2.x.

 
 <resolver:DataConnector xsi:type="dc:ComputedId"
                         id="computedID"
                         generatedAttributeID="computedID"
                         sourceAttributeID="uid"
                         salt="your random string here">
     <resolver:Dependency ref="myLDAP" />
 </resolver:DataConnector>

Note that this data connector is dependent on the LDAP data connector with id myLDAP. When using the data connector examples from attribute-resolver.xml it is a good idea to take copies of the examples and edit them as appropriate to your configuration, and to change the id values to something of your own choosing, remembering similarly to change the ref values in attribute definitions and other data connectors that depend upon them.

The following attribute definitions can then be used to generate eduPersonTargetedID (both the "old" and "new" versions):

 
 <!-- eduPersonTargetedID (old - valid in SAML 1 only) -->

 <resolver:AttributeDefinition id="eduPersonTargetedID.old" xsi:type="ad:Scoped"
                               scope="uni.ac.uk" sourceAttributeID="computedID">
     <resolver:Dependency ref="computedID" />

     <resolver:AttributeEncoder xsi:type="enc:SAML1ScopedString"
                                name="urn:mace:dir:attribute-def:eduPersonTargetedID" />
 </resolver:AttributeDefinition>

 <!-- eduPersonTargetedID (new - valid in SAML 1 and SAML 2) -->

 <resolver:AttributeDefinition id="eduPersonTargetedID" xsi:type="ad:SAML2NameID" 
                               nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
                               sourceAttributeID="computedID">
     <resolver:Dependency ref="computedID" />

     <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject"
                                name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />

     <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject"
                                name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" 
                                friendlyName="eduPersonTargetedID" />
 </resolver:AttributeDefinition>

Please note that the ComputedId data connector generates a warning which appears in the IdP log, and it is worth considering changing to the use of a storedId data connector instead. This requires the creation of a database table with a specific structure. Further information can be found here.

Note for those deploying against Active Directory: the objectSID is a good source for eduPersonTargetedID. However the issue described to do with the binary nature of the objectSid as described on the Shibboleth documentation site must be worked around, as described in the data connector section above.

attribute-filter.xml

The attribute-filter.xml file is used to determine which attributes should be released to which SPs.

The distribution attribute-filter.xml file contains a rule which releases the transient ID to all SPs; this rule should be kept in place when you edit the attribute-filter.xml file to add your own rules.

You should not release all possible attributes to all SPs in the UK federation aggregate as some attributes contain personal data, for example eduPersonPrincipalName. Please see section 7.2 of our Technical Recommendations for Participants and section 3 of Recommendations for use of personal data for more details. Note also that the UK federation metadata aggregate contains metadata from SPs registered in partner federations outside the UK, and which have been imported via the eduGAIN mechanism. The UK federation has developed a filter that allows IdP operators to filter an IdP's attribute release based on the federation that a SP was originally registered in. Please see the Attribute release to imported entities section of our eduGAIN participation page.

You should ask the service providers used by your organisation to tell you their attribute requirements, and we list the attributes required by many UK-registered SPs here. Some SPs require either eduPersonPrincipalName or eduPersonTargetedID; given this choice it is preferable to release eduPersonTargetedID.

As eduPersonTargetedID is an opaque identifier (an identifier that doesn't directly reveal an individual's name or other personally identifying information, such as email address), it's usually considered safe to release to any authenticated SP. Many also consider it safe to release eduPersonScopedAffiliation to any SP, as all it reveals is the user's affiliation status and the IdP's scope. The following AttributeFilterPolicy rule enables release of both forms of eduPersonTargetedID and eduPersonScopedAffiliation to any SP.

 
 <afp:AttributeFilterPolicy id="releaseToAnyone">
     <afp:PolicyRequirementRule xsi:type="basic:ANY" />
     <afp:AttributeRule attributeID="eduPersonTargetedID">
         <afp:PermitValueRule xsi:type="basic:ANY" />
     </afp:AttributeRule>
     <afp:AttributeRule attributeID="eduPersonTargetedID.old">
         <afp:PermitValueRule xsi:type="basic:ANY" />
     </afp:AttributeRule>
     <afp:AttributeRule attributeID="eduPersonScopedAffiliation">
         <afp:PermitValueRule xsi:type="basic:ANY" />
     </afp:AttributeRule>
 </afp:AttributeFilterPolicy>

Testing

You can test your configuration by going to the UK federation test SP:

You should test with all five links under the "Session Initiators" heading on the index page to check the full range of SAML1 and SAML2 profiles that your IdP supports. If the IdP is "invisible", that is to say it is hidden from the federation WAYF list of organisations, you will need to click on the "Search over All Sites." link at the bottom of the "Which organisation would you like to sign in with?" page. You need to select the IdP's organisation display name, click continue, and log in at your IdP login page.

Each time you test, check the attribute values released by clicking the "session dumper" link at the top of the page displayed by the test SP after login.

If you select your own IdP site from the discovery page and then successfully authenticate, you should see a list of CGI environment variables, thus testing attribute value generation and release in addition to simple authentication. If you have trouble authenticating or releasing attributes then ensure your Shibboleth log levels are turned up to DEBUG (see above in the logging.xml section) before re-testing, and check the logs; the idp-process.log is generally the most informative. If nothing is being written to the Shibboleth logs then check the Tomcat logs; it is advisable to keep checking the Tomcat logs anyway during the earlier stages of the installation.

Please note: You should not attempt to gain access to any live service until you have verified, by the use of the test pages noted above, that your identity provider is properly configured and handling attributes correctly.

Finally

Once your identity provider is in service, you might wish to contact any UK federation service providers with whom you have service agreements and inform them that you now have an identity provider registered in the UK federation. The information required by an SP varies; they will probably need to know the scope asserted by your IdP and some may need to know the entity ID.