How To Add Service Provider To Shibboleth Idp

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 lawmaking or using the ITS-provided parcel)
Configuring the local spider web server (Apache, IIS, etc.)
Bones understanding of SSL, including how to generate a cardinal and CSR
Bones understanding of XML documents

Please annotation that this guide only provides information on SAML 2.x, because that is what our Shibboleth identity provider supports.

The Process

Determine which attributes your awarding needs in order to make say-so decisions most users. Please start by consulting the list of standard attributes for SAML/Shibboleth Applications at Harvard; if you find that yous need attributes that are non on this list, please contact ithelp@harvard.edu.
Register your application, including specifying which attribute your app needs, using this form.
Install and configure your web server and the Shibboleth service provider (SP) software. (This volition likely take you the most amount of time and effort, but the data below volition help y'all get started.)
For more details on how to access attributes from SAML exclamation in your code, see this link in the Shibboleth wiki.

Assumptions

You are using Apache version two.ii or greater. If you are using an older version of Apache, you are strongly urged to upgrade before proceeding.
Yous will use Shibboleth SP version 2.4 or greater.
You lot are looking for basic installation and configuration instructions for a unmarried website and application. (For more complex installations, please contact ithelp@harvard.edu.)
If an RPM or binary for your Os is non readily bachelor, you are able to make one from source.

Registering Your App with Harvard

Please notation that this page covers simply the basic technical aspects of setting up Shibboleth. Delight call up that in society to exam your app or accept it utilise production IAM services, you'll also need to register your app using this form.

Download and Install Shibboleth

Download and installation instructions are available on the Shibboleth Project wiki's installation page. 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, Mac OSX, Solaris, and Windows. When you're done installing Shibboleth, yous'll take the shibd daemon and the mod_shib Apache module (if you use Apache) installed in your host surroundings.

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 circuitous configurations later.

Update shibboleth2.xml

The shibboleth2.xml file contains the basic Shibboleth SP configuration. This file is located in your master Shibboleth directory, and configures things such as what SSL certificate y'all are using, what resources Shibboleth should protect, and how your application identifies itself to the Shibboleth IdP. You can detect 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 post-obit changes to the shibboleth2.xml file:

Notice the ApplicationDefaults element and prepare 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 two hours and timeout to 1 hour)

<Sessions lifetime= "7200" timeout= "3600" relayState= "ss:mem" checkAddress= "false" handlerSSL= "true" cookieProps= "; path=/; secure; HttpOnly" >
Find the commencement SSO element and set information technology as shown below; this will configure SSO for the Harvard Academy phase, (pre-product) IdP

< SSO entityID = "https://stage.fed.huit.harvard.edu/idp/shibboleth" >

SAML2 SAML1

</ SSO >
Download our stage IdP metadata (phase-idp-metadata.xml) and save it in the aforementioned directory equally shibboleth2.xml
In shibboleth2.xml, find the line that begins <MetadataProvider blazon="XML" and update it as follows:

<MetadataProvider type= "XML" file= "stage-idp-metadata.xml" />

More Details on Entity ID

An entity ID is a URI that uniquely identifies your awarding within the InCommon ecosystem of applications and identity providers, too as uniquely identifying it inside Harvard. You lot can learn more most entity IDs here:

wiki.shibboleth.internet/confluence/display/SHIB2/EntityNaming
https://spaces.internet2.edu/display/InCFederation/Entity+IDs

We recommend that your entity ID take the following form:

https://<domain name>/<department name>/<application name>/sp

where application name is a name you choose. It should non contain spaces (or other whitespace) and should consist of letters and numbers only, i.eastward. a-z, A-Z, 0-9. The section proper noun tin exist found by taking the post-obit steps:

looking upwardly your name at www.directory.harvard.edu
taking the section listed
making these strings lower case
removing any white space
replacing the "^" separator with "_", leaving off a abaft "_"

For example, if Jane Hill were registering an app, she would find her department listing in www.directory.harvard.edu to be CADM^HUIT^Identity Access Mgmt. Making this string all lower case, removing white space, and replacing ^ with _ yields cadm_huit_identityaccessmgmt.

The domain name is a domain name associated with your department, such as huit.harvard.edu. Information technology may be the domain proper name where your application is hosted, but the entity ID should non change if you switch hosts. For instance, an instance entity ID using the parameters in a higher place would exist https:/huit.harvard.edu/cadm_huit_identityaccessmgmt/ourCoolRegistrationApp/sp.

Specify Attributes

Harvard's IdP sends your application attributes most the authenticated user. For your SP to process the attributes correctly, it needs to know which ones it volition be receiving. To specify these, edit theattributes-map.xml file and save it in the same location as shibboleth2.xml. You lot may besides wish to filter or transform the attributes; you tin can exercise 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 aspect policies, respectively.

Harvard'south IdP currently releases simply a limited number of attributes by default. You lot may uncomment boosted attributes in the attributes-map.xmfifty file; however, merely doing this does not mean that your SP will receive those additional attributes. Each IdP'southward configuration is exclusively responsible for the release of attributes to your SP, which is why you demand to specify your attribute requirements equally part of the application registration process for the Harvard IdP. The attribute-map.xml file but tells your SP which received attributes from IdP are to exist passed to your application.

Generate Your SP'southward Metadata File

Configuration upwards to this point has been to make the Shibboleth SP run on your server. Next, data must be exchanged with Harvard's IdP so that the IdP and SP can communicate. To exercise this, the IdP needs a copy of your SP'southward metadata. Yous can utilize the metagen.sh tool (found in the same directory equally shibboleth2.xml) to create the metadata file for your SP.

First, make certain you lot've called a practiced entity ID, and take the public key certificate for your SP set up. Adjacent, execute the metagen.sh command (in a terminal window or shell) equally follows:

./metagen.sh -c certificate_path -h domainNameOfYourSP -e entityIDForYour SP > metadata.xml

This will ship the metadata to metadata.xml. You may then wish to edit this file to add together contact information for your system'south technical and administrative support. (While these fields are optional, you'll need to add them if you want your SP to exist listed in InCommon metadata.)

Afterwards creating/editing the metadata, restart your Apache and shibd services. At this point, you lot tin download your SP's metadata from the server'due south website simply by visiting its URL (case: https://hostname.harvard.edu/Shibboleth.sso/Metadata , replacing hostname.harvard.edu with your site'due south domain). You may too download your metadata from the server's website using a command such equally curl on Linux (again, replacing hostname.harvard.edu with your site's domain name):

ringlet -o mysp.harvard.edu/metadata.xml -k https://hostname.harvard.edu/Shibboleth.sso/Metadata

When you have generated a re-create of your metadata file, please email it to ithelp@harvard.edu. Delight note that if y'all make configuration changes to your entity ID, modify your contact data in shibboleth2.xml, or alter your primal or certificates, you lot should regenerate your metadata file and transport it to the IAM team again.

Getting or Using Metadata from Non-Harvard IDPs

The SP needs to accept metadata from each IdP whose users you wish to serve. If the IdPs of interest to you are part of InCommon, yous can simply raise the SP's shibboleth2.xml configuration file to download fresh copies of the InCommon bundled metadata. Learn more than about this process hither.

Y'all can also include metadata from IdPs that aren't office of InCommon by storing the IdP's metadata locally. This example shows metadata from a local file and from a federation:

At that place are a number of options for getting, validating, and filtering metadata that might be of interest to you lot. See these pages on the Shibboleth wiki:

Certificates

An X.509 (SSL) document is required inside SAML/Shibboleth. We recommend that you apply a self-generated document and keypair. The fundamental/document 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, at that place may exist 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 utilize with your SAML/Shibboleth software should be different than your SSL document.

Initiating Authentication: Sessions and Discovery

The first fourth dimension a user tries to access a protected resource in your awarding (i.e. a resource under "/protectedarea" or whatever path you configure), the SP code needs to know where to send the hallmark request. To decide this, information technology checks what you have set up in the shibboleth2.xml file. At that place are two main possibilities:

Only one IdP is configured in the <SSO> section of the file. In this case, the SP sends the SAML authentication asking 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 instance, the SP temporarily hands over control to that discovery service, which prompts the user to select his or her dwelling house institution ("where are you from?") from a drib-downwardly list or similar interface chemical element. The discovery service and so returns the entity ID of the called institution's IdP to the SP. At this point, the SP sends the SAML authentication request to that IdP, and the user will exist served the IdP's login screen in order to proceed. If the user successfully authenticates at his or her dwelling house institution, the IdP sends a SAML authentication response to the SP, containing an exclamation that holds attributes well-nigh the user.

Note that an additional option does not involve shibboleth2.xml configuration, simply rather features links for users to click which contain the entity ID of the "proper" IdP in the class of a parameter. Hither'due south an example illustrating the key elements: https://SPhostname.harvard.edu/Shibboleth.sso/Login?entityID=https:/TheRightSchool.edu/idp/shibboleth —

It is also possible for you to specify where the user should land subsequently hallmark by including a "target" parameter equally role 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 volition simply be interacting with a limited number of IdPs, you may wish to employ the embedded discovery service, which is relatively like shooting fish in a barrel to set up. Please come across the Embedded Discovery Service page on the Shibboleth wiki.

Try information technology Out

Once y'all have Shibboleth installed, you'll need to configure it to point to the Harvard examination IdP. In order to help yous complete your app registration, we take prepare up a exam IdP that returns sample data. This should be enough to verify that Shibboleth is working properly and help you lot to think about how your application should swallow and use the information Shibboleth makes bachelor.

You'll need to modify your Apache configuration to endeavor the new SP. Y'all tin specify the paths you wish to have protected by the SP anywhere in your Apache configuration. The Shibboleth SP yous installed also includes a file that loads the Shibboleth SP Apache module and protects a sample directory. In society 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 hallmark to access whatever content from "/protected-area".

<Location / protected -area>

AuthType Shibboleth

ShibRequireSession On

crave valid-user

ShibUseEnvironment On

Order permit,deny

Allow from all

</Location>

For more details on how to access attributes from SAML assertion, come across this link in the Shibboleth wiki.

Advanced Topics

Multiple Applications

A unmarried Shibboleth SP installation is designed to support multiple applications installed on that server, but there are unlike deployment and configuration strategies to support this. More information is available at Shib 1.three Add Separate Application. (Note that these instructions are for Shibboleth 1.3, only the case maps fairly closely to the configuration changes required in 2.x — there is no particular wiki folio updated for this particular effect on the Shibboleth two.x wiki, only you tin can find all the relevant data in the diverse API pages.

Downloads

Production IdP Metadata
Phase IdP Metadata
Attribute Map XML

Thanks to the University of Southern California for selected source material for this guide.