Shibboleth

Summary

The Shibboleth project seeks to facilitate the sharing of information about users in a secure, privacy-preserving manner. Stated simply, Shibboleth's goal is to determine if a person using a web browser (or other access mechanism) has permission to access protected resources. Shibboleth is called privacy-preserving because it makes its authorization decisions based on a person's attributes rather than their identity. It is important to understand the following distinction: Shibboleth provides authorization services, NOT authentication. Authentication is provided via existing authentication tools. Once a user is authenticated, Shibboleth simplifies the problem of determining which resources the user can access. For this reason, Shibboleth has been referred to as a Single Sign On service. Shibboleth communicates attributes between Service Providers (SP) and Identity Providers (IdP) using OpenSAML (Open Source Security Assertion Markup Language)

Example

Student 1 at University A authenticates to University A. University A has a partnership with University B and Service C. After sign on, a Shibboleth IdP can allow Student 1 access not only to Uni. A's resources, but also those available at Uni. B and Service C without the student needing to sign in to each service at Uni. B and Service C. When Student 1 attempts to access resources at B or C, the SPs at each respective location ask 1 for his attributes and pass them along to the IdP. The IdP responds with further attributes and access control decisions are made based on those attributes. A conglomeration of SP's and IdP's that have trusted relationships between one another is called a Federation.

For a further introduction to Shibboleth see this Shibboleth Introduction and the Shibboleth FAQ. For more example benefits of Shibboleth, See this page.

GROW and Shibboleth

The Grid Research and educatiOn group @ ioWa decided to test an installation of a Shibboleth IdP and to integrate it with Globus Toolkit 4 which would allow Shibboleth to control access to grid resources.

Set up and Requirements

There are many different options for setting up a Shibboleth IdP including:

  • Shibboleth + Tomcat
  • Shibboleth + IIS + Tomcat + ISAPI
  • Shibboleth + Apache + Tomcat + mod_jk

Our Setup

The last is the most prevalent installation and it is by far the best supported. As such, GROW installed the following main software packages:

  • Apache 2.2.3
  • Tomcat 5.5.20
  • Shibboleth IDP 1.3.1 (when 2.0 is available, it is highly recommended to switch)
  • JDK 1.5
  • mod_jk 2.0.52 (This is the connector between Tomcat and Apache which allows the webserver to pass shibboleth requests to tomcat and thus to the web app).
  • Gridshib IdP 0.5.1 and Gridshib for Globus Toolkit 4.0

In addition, the following are either necessary at some point during the process or highly recommended:

  • apr 1.2.7 + apr-util
  • ntp 4.2.2 (Shibboleth requires some sort of clock synchronization to ensure freshness)
  • Apache Ant 1.6.5 (ant is used to build the Shibboleth IdP and deploys the war file to Tomcat automatically)
  • OpenSSL
  • commons-logging 1.1
  • logging4j 1.2.14 (Essential to debug the Shibboleth IdP webapp and Tomcat, don't bother trying to do so without integrating log4j and Tomcat.)

Pre-Shibboleth Installation Steps

The Shibboleth IdP obviously has a lot of interdependencies and it is best to be certain components are working at each step of the install before proceeding on to the next. The general installation steps are as follows:

  1. Install Java, j2sdk and j2re
    1. Make sure $JAVA_HOME is set and add it to your profile.
  2. Install apr + apr-util
  3. Install ant
  4. Make sure openSSL is installed
  5. Install Apache, either via yum/rpm/up2date/etc and be sure to include mod_ssl
    1. If compiling yourself, it is a good idea to compile it with mod_so so you can add modules at runtime if necessary.
    2. As mentioned above, Shibboleth does not contain a built in authentication mechanism and so for our purposes we also installed basic authentication modules as well.
      • Protect /shibboleth-idp/SSO, /shibboleth-idp/AA, /shibboleth-idp/CertificateRegistry in <location> blocks in httpd.conf and set up an authentication mechanism for those locations.
      • Alternatively, you can also use LDAP
      • Shibboleth uses SSL on both ports 443 and 8443 so it is necessary to have Apache listen on both ports and to enable ssl on both as well(either in httpd.conf or ssl.conf)
      • Note: Remember to check firewall rules, you will likely have to add new rules to allow communication over 8443 and may need further modification.
      • Note: It's acceptable to use the ssl keys provided with Apache for testing but shortly you will have to generate/acquire the keys you want the IdP to use and to include them in ssl.conf
  6. Install Tomcat 5.5
    1. Be certain to set $CATALINA_HOME
    2. Create user/group for tomcat to run as and chown tomcat to that user.
    3. Note: If running a system with selinux, be certain httpd and tomcat are running in the same security container
  7. Verify that both Apache and Tomcat are functional and logging.
    1. Note: Watch permissions on log directories.
  8. Install and configure mod_jk (make sure to include apxs if your Apache install included apxs)
    1. Include mod_jk.so in httpd.conf
      • JKMount shibboleth-idp/* ajp13 and
      • JKMount jsp-examples/* ajp13 (if you want to test the connection between Apache and Tomcat)
    2. Make worker.properties (see link to Shibboleth wiki below for an example)
    3. Check that Tomcat and Apache can communicate by requesting https:<myserver>/jsp-examples/index.html, substituting your server name for <myserver>. Assuming everything is setup correctly, you are now prepared to install the Shibboleth IdP I found these instructions useful for getting apache and tomcat to communicate via mod_jk ===Installing the IdP=== Note: If at any point you need assistance, we highly recommend you ask the incredibly helpful folk on the list SHIBBOLETH-USERS. Instructions for joining are available at: http://shibboleth.internet2.edu/support.html - Get the IdP code from The Shibboleth Project download page and untar it into a directory (referred to from here on as $SHIB_DIST$) - Copy the .jar files in $SHIB_DIST$/endorsed/ to $CATALINA_HOME/common/endorsed - Do ./ant in $SHIB_DIST$. We answered: - Y - shibboleth-idp - 1 - /usr/local/shibboleth-idp - $CATALINA_HOME - Again, check permissions, especially on log directories. - Check the file idp.xml and make necessary changes to customize it for your server. - Restart httpd/tomcat and you should see /shibboleth-idp listed under the webapps on the manager screen (http:<myserver>:8080/manager/html)
    4. You should also be able to go to https:<myserver>/shibboleth-idp/Status and receive: AVAILABLE - Also check https:<myserver>/shibboleth-idp/AA or https:<myserver>:8443/shibboleth-idp/SSO. You should receive a Shibboleth Identity Provider failure screen which includes the Shibboleth logo. The Shibboleth wiki contains a useful install doc from which much of the above info is taken. It also includes useful code examples for httpd.conf, worker.properties &etc. In the future, our config files will be posted as examples as well. ===Testing the IdP installation=== The first and most important step is to improve the logging capabilities of Tomcat and Shibboleth by installing log4j. There are very detailed instructions for creating useful container logs available here. When you have finished installing log4j you should have useful logs being generated, particularly in /etc/httpd/logs/ (typical location for apache logs + ssl logs, assuming default install) and $CATALINA_HOME/logs/ (you should have tomcat.log, shibboleth-idp.log and shibboleth-wayf.log). There are also shibboleth logs located at $SHIB_DIR$/logs (you should have shib-error.log and shib-access.log). Set the logging levels to debug and restart httpd and tomcat. Check for any errors and attempt to fix them before proceeding. It is very difficult to install gridshib on top of a faulty Shibboleth installation. After you have decent logging, attempt to get the IdP to pass attributes to a test SP at www.testshib.org. Instructions are available here. GROW registered with OpenIdP.org. Once you have created an account, log in here and register the IdP here. Once you have done so, continue following the instructions at www.testshib.org. A successful exchange of attributes will generate a page containing the following text: >Shibboleth-protected TestShib Content >This page is protected by the TestShib Service Provider. If you're reading this, your IdP successfully provided authentication >information. If you have data about you and an assertion below, then your IdP also released attribute and authorization >information. Cool! >If something's missing, you should check your IdP's shib_error.log. >TestShib also allows you to check out the last lines of or on the SP side. >Generally, for WARN level information(or worse) for indications as to the problem. Check the Shibboleth Wiki to see if you can find >a match. If that doesn't help, please check our mailing list archives, then ask on the mailing list. >Here are some pieces of information I can tell about you using the information Shibboleth gives me: This should be following by several attributes (depending on how you have configured your IdP.) * Again, unless things are working exactly as they should, consider joining SHIBBOLETH-USERS. Instructions for joining said list are available at: http://shibboleth.internet2.edu/support.html * A few common errors are detailed at: https://spaces.internet2.edu/display/SHIB/CommonErrors ===GridShib=== When you have ascertained that your IdP is capable of delivering attributes, you next need to integrate it with the GridShib IdP plug-in. There are two portions of the GridShib IdP plugin, GridShib for Shibboleth is integrated with the Shibboleth IdP and the GridShib for Globus Toolkit with Globus Toolkit 4.0. The two can be installed and tested separately but both need to be correctly installed to guarantee functionality of the GridShib plugin. Before beginning with GridShib, it is a good idea to install and configure the Globus Toolkit. ==Installing Globus Toolkit== The easiest way to install Globus is via the VDT's pacman package. Instructions are available here. The process involves installing pacman and then a VDT package. We installed the Globus-WS flavor. After installing GT4.0, be certain to following the steps in $GLOBUS_LOCATION/post-install/README to complete setting up Globus. Also, note that whenever you source Globus it is very likely to change your $PATH and $CLASSPATH variables so you may need to adjust them as well. ==Installing GridShib for Shibboleth== Here is a link to gridshib-idp-0_5_1 tarball Here is the installation document for gridshib-idp-0_5_1 The instructions below are, by and large, reproduced from that document with a few notes added. Installation is fairly simply: - Untar and expand the package into $SHIB_DIST$. This will create a $SHIB_DIST$/custom/gridshib-idp-0_5_1 folder as well as $SHIB_DIST$/customer/derby-10_2_3 folder. (Version numbers may change if you are using more recent distributions.) - Remove $IDP_HOME$ to ensure you are getting a fresh install (save idp.xml and any other altered config files). - do ./ant install in $SHIB_DIST$ and it will re-install the IdP and re-deploy the Tomcat WAR file. - Copy your idp.xml over the fresh version and add the following to idp.xml: <RelyingParty name=“urn:mace:gridshib:metadata:sp” signingCredential=“example_cred”> <NameID nameMapping=“x509”/> </RelyingParty> And: <NameMapping xmlns=“urn:mace:shibboleth:namemapper:1.0” id=“x509” format=“urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName” class=“edu.internet2.middleware.shibboleth.common.provider.GridShibNameIdentifierMapping”/> Then include: <MetadataProvider type=“edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata” uri=“file:$IDP_HOME$/etc/$EXTENSION_NAME$/gridshib-sp-metadata.xml”/>

Substitute $IDP_HOME$ and $EXTENSION_NAME$ for their actual values.

Also copy: $SHIB_DIST$/custom/$DIST_NAME$/data/arp.user.gridshib.xml to $IDP_HOME$/etc/arps/

Add the following to $IDP_HOME$/resolver.xml:

SimpleAttributeDefinition

  id="urn:mace:dir:attribute-def:eduPersonPrincipalName"
  smartScope="$SCOPE$">
  <DataConnectorDependency requires="echo"/>
</SimpleAttributeDefinition>

$SCOPE$, in our case, was uiowa.edu. Make sure the scope matches the shibmd scope in idp.xml!

Next, to use the GridShib to submit jobs, it needs a place to store certifictaes. This is referred to as the CertificateRegistry. To set up the CertificateRegistry complete the following steps:

  1. Examine the file: $SHIB_DIST$/build.properties and find the line: idp.deployment.descriptor. (In our case, and in most non-customized cases, it will be dist.idp.xml.
  2. Add the following lines to $SHIB_DIST$/webAppConfig/dist.idp.xml:
<servlet>
    <servlet-name>CertificateRegistry</servlet-name>
    <display-name>Certificate Registry Servlet</display-name>
    <servlet-class>edu.internet2.middleware.shibboleth.idp.CertificateRegistry</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>CertificateRegistry</servlet-name>
    <url-pattern>/CertificateRegistry</url-pattern>
</servlet-mapping>

Note that these lines must be in an appropriate place in the file. I.E. the <servlet> tag must be placed with the other servlets and the <servlet-mapping> tag must be with the other servlet-mappings.

You can now begin producing metadata for the IdP. Producing metadata is currently beyond the scope of this document.

Testing GridShib for Shibboleth

There are a number of tests bundled with GridShib, the two most necessary are the gridshib-db-test and gridshib-aa-test.

  • gridshib-db-test

To complete this test on Shibboleth 1.3.1 with the gridshib plug-in installed, first check that the file $IDP_HOME$/endorsed/derby.jar is not an empty archive (i.e.” jar tf derby.jar” should produce a long list of files). If it is not, replace it with the complete version that should be located at: $SHIB_DIST$/custom/derby-10_1_2_3/dist/derby.jar.