In order to use the OhioLINK remote user proxy system, each institution will be responsible for setting up, customizing, and maintaining a Shibboleth Identity Provider (IdP) unique to their individual network configurations and security policies. OhioLINK will refer to these IdP's whenever authentication is required for a requested resource.
This document will explain the basics of the initial setup and configuration of an IdP. As each institution's configuration will differ with their unique network setup, it won't delve too far into specifics unless these specifics are pertinent to everyone's configuration. These instructions also demand a certain degree of experience with UNIX/Linux system configuration and administration. Assistance with the server operating system outside of Shibboleth itself is beyond the scope of this document.
The following hardware is sufficient for deploying an IdP that could be used to learn about Shibboleth and demonstrate a small exemplar use case (on the order of 25-40 logins per minute).
Pentium III class processor in the 1GHz range
Any Ethernet card
The following hardware is suited for a production deployment supporting around 150 simultaneous requests.
Xeon/Opteron class processor (mid-level spec)
Gigabit Ethernet card
To increase the availability the production machines should have their hard drives mirrored (RAID1). Also the use of multiple servers and load balancing hardware is suggested.
When purchasing production machines the general rule is "greater horsepower => greater performance" and "more processors => more horsepower". This doesn't hold true with the IdP. Java applications scale poorly across multiple processors (or processor cores). The most common JVM, Sun's, uses one processor core to run all of its Java code (it may use other cores for other tasks as discussed below). So, processor speed is the place to sink your money, not the number of cores.
Generally the IdP is run within Tomcat with an Apache HTTP server front-end. Apache 2 and Java 1.5 are recommended. Be sure to tune both Apache and the JVM used by Tomcat appropriately.
The most influential tuning within Apache is the MPM used and how it's configured. The worker MPM is strongly encouraged. We recommend very few servers and a fair number of threads within each (maybe 3-5 servers and 75-100 threads).
Proper tuning of the JVM is the single most important factor in IdP performance (assuming you don't choke connections with unreasonably restrictive Apache configs). Assuming a Sun JVM the following items should be configured:
Use the server VM instead of the client by using -server flag
Increase the amount of heap initially allocated using -Xms###M (where ### is the amount of memory to allocate, probably something around 256-512)
Increase the max amount of memory that can be used using -Xmx###M (where ### is the amount of memory to allocate, probably something around 1024-1536, don't go above 1800 as in most boxes this is the upper limit of JVM size, Solaris and 64bit OSs may be able to go higher)
If your hardware does have multiple processor cores turn on the throughput garbage collector using the -XX:+UseParallelGC flag
OhioLINK suggests the use of a reasonably modern version of Linux or UNIX for the IdP. It is possible that a Microsoft Windows server will suffice; however, we have no experience in this type of environment and won't be able to offer assistance. (If, however, you are able to get a Microsoft-based solution working then we'd be interested to know how so that we can assist others.)
A Shibboleth IdP configuration will vary from institution to institution based on how it authenticates its patrons. Many parts are the same, however, and this document will explain how to configure those parts. When aspects vary, it will be noted and only basic information will be given.
You will need to install the following:
The Apache Web Server with the following built in:
SSL encrypted connection support (mod_ssl)
External module support (mod_so)
The Tomcat Java servlet for executing the Shibboleth code through Apache
The mod_jk Apache module to connect Tomcat to Apache
A Java interpreter (Sun's is preferred)
If possible, it is best to install these via the operating system's package installer. This method makes installation easier, ensures that necessary supporting software is installed, handles system-specific cavets properly, and simplifies bug fixes and version updates. Instructions for installing and configuring these packages can be found in your operating system's documentation.
If you are unable to provide all of the require software via the distribution's package installer then you may be forced to install directly from source code.
Please refer to the software's included documentation and/or website for installation instructions.
Downloading & Installing Shibboleth
Shibboleth can be downloaded from Internet2 website. Be sure to get the “Identity Provider” software and not the “Service Provider” software.
Decompress the IdP package and change into the directory that it creates. Execute “echo $JAVA_HOME” to check your environment for an existing Java interpreter path variable. If nothing is returned, refer to the Java installation instruction for how to set one up. Once JAVA_HOME is properly set, execute “./ant install”. Be sure to remember what name you chose for the application and where you asked it to install as you'll need them later while configuring Apache.
Configuring Apache & Tomcat
Apache must be told to use the mod_jk Tomcat connector for Shibboleth-related activity. The following belongs in your httpd.conf file or an external configuration file called from within it:
<IfModule !mod_jk.c> LoadModule jk_module libexec/mod_jk.so </IfModule> JkWorkersFile /usr/local/tomcat/conf/jk/workers.properties JkLogFile /var/log/httpd/mod_jk.log JkLogLevel emerg JkMount /jsp-examples/* ajp13 # Change “shibboleth-idp” to what you installed the app under JkMount /shibboleth-idp/* ajp13
The paths should be changed appropriately for your particular installation choices.
The workers.properties file that the Apache conf file points to will also need some work. The following settings should be used:
# Define 1 real worker using ajp13 worker.list=ajp13 # Set properties for the ajp13 worker worker.ajp13.type=ajp13 worker.ajp13.host=localhost worker.ajp13.port=8009 worker.ajp13.lbfactor=50 worker.ajp13.cachesize=10 worker.ajp13.cache_timeout=600 worker.ajp13.socket_keepalive=1 worker.ajp13.recycle_timeout=300
Tomcat must also be configured to accept the authentication information coming in through mod_jk. In the server.xml file, locate the <Connector/> section for port 8009 and change it to resemble the following:
<!-- Define an AJP 1.3 Connector on port 8009 -->
enableLookups="false" redirectPort="8443" protocol="AJP/1.3"
request.tomcatAuthentication="false" address="127.0.0.1" />
You will also want to disable direct Tomcat access on port 8080 as mod_jk renders it unnecessary and it allows access to all Tomcat applications bypassing any Apache-based security that may be in place.
<!-- Disabled as mod_jk only requires port 8009
Restart Tomcat and Apache to load the new settings.
During initial setup and testing, a temporary login/password set should be created and the Shibboleth SSO section protected with it. This can be done using Apache's built-in authentication system. First create a login/password set using the htpasswd utility:
htpasswd -c /etc/shibauth.db testuser
htpasswd /etc/shibauth.db anotheruser
Once the test users have been added, add the following configuration block to the Apache configuration file:
<Location /shibboleth-idp/SSO> AuthType Basic AuthName "Shibboleth Testing Authentication" AuthUserFile /etc/shibauth.db require valid-user </Location>
Finally, you will need to set up the SSL portion of Apache. In addition to the usual HTTPS port (443), Shibboleth uses an additional encrypted port (8443) for its attribute authority. This is due to the use of a certificate authority not recognized by most browsers as a “legitimate” signer. Port 443 is what browsers will hit when they access the IdP and, therefore, should use a certificate signed by a recognized signature authority. Port 8443, however, requires a certificate signed by whichever Shibboleth federation you've chosen to join. OhioLINK requires that its users join the InCommon federation. (http://www.incommonfederation.org) Obtaining a certificate from them will be discussed later.
Referring to the Apache documentation, you will need to generate two SSL keys – one for the Handle Service (HS) on port 443 and one for the Attribute Authority (AA) on port 8443. The HS key you can have signed by whomever you see fit. (Even a self-signed cert will work for testing purposes.) The following is a portion of a working SSL virtualhost:
SSLCertificateFile ssl/idp-hs.cert SSLCertificateKeyFile ssl/idp-hs.key SSLCertificateChainFile ssl/cachain.pem #Optional but preferred
First we generated a key and stored it in idp-hs.key. Then, we generated a certificate signature request (CSR), put its contents into idp-hs.csr, and sent it to a universally recognized signing authority. The resulting certificate returned was put into idp-hs.cert. The certificate authority's (CA's) chain certificate is in cachain.pem. Many established CA's don't include a chain certificate; however, if one is provided then it's a good idea to use it. Even if your browser recognizes the CA, you cannot be sure that this will always be the case. (Different browser, different OS, older versions, etc.)
The second key that was generated will be sent to InCommon and signed. (See next section) It and the certificate returned will be used by the AA on port 8443. The following is an example of a working AA virtualhost:
# Shibboleth Attribute Authority Listen 8443 <VirtualHost *:8443> SSLEngine on SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP SSLVerifyClient optional_no_ca SSLVerifyDepth 10 SSLOptions +StdEnvVars +ExportCertData SSLCertificateFile /usr/local/shibboleth-idp/etc/idp-aa.cert SSLCertificateKeyFile /usr/local/shibboleth-idp/etc/idp-aa.key SSLCertificateChainFile /usr/local/shibboleth-idp/etc/incommon-ca.pem SSLCACertificateFile /usr/local/shibboleth-idp/etc/incommon.pem ErrorLog logs/idp_aa_error_log TransferLog logs/idp_aa_access_log </VirtualHost>
The key you generated is stored in idp-aa.key, the certificate returned from InCommon will go in idp-aa.cert, and the other two are provided for download on the InCommon website. You'll probably want to place these in the Shibboleth etc directory rather than where you normally keep web SSL certs as they will be used in the Shibboleth configuration as well. In addition, the CSR for the key was stored in a file called idp-aa.csr; however, it's not a part of the Apache configuration so it doesn't appear above.
Joining the InCommon Federation
In order to get the last piece for your Apache configuration, (idp-aa.cert) you will need to sign up with the InCommon federation.
Once you have an account set up, log into the “Administrative Login” section, go into the “Manage Identity Provider” subsection, and set up the following for your organization. (OhioLINK is used only as an example – your URLs will be different)
Organization Domain Name:
Artifact Resolution Service:
Single Sign On Service:
Once your settings have been put into place, click on “Manage Certificate”, paste the contents of the AA key's certificate signature request (idp-aa.csr) into the field provided, and click “Next”. This will send the CSR to InCommon at which point they will sign the key and email you back the certificate that goes into idp-aa.cert. This email should also include links for downloading the chain certificate and CA certificate described in the example.
In the etc/ directory of your Shibboleth installation, you should see the files idp.xml and resolver.xml. The former is the IdP's primary configuration file and the latter is the Attribute Authority's configuration file. Make a copy of idp.xml and resolver.xml called idp.dist.xml and resolver.dist.xml or something so you have originals to refer to if necessary.
The idp.xml file will need to be customized to your institution and InCommon account information. In the IdPConfig element, the following should be changed for InCommon use:
AAUrl is the URL to your attribute authority
providerId is the URN that InCommon gives you
For example, OhioLINK's IdP looks like this:
<IdPConfig xmlns="urn:mace:shibboleth:idp:config:1.0" xmlns:cred="urn:mace:shibboleth:credentials:1.0" xmlns:name="urn:mace:shibboleth:namemapper:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 ../schemas/shibboleth-idpconfig-1.0.xsd" AAUrl="https://authdb.ohiolink.edu/shibboleth-idp/AA" resolverConfig="file:/usr/local/shibboleth-idp/etc/resolver.xml" defaultRelyingParty="urn:mace:shibboleth:examples" providerId="urn:mace:incommon:ohiolink.edu">
If all went well with your install, you should only have to change the two attributes listed as the rest will either be the same for everyone or was automatically configured for you during the install.
Next we want to replace the example SSL certificate with the one you obtained earlier from InCommon. Search for the string “example_cred”, which should be located in an element called RelayingParty, and replace the first instance of it with a new name. (I called OhioLINK's “ohiolink_cred”) Then move to the next instance of it which should be in the Credentials element. Change the Id attribute of the FileResolver element to whatever new name you chose above and then change the two Path elements to the correct path to your SSL key and certificate files.
Finally, the uri attribute of the MetadataProvider element should be changed to use InCommon's XML file. It can be downloaded from their website and should be updated regularly via a cronjob. The URL is http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml. The file can be stored wherever you like so long as it's consistent and accessible to the user that the Tomcat process is running as.
Basic Functionality Testing
Restart Apache to load the new settings and watch the various error logs for any problems. If all went well, you should now have a basic, but functional, IdP suitable for testing. Before proceeding to the customization steps, however, be sure that this rudimentary IdP works and that all important configuration files are backed up. This way, if something goes wrong later, you aren't forced to start over from the very beginning.
At this point, it's best to test with an SP that does not require attributes to be released to it for proper functionality. If you're forced to test with SP that does mandate attributes then please skip this section and revisit it after you've completed the next two sections. (Attributes and Attribute Release Policies)
Shibboleth IdPs can offer SPs information about the user's account by way of user attributes. These pull information from the user database and IdPs can control which SPs are allowed to access which attributes. OhioLINK SPs require the attributes “urn:mace:dir:attribute-def:eduPersonPrincipalName” (a unique identifier for the institution member) and “urn:mace:dir:attribute-def:eduPersonScopedAffiliation”. (defines what type of patron the account cooreponds to) These serve multiple purposes:
Determines if the user is allowed to access OhioLINK content
Faculty, student, & staff are allowed
Alumni, 3rd party affiliates, or visitors are not
Personalized content services that remember individualized settings, i.e.:
Favorite journals in MyEJC
Commonly performed searches
Content abuse detection so that stolen or misused member accounts can be quickly determined and addressed
OhioLINK privacy policies prohibit this information from being used for actively track accessed content without good reason (such as account abuse) and the information is periodically purged once institutional statistics are generated from it. These statistics do not include individual patron information.
Institutions with multiple campuses using the same IdP may also need to supply an attribute describing the user's home campus. Different branches will often have different subscription subsets of the services that OhioLINK provides and, if we are to offer remote access to those services, we will need to ensure that students are only able to access their home campus' subset. OhioLINK suggests that the attribute localityName be used for this information (as defined in the orgPerson specifications) and a list of possible values will need to be provided so that we can set up the pattern matching.
The settings for connecting attributes to user database information is in the etc/resolver.xml file of the Shibboleth install directory. The following is an example of an LDAP-based resolver configuration:
<AttributeResolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mace:shibboleth:resolver:1.0" xsi:schemaLocation="urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd"> <!-- The LDAP server connection settings --> <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://localhost/ou=People,dc=ohiolink,dc=edu" /> <Property name="java.naming.security.principal" value="cn=admin,dc=ohiolink,dc=edu" /> <Property name="java.naming.security.credentials" value="examplepw" /> </JNDIDirectoryDataConnector> <!-- The LDAP attributes available via the AA --> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonAffiliation"> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonScopedAffiliation" smartScope="ohiolink.edu"> <AttributeDependency requires="urn:mace:dir:attribute-def:eduPersonAffiliation"/> </SimpleAttributeDefinition> <SimpleAttributeDefinition id="urn:mace:dir:attribute-def:eduPersonPrincipalName" smartScope=”ohiolink.edu”> <DataConnectorDependency requires="directory"/> </SimpleAttributeDefinition> </AttributeResolver>
This setup will bind to an LDAP server on the same machine (localhost) as cn=admin,dc=ohiolink,dc=edu and look at the objects in the DN ou=People,dc=ohiolink,dc=edu. Any “subfolders” under that DN will be ignored as per the SUBTREE_SCOPE setting. Account information for the user logging in will be found by searching for objects whose primary names are set to “uid=<login provided>”.
If no users exist with the uid provided then any attribute requests will be returned as empty datasets. Note that this does not control whether or not the user will be able to successfully log in – rather it links the information in their LDAP entry with the Shibboleth session. If the user's account is located, the attributes “urn:mace:dir:attribute-def:eduPersonPrincipalName”, “urn:mace:dir:attribute-def:eduPersonAffiliation” will be linked to their eduPersonPrincipalName and eduPersonAffiliation data respectively. In addition, an attribute called “urn:mace:dir:attribute-def:eduPersonScopedAffiliation” will be available that displays the same information as in eduPersonAffiliation but in a slightly different format.
Each institution will need to connect the attributes differently based on their user database setup. Shibboleth installs with a few configuration examples for the different ways that Shibboleth can connect to user information providers. The above example is based on the LDAP directory model; however, an SQL-based example (via JDBC) is available as well as a simple model that uses a combination of a Java keystore file and information that the user provided to the IdP at login.
Attribute Release Policies
The Attribute Release Policies (ARPs) define which attributes are available to requesting SPs. The data in some attributes may be too sensitive for just anyone allowing access to their content via your IdP; however, this information may be mandatory in other cases and therefore cannot simply be skipped in resolver.xml. The ARP configuration offers precise access control of which attributes are available to which IdPs.
The following example is from the arps/arp.site.xml in the Shibboleth etc directory on OhioLINK's staff IdP:
<?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>OhioLINK Staff ARP</Description> <Rule> <Target> <Requester matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch">https://.+\.ohiolink\.edu/shibboleth</Requester> </Target> <Attribute name="urn:mace:dir:attribute-def:eduPersonScopedAffiliation"> <AnyValue release="permit"/> </Attribute> <Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName"> <AnyValue release="permit"/> </Attribute> </Rule> </AttributeReleasePolicy>
As per the attributes available from resolver.xml example, the user's eduPersonPrincipalName and eduPersonScopedAfilliation fields are being offered here. (Also note that the eduPersonAffiliation field is not being released as it is redundant and not the preferred format.) This example restricts these attribute to only being available to SP's from the ohiolink.edu domain. In the future, OhioLINK will have an SP for each service we offer and the regular expression used should cover all of them with a single rule.
Institutional Login Page
Up until now, access to the IdP has been protected by Apache's built-in login / password functionality. Most institutions, however, will want to use a login page that resembles the one they use for their other SSO-protected resources. Obviously, everyone's signon page will look different; however, they will all need to interact with the Shibboleth IdP the same way.
If you're content to continue using Apache's auth features via the browser's login/password prompt then you can still display a webpage behind it with your institution's logo, some instructions, or whatever else you'd like. To do this, you set up a different webspace and place a webpage into it containing what you want to be shown behind the login pop-up. SSL-encryption for this page is not technically necessary; however, it's still a good idea for your users' piece of mind as it will affect the various security prompts and padlock icons that they see. This webpage becomes the new SSO site in your IdP's InCommon account and requires that you pass through a few important GET variables. The following is a simple, PHP-based example of a branded institutional landing page:
<?php // Generate a URL to redirect them to for the actual Shibboleth login. // We're simply taking the variables we're given and changing the destination $sso_url = "https://idp.ohiolink.edu/shibboleth/SSO?"; foreach ($_GET as $var => $data) $sso_url .= $var."=".urlencode($data)."&"; ?> <html> <head> <title>Shibboleth Authentication</title> <meta http-equiv="Refresh" content="0; URL=<?php echo $sso_url ?>"> </head> <body> This is the content that the user will see behind the browser's login and password prompt. Change it to look appropriate for your institution's website. </body> </html>
A fully form-based login requires a little more work. Building a form page isn't tough – you may already have one in use by other resources – but it needs to be modified to work with Tomcat's form-based authentication and must be written to correctly exchange certain bits of information with Shibboleth. More on this process can be found on the Interne2 web site and in the “Java-based User Authentication” section and the O'Reilly book “Tomcat: The Definitive Guide, 2nd Edition” at http://proquest.safaribooksonline.com/9780596101060/managing_realms_comma_roles_comma. (accessible via OhioLINK's Safari Books Online account)
Additionally, the Shibboleth Wiki offers information for using client certificate-based authentication in the section immediately following the Java form instructions. Done correctly, this is probably the most secure option of those available; however, it's complicated to set up client-side and probably not a good idea to require of students. It may, however, be useful for your tech staff if they have access to more sensitive resources than average students.
The Shibboleth Wiki is the best place to find more extensive configuration documentation. A link is included in the references section below. Questions can also be directed to the Shibboleth user mailing list. To join, send an email with “subscribe shibboleth-users First Last” to email@example.com. (First and Last should be replaced with your first and last name.) There is also a mailing list for Shibboleth-related announcements called shibboleth-announce which can be joined the same way. Instructions on how to submit questions will be provided in the list's welcome email.
Written by E. Stuart Hicks
Updated November 2013