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 Internet2 documentation, and tested its basic functionality using the testshib test SP. It's a good idea to test both the SAML2 flow (the default) and the SAML1 flow: the latter can be tested here.
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 Quick Installer section below.
Please note that 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.
Please also note that 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.
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. In turn, Tomcat requires Sun Java to run.
The minimum Shibboleth installation thus depends on Java and Tomcat 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 Internet2 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.
Please note: if you are using the Windows Quick Installer you should start out with the latest 32 bit version of Java only. Tomcat is included with the Quick Installer, and Apache httpd is not required.
Please also note: Tomcat's default heapspace memory allocation is not likely to be sufficient for the IdP. At least 512MB is needed, perhaps more. Here is a description of the problem and how to resolve it.
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.
Windows Quick Installer
Windows users can use the Windows Quick Installer .msi package as an alternative to the standard Shibboleth package. The Quick Installer is in beta release at present, but its beta status does not refer to the installation resulting from running it; it installs a standard 2.1.5 release Shibboleth IdP. 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 of the Quick Installer can be downloaded from here:
Please follow the pre-installation instructions before running the .msi file. When you have completed those instructions and gathered the information specified there you can run the installer. Ensure that you enter the information accurately as it will save trouble-shooting work later on.
When you have run the installer and entered the information you can test against testshib and then proceed to Tomcat Configuration (without Apache) below, to configure the IdP's endpoints with an SSL certificate.
Please note that the Quick 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 Internet 2 upgrade 2.x documentation.
Upgrading a Shibboleth IdP from 1.3 to 2.x
Important note: When upgrading your Shibboleth 1.3 IdP to 2.x it is important to ensure that the final Shibboleth 2.x installation and registration has the same entity ID as the Shibboleth 1.3 IdP, and that the same Salt string is used to generated the eduPersonTargetedID attribute. This will ensure that the eduPersonTargetedID values released for your users will not change as a result of the upgrade, and this in turn will ensure that users' personalisations and registrations will be retained at SPs after the upgrade.
Please see this document for suggested approaches to upgrading a Shibboleth IdP from version 1.3 to 2.x.
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 an SSL certificate to protect the IdP's endpoint URLs, and these are configured in the connectors in server.xml.
Please see this page for the recommended configuration. You can then proceed to Shibboleth Configuration Files below.
Apache Configuration
As already noted, it is not necessary to proxy the Shibboleth 2 IdP behind Apache. 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.
Please see this page for the recommended configuration. You can then proceed to Shibboleth Configuration Files below.
Registration
Once you can login 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.xmlattribute-resolver.xmllogging.xmlrelying-party.xmlhandler.xmllogin.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:
| Shibboleth 1.3 | Shibboleth 2.x |
|---|---|
| idp.xml | relying-party.xml |
| resolver.xml | attribute-resolver.xml |
| arp.site.xml | attribute-filter.xml |
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 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.
The Shibboleth log files are written to the logs subdirectory of the Shibboleth installation directory; the idp-process.log is usually the most informative.
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.
<LoginHandler xsi:type="UsernamePassword"
jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config">
<AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
</AuthenticationMethod>
<AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
</AuthenticationMethod>
</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 issues described here. 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 use 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 <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:
<DefaultRelyingParty provider="https://idp.uni.ac.uk/idp/shibboleth"
defaultSigningCredentialRef="IdPCredential">
Metadata
Shibboleth 2 has built-in support for metadata download, so a separate tool (such as metadatatool) is no longer needed. Scroll down relying-party.xml and find the Metadata Configuration section. Look for the section starting <MetadataProvider id="URLMD" and edit it as indicated below. You may need to change /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 are using the Windows Quick Installer then there might be no <MetadataProvider id="URLMD"> like the one below. In that case you should remove the existing <MetadataProvider> for testshib and replace it with the one below.
<MetadataProvider id="URLMD" xsi:type="FileBackedHTTPMetadataProvider"
xmlns="urn:mace:shibboleth:2.0:metadata"
metadataURL="http://metadata.ukfederation.org.uk/ukfederation-metadata.xml"
backingFile="/opt/shibboleth-idp/metadata/ukfederation-metadata.xml">
<MetadataFilter xsi:type="ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
<MetadataFilter xsi:type="RequiredValidUntil" xmlns="urn:mace:shibboleth:2.0:metadata"
maxValidityInterval="2592000" />
<MetadataFilter xsi:type="SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata"
trustEngineRef="shibboleth.MetadataTrustEngine"
requireSignedMetadata="true" />
<MetadataFilter xsi:type="EntityRoleWhiteList" xmlns="urn:mace:shibboleth:2.0:metadata">
<RetainedRole>samlmd:SPSSODescriptor</RetainedRole>
</MetadataFilter>
</MetadataFilter>
</MetadataProvider>
Note that the maxValidityInterval value is changed from "604800" to "2592000" (i.e. from 7 days to 30 days), which is a security measure that causes metadata to be rejected whose root element does not contain a validUntil attribute, or whose validity period exceeds 30 days.
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> section, ensure that the private key and certificate you intend to use for the UK federation trust fabric are referred to. The Shibboleth installation process generates a long-life self-signed certificate which is saved to the credentials subdirectory of the Shibboleth installation directory. If you intend to use this certificate for the federation trust fabric then you won't need to change anything here. However, it should be noted that at the time of writing, there are some service providers in the UK federation that will not accept self-signed certificates from client IdPs.
Please note: If you do decide to use the self-signed certificate then it will need to be embedded in the UK federation metadata, which requires a verification procedure by the federation team. A member of the team will arrange to call your management liaison at a publicly available telephone number and ask for the SHA1 fingerprint of the certificate, which they will compare with the fingerprint of the certificate submitted at registration. On a Windows system you should be able to view the certificate and thus the SHA1 fingerprint simply by opening the certificate file. On a Unix or Linux system you can view the fingerprint with the OpenSSL command given near the end of this section (replacing "ukfederation.pem" with the name of your certificate).
If you decide to use an alternative certificate, eg. a commercial SSL certificate purchased from a certification authority, then you will need to edit the <security:PrivateKey> and <security:Certificate> lines to refer to its private key file and certificate file (or alternatively rename/move the private key and certificate files to the locations referred to by those lines).
Finally, ensure that the <security:TrustEngine> section 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>
Download the UK federation signing certificate into the credentials subdirectory from ukfederation.pem. To avoid being spoofed into releasing your users' attributes to fake service providers, you should verify the SHA1 fingerprint of the certificate. On a Windows system you can view the certificate details by opening the certificate file. On a Unix or Linux system you can use this OpenSSL command:
openssl x509 -fingerprint -sha1 -in ukfederation.pem -noout
The correct fingerprint value must be determined offline from a member of the UK federation team to guard against the possibility of this web site being compromised. The team can be contacted via the Help desk.
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 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="LDAPDirectory"
xmlns="urn:mace:shibboleth:2.0:resolver:dc"
ldapURL="ldap://ldap.uni.ac.uk"
baseDN="OU=Users,DC=uni,DC=ac,DC=uk"
principal="uid=myservice,ou=system"
principalCredential="Password">
<FilterTemplate>
<![CDATA[
(uid=$requestContext.principalName)
]]>
</FilterTemplate>
</resolver:DataConnector>
Notes for Active Directory users:
- 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 thebaseDNfield. - 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. - The attribute used to look up the user is
sAMAccountNamein Active Directory (replacinguidin<FilterTemplate>in the example above and inlogin.config). - In the eduPersonTargetedID section below it is recommended for Active Directory users to use the objectSid to source eduPersonTargetedID. In order to work around issues described here you need to add this property to the above <DataConnector> after the <FilterTemplate> element:
<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="Scoped"
xmlns="urn:mace:shibboleth:2.0:resolver:ad"
scope="uni.ac.uk" sourceAttributeID="eduPersonAffiliation">
<resolver:Dependency ref="myLDAP" />
<resolver:AttributeEncoder xsi:type="SAML1ScopedString"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" />
<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.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="ComputedId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
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) -->
<resolver:AttributeDefinition id="eduPersonTargetedID.old" xsi:type="Scoped"
xmlns="urn:mace:shibboleth:2.0:resolver:ad"
scope="uni.ac.uk" sourceAttributeID="computedID">
<resolver:Dependency ref="computedID" />
<resolver:AttributeEncoder xsi:type="SAML1ScopedString"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
name="urn:mace:dir:attribute-def:eduPersonTargetedID" />
</resolver:AttributeDefinition>
<!-- eduPersonTargetedID (new) -->
<resolver:AttributeDefinition id="eduPersonTargetedID" xsi:type="SAML2NameID"
xmlns="urn:mace:shibboleth:2.0:resolver:ad"
nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
sourceAttributeID="computedID">
<resolver:Dependency ref="computedID" />
<resolver:AttributeEncoder xsi:type="SAML1XMLObject"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
<resolver:AttributeEncoder xsi:type="SAML2XMLObject"
xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
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 here 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.
It is unwise to release all possible attributes to all SPs. You should ask the service providers used by your organisation to tell you their attribute requirements, but a good rule of thumb is to release eduPersonScopedAffiliation and eduPersonTargetedID to any SP in the federation. Some SPs require either eduPersonPrincipalName or eduPersonTargetedID; given this choice it is preferable to release eduPersonTargetedID. Indeed, there are DPA issues associated with the release of eduPersonPrincipalName; please see section 7.2 of the federation's Technical Recommendations for Participants.
This AttributeFilterPolicy rule releases all permissible values of eduPersonScopedAffiliation and eduPersonTargetedID (both forms) to any UK federation SP:
<AttributeFilterPolicy>
<PolicyRequirementRule xsi:type="saml:AttributeRequesterInEntityGroup"
groupID="http://ukfederation.org.uk" />
<AttributeRule attributeID="eduPersonScopedAffiliation">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="eduPersonTargetedID">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
<AttributeRule attributeID="eduPersonTargetedID.old">
<PermitValueRule xsi:type="basic:ANY" />
</AttributeRule>
</AttributeFilterPolicy>
Information about the attributes required by many federation service providers can be found here.
Testing
You can test your configuration by going to this UK federation test SP:
If you select your own IdP site from the WAYF 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.
Additionally, the Shibboleth 2 test SP can be used to test the Artifact profile, and to test SAML2 flow. The link to test the Artifact profile should be obvious. To test the SAML2 flow, click on the "Rod's Discovery Service" link. The Discovery Service is capable of using SAML2 whereas the current federation WAYF is SAML1 only.
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.