# Authentication How-To Guide: SAML/Shibboleth Integration This guide is intended for systems administrators who will be installing and maintaining SAML/Shibboleth service provider software for an application (or set of co-located apps) at Harvard. The following basic skills are expected of the reader: - Familiarity with the local operating system, including how to install software (on some UNIX systems, this may mean compiling packages from source code or using the ITS-provided package) - Configuring the local web server (Apache, IIS, etc.) - Basic understanding of SSL, including how to generate a key and CSR - Basic understanding of XML documents Please note that this guide only provides information on SAML 2.x, because that is what our Shibboleth identity provider supports. ## Process 1. **Determine which attributes** your application needs in order to make authorization decisions about users. Please start by consulting the list of standard [attributes for SAML/Shibboleth Applications at Harvard](/attributes-available-applications-using-harvardkey-authentication-services); if you find that you need attributes that are not on this list, please contact . 2. [**Register your application**](/saml-signing-and-encryption-certificates "SAML Signing and Encryption Certificates "), including specifying which attribute your app needs. 3. **Install and configure your web server** and the Shibboleth service provider (SP) software. (This will likely take you the most amount of time and effort, but the information below will help you get started.) For more details on how to access attributes from SAML assertion in your code, see [this link in the Shibboleth wiki](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeAccess). ## Assumptions - You are using Apache version 2.2 or greater. If you are using an older version of Apache, you are strongly urged to upgrade before proceeding. - You will use Shibboleth SP version 2.4 or greater. - You are looking for basic installation and configuration instructions for a single website and application. (For more complex installations, please contact .) - If an RPM or binary for your OS is not readily available, you are able to make one from source. ## Registering Your App with Harvard Please note that this page covers only the basic technical aspects of setting up Shibboleth. Please remember that in order to test your app or have it use production IAM services, you'll also need to [register your app using this form](/resource/harvardkey-application-integration-form "HarvardKey Application Integration Form"). ## Download and Install Shibboleth Download and installation instructions are available on the Shibboleth Project wiki's [installation page](https://wiki.shibboleth.net/confluence/display/SHIB2/Installation). You'll need to follow the information in the section for Native Service Provider. Follow the instructions specific to your platform; available OS options are [Linux](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall), [Mac OSX](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMacInstall), [Solaris](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSolarisInstall), and [Windows](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPWindowsInstall). When you're done installing Shibboleth, you'll have the *shibd* daemon and the *mod\_shib* Apache module (if you use Apache) installed in your host environment. ## Configure Shibboleth for the Harvard IdP (Pre-Production) Now you need to configure your SP to work with the Harvard University identity provider (IdP). It is easiest to start with a simple configuration and migrate to more more complex configurations later. ### Update *shibboleth2.xml* The *shibboleth2.xml* file contains the basic Shibboleth SP configuration. This file is located in your main Shibboleth directory, and configures things such as what SSL certificate you are using, what resources Shibboleth should protect, and how your application identifies itself to the Shibboleth IdP. You can find this file here: - Red Hat or Ubuntu Linux: */etc/shibboleth/shibboleth2.xml* - ITS Solaris systems: */var/local/etc/shibboleth/shibboleth2.xml* - Other UNIX systems: */opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml* - Windows: *c:\\opt\\shibboleth-sp\\etc\\shibboleth* Make the following changes to the shibboleth2.xml file: - Find the *ApplicationDefaults* element and set the *entityID* (see below for more details) - Find the *Sessions* element and modify it for lifetime and timeout (in the example below, session lifetime is set to 2 hours and timeout to 1 hour) `` - Find the first SSO element and set it as shown below; this will configure SSO for the Harvard University stage, (pre-production) IdP `` `    SAML2 SAML1` `` - Download our stage IdP metadata ([*stage-idp-metadata.xml*](/files/iam/files/stage-idp-metadata.xml.zip)) and save it in the same directory as *shibboleth2.xml* - In *shibboleth2.xml,* find the line that begins *<MetadataProvider type="XML"* and update it as follows: `` ### More Details on Entity ID An entity ID is a URI that uniquely identifies your application within the [InCommon](http://www.incommon.org) ecosystem of applications and identity providers, as well as uniquely identifying it within Harvard. You can learn more about entity IDs here: - - We recommend that your entity ID have the following form: *https://<domain name>/<department name>/<application name>/sp* where *application name* is a name you choose. It should not contain spaces (or other whitespace) and should consist of letters and numbers only, i.e. a-z, A-Z, 0-9. The *department name* can be found by taking the following steps: - looking up your name at [www.directory.harvard.edu](https://www.directory.harvard.edu/) - taking the department listed - making these strings lower case - removing any white space - replacing the "^" separator with "\_", leaving off a trailing "\_" For example, if Gretchen Gingo were registering an app, she would find her department listing in [www.directory.harvard.edu](http://www.directory.harvard.edu/) to be CADM^HUIT^TPS^IAM*.* Making this string all lower case, removing white space, and replacing ^ with \_ yields *cadm\_huit\_tps\_iam*. The *domain name* is a domain name associated with your department, such as *huit.harvard.edu*. It may be the domain name where your application is hosted, **but the entity ID should not change if you switch hosts**. For example, an example entity ID using the parameters above would be *https:/huit.harvard.edu/cadm\_huit\_tps\_iam/ourCoolRegistrationApp/sp*. ### Specify Attributes Harvard's IdP sends your application attributes about the authenticated user. For your SP to process the attributes correctly, it needs to know which ones it will be receiving. To specify these, edit the [*attributes-map.xml*](/files/iam/files/attribute-map.zip) file and save it in the same location as *shibboleth2.xml*. You may also wish to filter or transform the attributes; you can do this via the *attribute\_policy.xml* file. Both of these files are in the same directory as *shibboleth2.xml*, and they include examples of how to configure attributes and attribute policies, respectively. Harvard's IdP currently releases only a limited number of attributes by default. You may uncomment additional attributes in the *attributes-map.xm*l file; however, simply doing this does not mean that your SP will receive those additional attributes. Each IdP's configuration is exclusively responsible for the release of attributes to your SP, which is why you need to specify your attribute requirements as part of the application registration process for the Harvard IdP. The *attribute-map.xml* file only tells your SP which received attributes from IdP are to be passed to your application. ### Generate Your SP's Metadata File Configuration up to this point has been to make the Shibboleth SP run on your server. Next, information must be exchanged with Harvard's IdP so that the IdP and SP can communicate. To do this, the IdP needs a copy of your SP's metadata. You can use the *metagen.sh* tool (found in the same directory as *shibboleth2.xml*) to create the metadata file for your SP. First, make sure you've chosen a good entity ID, and have the public key certificate for your SP ready. Next, execute the *metagen.sh* command (in a terminal window or shell) as follows: `./metagen.sh -c certificate_path -h domainNameOfYourSP -e entityIDForYour SP > metadata.xml` This will send the metadata to *metadata.xml*. You may then wish to edit this file to add contact information for your organization's technical and administrative support. (While these fields are optional, you'll need to add them if you want your SP to be listed in InCommon metadata.) After creating/editing the metadata, restart your Apache and shibd services. At this point, you can download your SP's metadata from the server's website simply by visiting its URL (example: **, replacing *hostname.harvard.edu* with your site's domain). You may also download your metadata from the server's website using a command such as *curl* on Linux (again, replacing *hostname.harvard.edu* with your site's domain name): `curl -o mysp.harvard.edu/metadata.xml -k https://hostname.harvard.edu/Shibboleth.sso/Metadata` When you have generated a copy of your metadata file, please email it to . Please note that if you make configuration changes to your entity ID, change your contact data in shibboleth2.xml, or change your key or certificates, you should regenerate your metadata file and send it to the IAM team again. ### Getting or Using Metadata from Non-Harvard IDPs The SP needs to have metadata from each IdP whose users you wish to serve. If the IdPs of interest to you are part of InCommon, you can simply enhance the SP's *shibboleth2.xml* configuration file to download fresh copies of the InCommon bundled metadata. [Learn more about this process here](https://spaces.internet2.edu/display/InCFederation/Shibboleth%20Metadata%20Config). You can also include metadata from IdPs that aren't part of InCommon by storing the IdP's metadata locally. This example shows metadata from a local file and from a federation: `        ` There are a number of options for getting, validating, and filtering metadata that might be of interest to you. See these pages on the Shibboleth wiki: - [Getting and validating metadata](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider) - [Filtering metadata](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataFilter) ### Certificates An X.509 (SSL) certificate is required within SAML/Shibboleth. We recommend that you use a self-generated certificate and keypair. The key/certificate pair *sp-key.pem* and *sp-cert.pem*, in the *conf* directory, are generated by the installation process and are referred to in *shibboleth2.xml*'s *CredentialResolver*. Depending on your configuration, there may be no need to change these files. However, you can also generate these files if needed using the keygen script that comes with the Shibboleth SP installation (available in the *conf* directory). Please note that the certificate you use with your SAML/Shibboleth software **should** be different than your SSL certificate. ## Initiating Authentication: Sessions and Discovery The first time a user tries to access a protected resource in your application (i.e. a resource under "/protectedarea" or whatever path you configure), the SP code needs to know where to send the authentication request. To determine this, it checks what you have set up in the *shibboleth2.xml* file. There are two primary possibilities: - Only one IdP is configured in the <SSO> section of the file. In this case, the SP sends the SAML authentication request to that IdP, and the user will be served the IdP's login screen in order to proceed. - A discovery service has been configured in the <SSO> section. In this case, the SP temporarily hands over control to that discovery service, which prompts the user to select his or her home institution ("where are you from?") from a drop-down list or similar interface element. The discovery service then returns the entity ID of the chosen institution's IdP to the SP. At this point, the SP sends the SAML authentication request to that IdP, and the user will be served the IdP's login screen in order to proceed. If the user successfully authenticates at his or her home institution, the IdP sends a SAML authentication response to the SP, containing an assertion that holds attributes about the user. Note that an additional option does not involve *shibboleth2.xml* configuration, but rather features links for users to click which contain the entity ID of the "proper" IdP in the form of a parameter. Here's an example illustrating the key elements: *[https://SPhostname.harvard.edu/Shibboleth.sso/Login?entityID=https:/The…](https://SPhostname.harvard.edu/Shibboleth.sso/Login?entityID=https:/TheRightSchool.edu/idp/shibboleth) —* - ** refers to the SP's default "initiate session" endpoint. - *entityID=* is the entity ID for the IdP of interest. Note that the SP needs to have metadata about this IdP; the SP will use the entity ID to look up information in the metadata (such as the IdP's certificate) required for authentication request and response processing. It is also possible for you to specify where the user should land after authentication by including a "target" parameter as part of the query string. #### Standalone vs. Embedded Discovery The discovery service can be either a standalone service or "embedded" within the SP. If your SP will only be interacting with a limited number of IdPs, you may wish to use the embedded discovery service, which is relatively easy to set up. Please see the [Embedded Discovery Service](https://wiki.shibboleth.net/confluence/display/EDS10/Embedded%20Discovery%20Service) page on the Shibboleth wiki. ## Try it Out Once you have Shibboleth installed, you'll need to configure it to point to the Harvard test IdP. In order to help you complete your app registration, we have set up a test IdP that returns sample data. This should be enough to verify that Shibboleth is working properly and help you to think about how your application should consume and use the data Shibboleth makes available. You'll need to change your Apache configuration to try the new SP. You can specify the paths you wish to have protected by the SP anywhere in your Apache configuration. The Shibboleth SP you installed also includes a file that loads the Shibboleth SP Apache module and protects a sample directory. In order to protect other paths, you can update that file or configure an additional file. To protect a path, use a configuration block as shown below. This particular configuration requires authentication to access any content from "/protected-area". `` `   AuthType Shibboleth` `   ShibRequireSession On` `   require valid-user` `   ShibUseEnvironment On` `   Order allow,deny` `   Allow from all` `` For more details on how to access attributes from SAML assertion, see [this link in the Shibboleth wiki](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAttributeAccess). ## Advanced Topics #### Multiple Applications A single Shibboleth SP installation is designed to support multiple applications installed on that server, but there are different deployment and configuration strategies to support this. More information is available at [Shib 1.3 Add Separate Application](https://wiki.shibboleth.net/confluence/display/SHIB/AddSeparateApplication). (Note that these instructions are for Shibboleth 1.3, but the example maps fairly closely to the configuration changes required in 2.x — there is no particular wiki page updated for this particular issue on the Shibboleth 2.x wiki, but you can find all the relevant information in the various API pages. ## Downloads - Production IdP Metadata - Stage IdP Metadata - Attribute Map XML *Thanks to the* [*University of Southern California*](https://shibboleth.usc.edu/docs/sp/install/) *for selected source material for this guide.*