Shibboleth is an Internet2 project designed to make it possible to share resources securely and anonymously. Instead of the user presenting credentials to each resource, their home institution sends a set of attributes describing the user that need not identify them personally. For example, if a resource is licensed for use by members of staff at an institution, it will only need to receive an attribute which asserts that the user is indeed a member of staff. Further details are available from the Shibboleth site.
Shibboleth has a complex architecture with a large number of components, but can basically be divided into two: the origin and the target. The target protects the resource, while the origin ensures that users are authenticated and passes on their attributes to the target on request. This section describes how to install the origin. It is only necessary to install the target if there are resources which your institution wishes to share with a specific community.
The origin has two components, the handle service (HS) and the attribute authority (AA). The handle service is the component of Shibboleth through which the user authenticates. Typically, they will be redirected to it by a Shibboleth target run by the resource provider via a WAYF ('where-are-you-from' service) provided by a federation of institutions and resource providers of which the user's institution is a member. The AA retrieves information about the user from the institutional directory system, and forwards these to the target according to the origin attribute release policy.
Time required: 3 days.
Skill required: Some sysadmin experience to install; and a basic knowledge of XML for configuration.
To realise the benefits of a Shibboleth origin, it is necessary to be a member of a cooperative association or federation. This basically is a group of institutions and resource providers, who have common policies and generally are able to access the same material. The technical and organisational issues relating to federations have been further explored by InQueue. The installation should ideally be completed before the application to join a federation is made, as the process will need information that is unlikely to be available before starting out, and there may be testing of your installation required. The application needs to be made before the origin can come into use.
(For further information, see also the installation instructions (deployment guide) on the Shibboleth web site.)
The software should ideally be installed in the directory suggested in the deployment guide. Although this is not mandatory, putting it elsewhere may cause complications in the subsequent configuration. This location will require root access to the machine. As root, change to the install directory:
# cd /opt
download the software:
# wget http://wayf.internet2.edu/shibboleth/shibboleth-origin-1.1.tar.gz
and open the archive:
# tar zxvf shibboleth-origin-1.1.tar.gz
This process is basically the same as that for the CAS. The shibboleth.war file needs to be copied to the right Tomcat directory, and then needs to load the application. Again, set the location of Tomcat as an environment variable. If your copy of the software was installed from source, it is likely to be in /usr/local/tomcat. Alternatively, if it was installed as a RedHat rpm, it should be in /var/tomcatn, where n is the major version number (i.e. 4 for Tomcat 4.1.0, etc.). For example,
# export TOMCAT_HOME=/usr/local/tomcat
for the source code installation.
cp /opt/shibboleth-origin-1.1/dist/shibboleth.war $TOMCAT_HOME/webapps/
The only extra step needed here is to copy some Java libraries to the endorsed directory of your installation, so that they can override the libraries supplied as part of the Sun Java installation. To do this:
# cp /opt/shibboleth-origin-1.1/endorsed/*.jar $TOMCAT_HOME/common/endorsed
Note that this directory may not be in the same place as different versions of Tomcat or other Java application servers, so you may need to refer to your documentation if this command produces the following error:
cp: copying multiple files, but last argument `/usr/local/tomcat/common/endorsed' is not a directory Try `cp --help' for more information.
On how to use Tomcat to deploy the software, see our associated Tomcat documentation.
While Apache stores server certificates as files, the Shibboleth origin accesses them from a protected keystore (a database of keys and certificates). This can be accessed using the keytool utility that is part of the Java installation. A sample file is supplied as part of the origin ($TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks), but this needs to have the server certificate added to it. (If so desired, another keystore can be used instead.)
First, you will need to locate the keytool utility. It will be $JAVA_HOME/bin/keytool, where $JAVA_HOME is the location of your Java installation (e.g. /usr/local/j2sdk1.4.2/). To make it easier to use the utility, you should put it into your path:
# export PATH=$PATH:$JAVA_HOME/bin
(where either you already have the JAVA_HOME environment variable set or you replace it with the directory containing your Java installation). There are several actions you might want to take with the keystore. The procedure is only described for servers that already have server certificates. (Keytool can be used to generate requests to certificate authorities to obtain certificates. This is the main mechanism described in the origin deployment guide.) The keytool utility will not actually add existing certificates to a keystore, but the Shibboleth origin includes a utility to do this.
Before adding the server certificate to the keystore, you will need to export the certificate key in the right format, and create a certificate bundle (a file containing multiple certificates) which includes the CA root certificate and any intermediate certificates in the trust chain used to authenticate your server certificate. Convert the private key to unencrypted DER-encoded pkcs8 format:
# openssl pkcs8 -in yourkey.enckey -topk8 -nocrypt -outform DER -out yourkey.der.pkcs8
where yourkey.enckey is the filename of your private key (found in /etc/httpd/conf/ssl.key), and yourkey.der.pkcs8 is the name of the exported DER encoded pkcs8 format file. To create the certificate bundle:
# cat servercert.cert intermediate.cert caroot.cert > cert.bundle
where the certificate files listed in the first part are respectively your server certificate, any intermediate certificate(s) in the chain, and the CA root certificate. Note that if you cannot find the root certificate, then it is probably also contained in the file /etc/httpd/conf/ssl.crt/ca-bundle.crt that is distributed with the Apache web server, or can be exported from the certificate store of a web browser.
| Task: | Change keystore password |
|---|---|
| Method: | # keytool -storepassword shibhs -keystore $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks -new newpassword -storepass shibhs |
| Notes: | The password in the keystore on download is set to be shibhs. Replace
newpassword with the new password you choose. |
| Task: | Import existing certificate |
| Method: | # $SHIB_HOME/bin/extkeytool -importkey -alias shibkeyalias -keystore $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks -storepass password -keypass keypassword -certfile cert.bundle -keyfile yourkey.der.pkcs8 -provider org.bouncycastle.jce.provider.BouncyCastleProvider |
| Notes: | You should set the SHIB_HOME environment variable to the location of the
Shibboleth origin installation before carrying out this task:
# export SHIB_HOME=/opt/shibbolethReplace shibkeyalias with an alias to be used to identify the key, storepass with the password to the keystore, and keypassword with a password to be used to protect access to the key. |
| Task: | Check certificate now contained in keystore |
| Method: | # keytool -list -v -keystore $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks -alias shibkeyalias -storepass yourkeystorepassword |
| Notes: | If this works, you should see a long list of the attributes of the various certificates which made up the bundle you imported. |
Now delete the unencrypted version of your server certificate key, as it may compromise system security:
# rm yourkey.der.pkcs8
(As root, you will need to confirm that you wish to delete the file.)
First, we need to configure the web server components to be able to serve the Shibboleth origin components. Assuming that mod_jk is configured for the CAS already, the webserver configuration that is needed for the Shibboleth origin should be added first (after the equivalent line for the CAS in the appropriate configuration file (either httpd.conf or mod_jk.conf)):
JkMount /shibboleth/* ajp13
If left in its default state, the Tomcat configuration file server.xml is not compatible with the needs of Shibboleth. A copy of a compatible version of the file is available from the SECURe website:
# wget http://www.angel.ac.uk/SECURe/software/server.xml
This file needs to be copied over the existing one. You may wish to save a copy of the original file elsewhere before doing this.
# mv server.xml $TOMCAT_HOME/conf/
(As the root user, you will need to confirm that it is your intention to over-write the file). After doing this, you will need to reload the Shibboleth origin application into Tomcat (see our associated Tomcat documentation).
For security reasons, Shibboleth should be run on a secure web server. This is achieved by putting the following lines in the Apache configuration file (specifically, in the configuration for the SSL virtual host between <VirtualHost _default_:443> and </VirtualHost>):
<Location /shibboleth/AA> SSLVerifyClient optional SSLOptions +StdEnvVars +ExportCertData </Location>
This defines the property AAURL used below.
The HS also needs to have a defined location block in the web server configuration. By using the web server to protect the HS via CAS, you will define how the user authenticates to Shibboleth, and hence how they are authorised to access target sites. To protect the HS, add the following lines to your httpd.conf file, again in the secure web server virtual host (with appropriate modifications to the AuthName):
<Location /shibboleth/HS> AuthType CAS AuthName "Institution Internet2 Handle Service" require valid-user </Location>
Information on how to configure the Shibboleth origin is contained in the Tomcat architecture, principally in $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/origin.properties. This file has the format "property name = property value". Care must be taken to ensure that the entries in this file are consistent with those elsewhere in the configuration. All pathnames are relative, and have an effective root path of $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/ (in other words, a filename that is not given a full path is assumed to be somewhere relative to this directory). To specify files outside of the webapp, use a full URI such as file:///usr/local/shibboleth/. The following table is a list of the values to edit.
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer |
|---|---|
| Value: | The domain name of the machine on which the origin runs. It needs to match the CN of the server certificate referenced below. |
| Example: | secure.institution.ac.uk |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName |
| Value: | This value is assigned by the federation that you will join. |
| Example: | urn:mace:inqueue:institution.ac.uk |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl |
| Value: | The Attribute Authority URL, as defined above. |
| Example: | https://secure.institution.ac.uk/shibboleth/AA |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath |
| Value: | Location of the keystore containing the X.509 certificate to be used by the HS (probably a copy of the server certificate; see above for details on how to set this up). |
| Example: | /conf/keystore.jks |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword |
| Value: | The password required to access the keystore (which can be set with the keytool utility as described above). |
| Example: | shibhs |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias |
| Value: | The name used in the keystore to refer to the key matching the certificate. |
| Example: | hskey |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword |
| Value: | The password associated with the key (may be different from the keystore password). |
| Example: | hskeypwd |
| Property: | edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias |
| Value: | The name given to the certificate. This is an optional parameter; if it is omitted, assumed to be the same as the key alias. |
| Example: | servercert |
| Property: | edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName |
| Value: | The name of the Attribute Authority (the part of Shibboleth which returns certificated user attributes as determined by the release policies). This is usually the name of the machine on which the origin runs. |
| Example: | secure.institution.ac.uk |
| Property: | edu.internet2.middleware.shibboleth.audiences |
| Value: | URI of the federation to which the origin is affiliated (supplied by the federation upon approval of membership). |
| Example: | urn:mace:inqueue |
It is likely that the default Shibboleth origin logging configuration (sending error messages to the console) will not be very useful for testing purposes. The log configuration is set in the file $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/log4j.properties. This has the same format as origin.properties: "property=value"; lines are commented by prefacing them with "#". Comment out all the lines of the default configuration section, and uncomment those in the section entitled "The following block represents an example of how to direct logging output to a file". You might want to change the value for the logfile from log4j.appender.file.File to, say, /var/log/shibboleth.log.
The logging is fairly verbose. For example, a line of information is created for each attribute successfully resolved from the directory. This can be changed by setting the log4j.rootCategory property (though you will probably want to leave it at "INFO" until you're happy that the origin is working correctly). Possible logging levels, in order of terseness, are: "DEBUG", "INFO", "WARN", "ERROR" and "FATAL"; further information can be found in the log4j manual section on log levels.
The attribute configuration for the Shibboleth comprises two parts: the attribute resolver, which determines how to get the attributes describing a user from your institutional directory; and the attribute release policy (policies), which determines how these attributes are exposed to resource providers.
The resolver is configured in the file $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml. (If you want to use a file with a different name, it is possible to do this by changing the value of edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig in the origin.properties file.) This file is in an XML format, and a description follows. However, if you just want to get the Shibboleth origin working, you need to make two small changes. There are two commented out attribute definition tags (i.e. ones preceded by <!-- and followed by -->): eduPersonScopedAffiliation and eduPersonPrincipalName. These need to be uncommented, and have the smartScope attribute changed to the domain name submitted to the federation which you are joining. This simple configuration will not actually obtain the user details from your institution directory, and is suitable only for testing.
More complex configuration than this will therefore be needed in practise. The file resolver-ldap.xml provides a more comprehensive example of a resolver file that connects to an LDAP directory, and the simplest way to configure the resolver is to edit this file and replace the existing resolver.xml (alternatively, you can save it with another name and change the edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig property value in the origin.properties file - and remember to uncomment it as this property is commented out in the file as shipped with the release!). The same changes to the smartScope attributes described above will need to be made here. If your institutional directory supports secure connections, you need to edit the JNDIDirectoryDataConnector tag which has the comment "An example of how to do a simple ldap bind over SSL" (this should be uncommented and the others commented out). You need then to edit the first tag of this name in the file. The sub-tags which need to be changed are:
The actual attribute definitions are easiest to set by copying existing ones. Notes are given in the deployment guide that explain the structure of the file in more detail. Remember that setting up attribute definitions in this file does not actually mean they will be released to a target. Defined attributes merely become available to the AA for release as determined by an attribute release policy.
One other aspect which may prove confusing is the tag "PersistentIDAttributeDefinition", which defines the calculation of a one-time identitifier for a user (which is by its nature not something that can just be obtained by querying a directory). The idea is basically to use data from the keystore as salt for the randomisation process.
A utility is provided in the Shibboleth origin software for testing the attribute definitions once the file is ready. To use this, you must have the SHIB_HOME environment variable correctly set:
# export SHIB_HOME=/opt/shibboleth/
JAVA_HOME also needs to be correctly set. The utility is found at $SHIB_HOME/bin/resolvertest, and to run it you need a valid userID; the utility returns all the attributes that it can resolve based on the information in the resolver file. (Note that this does not mean that these attributes are released to targets.) To use it, type:
# $SHIB_HOME/bin/resolvertest --user=userid --file=file://$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml
replacing "userid" with your valid userID. You should see a series of attribute values that look like:
<?xml version="1.0" encoding="UTF-8"?>
<Attribute
AttributeName="urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation"
AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri" xmlns:typens="urn:mace:shibboleth:1.0">
<AttributeValue xsi:type="typens:AttributeValueType">Physics Department</AttributeValue>
</Attribute>
If you fail to get the attributes from the directory, you should see some self-explanatory error messages.
The Shibboleth origin supports multiple attribute release policies (henceforward ARPs), so that individual users can customise which attributes are released (e.g. to allow an email address to go to a target which offers more facilities for non-anonymised users). These are configured by a file per policy; the directory containing the policies is configured with the edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path property in the origin.properties file. There are two types of ARP, as you might expect from the foregoing description: the site ARP stored in the file arp.site.xml and user ARPs stored in files with names including the userID. When a user has his/her own ARP, this is applied in addition to the site ARP.
ARPs have an XML file format, and it is simplest to proceed to begin with by editing the existing site ARP file. (Web based editors are due to be developed for user ARPs, but these are not yet ready.) Inside the root tag there are two possible subelements. The Description element merely provides a container for text documenting the purpose of the ARP. A sequence of Rule elements then describes the policy. The Rule element has two kinds of children. The Target element describes which targets (and users) the ARP is valid for. For simplicity's sake, it makes sense to initially leave this with only the AnyTarget sub-element, to create ARP rules applicable to any target.
The actual attribute release is determined by the Attribute element. This has an attribute name, which contains the name of the attribute in URN form (e.g. "urn:mace:dir:attribute-def:eduPersonPrincipalName" rather than just "eduPersonPrincipalName"), and either the single sub-element AnyValue or a series of Value sub-elements, which (clearly) describe for which values of the attribute the rule applies. These subelements both have the attribute release, which takes the values "allow" or "deny", with the obvious meanings.
Advice on attributes to release initially.
InQueue is a federation intended for institutions and resource providers who want to try out Shibboleth functionality (for more details, see the InQueue Federation Policy and Configuration Guidelines). Currently, the Shibboleth origin only supports a single federation, but multiple federation support is to be phased in over the next few releases.
To join InQueue, send an email to inqueue-support@internet2.edu containing the following information:
-----BEGIN CERTIFICATE-----
When you receive your response from the federation, you need to put some of the details into your Shibboleth origin configuration. In $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/conf/origins.properties, the property edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName needs to be set to the value supplied by the federation. Similarly, edu.internet2.middleware.shibboleth.audiences needs to be set to the federation URI, which should also be supplied. The federation and targets within it may have requirements for eduPersonEntitlement attribute values, which need to be set in the institution directory as appropriate (since Shibboleth operates a federated trust model, it is up to you to ensure that an entitlement which implies that a user is a staff member should only be returned by a staff member).
Make sure you reload the origin application into Tomcat before proceeding to test it.
The InQueue federation provides a test target which you can use to evaluate your Shibboleth origin installation (allowing a short time for updating needed when you join the federation). This is located at https://wayf.internet2.edu/InQueue/sample.jsp. If everything is working correctly, this is what you should see when you click on the link:
There are four good places to look for help with problems with your shibboleth origin.
Copyright © SECURe Project Team, 2004
Document last updated: 03/06/04