Configuring a Shibboleth 1.3 Identity Provider for the UK Federation
Please note that as Shibboleth 1.3 reached its end-of-life at the end of June 2010, we recommend that you install version 2 instead.
This description assumes you have already installed the Shibboleth 1.3 software, as described in the documentation at https://spaces.internet2.edu/display/SHIB/InstallingShibboleth
First, find the Shibboleth idp.xml file, which is usually in the Shibboleth installation directory's sub-directory "etc". E.g. C:\shibboleth-idp\etc or /usr/local/shibboleth-idp/etc/.
Download into the directory containing idp.xml the Java keystore from ukfederation.jks. This keystore contains the federation's signing certificate. To avoid being spoofed into releasing users' attributes to fake service providers, ideally you should verify the SHA1 fingerprint of the certificate, like this:
keytool -list -v -keystore ukfederation.jks -alias ukfederation
Just hit Enter when prompted for the keystore password. You will be warned that the keystore's integrity cannot be verified automatically: 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.
Ensure that the $IDP_HOME variable is set to the directory where the IdP was unpacked, e.g. C:\shibboleth-idp or /usr/local/shibboleth-idp, then from the directory containing idp.xml use the metadatatool command as follows to download the federation metadata from ukfederation-metadata.xml and verify that it is signed correctly:
$IDP_HOME/bin/metadatatool --in [=http://metadata.ukfederation.org.uk/ukfederation-metadata.xml --keystore ukfederation.jks --alias ukfederation -o ukfederation-metadata.xml
You must also arrange to run this command regularly as a scheduled job, perhaps daily, to keep your copy of the metadata up to date. This ensures that your users are able to access new service providers joining the federation and prevents release of user attributes to service providers who have left the federation.
Editing idp.xml
Edit idp.xml as follows. Modify the AAUrl, defaultRelyingParty and providerId attributes of <IdPConfig> to:
<IdPConfig ... AAUrl="https://shibbox.uni.ac.uk:8443/shibboleth-idp/AA" defaultRelyingParty="http://ukfederation.org.uk" providerId="https://yourdomain.ac.uk/shibboleth">
Note that 'shibbox.uni.ac.uk:8443' and 'yourdomain.ac.uk/shibboleth' are placeholders, and need to be replaced by appropriate values.
The AAUrl and providerId values must match the 'AA Location' and 'Entity ID' values respectively which you gave when you registered your identity provider with the UK federation, and which are now embedded in your <EntityDescriptor> entry in ukfederation-metadata.xml. Note in particular that the above suggested value for providerId might not match the value you gave when you joined the federation: check the value in ukfederation-metadata.xml, which is definitive. The defaultRelyingParty is the URI of the UK federation, which is fixed.
Change the <MetadataProvider> URI (near the end of idp.xml) to refer to ukfederation-metadata.xml:
<MetadataProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata" uri="file://.../shibboleth-idp/etc/ukfederation-metadata.xml"/>
Back near the top of the file, within the <IdPConfig> element, modify the clause identifying the certificate to use when signing identity assertions for this federation:
<RelyingParty name="http://ukfederation.org.uk" signingCredential="ukfederationCred" schemaHack="true"> <NameID nameMapping="shm"/> </RelyingParty>
Note on schemaHack="true": Early versions of the Shibboleth SP rely on an XML parser that has significant bugs. Prior to Shibboleth 1.3, all versions of the IdP accommodated these bugs directly. From release 1.3 onwards, however, deployers must specifically add the attribute schemaHack="true" if they expect to be issuing attributes to older SP versions. It is recommended that this attribute be added, to enable interoperability with older SPs.
While you are just starting out, or trying to resolve a problem, it may be useful to change WARN to DEBUG in the <ErrorLog> element:
<Logging> <ErrorLog level="WARN" location="..." /> ... </Logging>
Specifying DEBUG causes the log file produced to be more comprehensive and informative, but much larger.
In the <Credentials> section, add a <FileResolver> clause defining the key and certificate files to use for the "ukfederationCred" signing credential:
<FileResolver Id="ukfederationCred">
<Key>
<Path>file://...path/to/shibbox.uni.ac.uk.ss.key</Path>
</Key>
<Certificate>
<Path>file://...path/to/shibbox.uni.ac.uk.ss.crt</Path>
</Certificate>
</FileResolver>
shibbox.uni.ac.uk.ss.crt is the self-signed trust-fabric certificate you created for yourself at the beginning of GetCertificate (not the browser-facing certificate you obtained from a CA). shibbox.uni.ac.uk.ss.key is the corresponding key. If you encrypted the key, a password must be given inside the <Key> element:
<Key password="your password">
That completes the editing of the idp.xml file.
Editing resolver.xml
eduPersonScopedAffiliation
Because UK federation service providers rely on the eduPersonScopedAffiliation attribute to identify users from your organisation, you must find the resolver.xml file for your IdP (in $IDP_HOME/etc) and edit it as follows. Uncomment the <SimpleAttributeDefinition> for eduPersonScopedAffiliation and change smartScope="shibdev.edu" to the security domain (scope) you specified when you registered your identity provider with the UK federation. For a main institutional identity provider this will usually just be of the form uni.ac.uk; for a test server, it might be shibbox.uni.ac.uk, etc. For example:
<SimpleAttributeDefinition
id="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"
smartScope="uni.ac.uk">
<AttributeDependency
requires="urn:mace:dir:attribute-def:eduPersonAffiliation"/>
</SimpleAttributeDefinition>
eduPersonTargetedID
The source for eduPersonTargetedID should be an appropriate field in the LDAP. It must be unique and not have the scope explicitly appended. The LDAP attribute against which the %PRINCIPAL% (login name) is matched suits this purpose. If possible, a field should be chosen that is unique over time as well as space, ie. no value of the field can ever be reused. If no such field exists then care must be taken (particularly for organisations asserting user accountability) to ensure that no value of the field chosen is reallocated to another user for at least two years after being cancelled.
Replace the scope "uni.ac.uk" with the domain for which the attribute is to be asserted, usually the domain of your organisation. The <Salt> is a constant, arbitrary value that you should choose once and keep secret. The value must be at least 16 characters long, otherwise the software will silently ignore it and expect the value to be supplied from a Java keystore. The Salt value is used to generate the persistent opaque identifier from the scope and the attribute chosen as the source as described above. Its purpose is to prevent attempts to work back from the opaque identifier to the user's identity by combining knowledge of the scope and the hash function used with an exhaustive search of the possible user ids.
Assuming then that the principal name is matched against a directory field called uid and this is to be used to seed eduPersonTargetedID, here is the code for the eduPersonTargetedID definition:
<PersistentIDAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonTargetedID" scope="uni.ac.uk" sourceName="uid"> <DataConnectorDependency requires="directory"/> <Salt>saltstring.......</Salt> </PersistentIDAttributeDefinition>
There also needs to be a data connector with an id of "directory", which is used to access the LDAP and should be of the following form; there should be a suitable one in the resolver.xml file already, which needs to be modified for your local configuration:
<JNDIDirectoryDataConnector id="directory">
<Search filter="uid=%PRINCIPAL%">
<Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
</Search>
<Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" />
<Property name="java.naming.provider.url"
value="ldap://ldap.uni.ac.uk:389 CN=Users,DC=uni,DC=ac,DC=uk" />
<Property name="java.naming.security.principal" value="ldapuser@uni.ac.uk" />
<Property name="java.naming.security.credentials" value="Password" />
</JNDIDirectoryDataConNector>
If your organisation uses Microsoft Active Directory then the objectSid is a better source for eduPersonTargetedID; the information and code can be found here.
The default Shibboleth attribute release policy does not release eduPersonTargetedID. You must therefore manually edit the arp.site.xml file to enable this feature, as described under Attribute Release below.
Restart the /shibboleth-idp web application (or restart Tomcat) to ensure that the updated files are in use.
Please note a caveat about the definition of eduPersonTargetedID in some older versions of the resolver.xml file.
Attribute release
The default arp.site.xml file shipped with Shibboleth releases eduPersonScopedAffiliation to any service provider, which is all that is initially required by many services. Some services will work better, by supporting personalisation, if eduPersonTargetedID is also released. The default arp.site.xml file can be modified to release eduPersonTargetedID as follows (with eduPersonAffiliation also removed, as this unscoped attribute is of limited use across a federation):
<?xml version="1.0" encoding="UTF-8"?>
<AttributeReleasePolicy
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:mace:shibboleth:arp:1.0"
xsi:schemaLocation="urn:mace:shibboleth:arp:1.0 shibboleth-arp-1.0.xsd" >
<Description>Simplest possible ARP plus targeted ID.</Description>
<Rule>
<Target>
<AnyTarget/>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
</AttributeReleasePolicy>
Additional attributes, e.g., eduPersonEntitlement, can be released similarly.
If you later decide to modify the attribute release policy so that these attributes are not universally released, you will need to add individual <Rule>s for each service that users should have access to. You can copy the <Rule>s needed from the list of examples below:
<Rule>
<Description>CAB Abstracts and "Land Life Leisure" at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:nevis.ed.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Digimap</Description>
<Target>
<Requester>https://geoshibb.edina.ac.uk/shibboleth</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
<!-- Following are optional but if present are used to pre-populate
the online user registration form. Since some of these are personal data,
the IdP should consider how it will meet its Data Protection Act
obligations before adding these to its configuration. -->
<Attribute name="urn:mace:dir:attribute-def:givenName">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:sn">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:mail">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:o">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:ou">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:title">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Film and Sound Online service at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:emol.sdss.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonEntitlement">
<Value release="permit">urn:mace:ac.uk:sdss.ac.uk:entitlement:emol.sdss.ac.uk:restricted</Value>
</Attribute>
</Rule>
<Rule>
<Description>EIG service at EDINA</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:eig.sdss.ac.uk</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>Internet2 Shibboleth Wiki</Description>
<Target>
<Requester>https://spaces.internet2.edu/shibboleth</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>MIMAS Landmap</Description>
<Target>
<Requester>urn:mace:ac.uk:sdss.ac.uk:provider:service:shibboleth-landmap.mimas.ac.uk</Requester>
</Target>
<!-- Minimal attribute set required is just ePPN: givenName, sn and ou are optional -->
<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>ScienceDirect</Description>
<Target>
<Requester>https://sdauth.sciencedirect.com/</Requester>
</Target>
<!--
No attributes are required: access is granted based on IdP entityID
but ePTI is leveraged if present.
-->
<Attribute name="urn:mace:dir:attribute-def:eduPersonTargetedID">
<AnyValue release="permit"/>
</Attribute>
</Rule>
<Rule>
<Description>EBSCOhost service</Description>
<Target>
<Requester>http://shibboleth.ebscohost.com</Requester>
</Target>
<Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation">
<AnyValue release="permit"/>
</Attribute>
</Rule>
Reconfigure Apache
Ensure that the <VirtualHost> context for the Shibboleth SSO service (usually /shibboleth-idp/SSO on the default HTTPS port 443) in the Apache config file httpd.conf (or the SSL config file ssl.conf) contains:
SSLEngine on SSLCertificateFile path/to/shibbox.uni.ac.uk.crt SSLCertificateKeyFile path/to/shibbox.uni.ac.uk.key
shibbox.uni.ac.uk.crt and shibbox.uni.ac.uk.key are the browser-facing certificate, which you obtained from a CA, and its corresponding key. Normally this will be a different certificate from the self-signed certificate used in <Credentials> above and for the attribute authority virtual host in the next section.
It is also desirable to configure Apache to send the certificate of the CA that signed the server certificate (and any other intermediate CAs) to the client browser. If this certificate chain is not provided, the browser may not be able to verify the certificate and may report an error to the user. The chain to use obviously depends on what CA signed the server certificate.
For JANET Certificate Service certificates, the chain comprises the intermediate CA certificates which accompanies your certificate in the zip file provided (see Submitting the Request at the end of GetJCSCert).
SSLCertificateChainFile path/to/JANET-intermediate-cert-chain.pem
For other CAs, the chain of intermediate certificates required (if any) will be described in their documentation for "how to configure your web server", and will often differ depending on the exact type of certificate.
Attribute Authority VirtualHost
The attribute authority is normally in a separate Apache <VirtualHost> context, on port 8443. The required configuration is different from the SSO service <VirtualHost> described above:
SSLEngine on SSLVerifyClient optional_no_ca SSLVerifyDepth 10 SSLOptions +StdEnvVars +ExportCertData SSLCertificateFile path/to/shibbox.uni.ac.uk.ss.crt SSLCertificateKeyFile path/to/shibbox.uni.ac.uk.ss.key
The certificate and key to use here are the trust-fabric self-signed (.ss) ones you created yourself, not the browser-facing ones you obtained from a CA.
Finally, you will need to restart Apache.
Testing
Once you have reconfigured Shibboleth and Apache as described above, you can test your setup by going to these UK federation test pages:
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.
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.
Keeping Metadata Refreshed
As mentioned previously, metadatatool should be run as a regular scheduled job, perhaps daily, to keep your site's locally cached copy of the UK federation metadata (ukfederation-metadata.xml) up to date.
Finally
Once your identity provider is in service, you might wish to contact those UK federation service providers with whom you have service agreements, to inform them that you now have an identity provider within the UK federation and wish your end users to be able to access services via that route. The information you give an SP depends on how it confirms that your organisation is a valid licence holder: they might, for example, wish to know the Shibboleth scope(s) which you are asserting.