Shibboleth Technical Documentation
Local/HomeGrown Installation and Configuration
Vendor Integration
1) Gather information from your vendor
Ask your vendor if they are a member of InCommon (you can also look this up through the InCommon website).
Ask for your vendor's EntityId, SP metadata file (metadata is not required if they are a member of InCommon) and login URLs for any production and non-production sites they plan to Shibbolize. These will be required in step 3.
2) Share our campus information with your vendor
Provide your vendor with our campus's IDP metadata and Login Post URL. Some SPs may also request the Logout URL.
IDP Metadata: http://login.ucsc.edu/metadata/idp-metadata.xml
Login Post URL: https://login.ucsc.edu/idp/profile/SAML2/Redirect/SSO
3) Submit the integration request form
Complete a Shibboleth Integration Request Form in SlugHub. You will be copied on most communication related to this service request so you can track the progress of the integration work, including verification of the needed information, campus approvals to release student and employee data to the vendor, development work and testing.
4) Test
Once the integration work is completed by the UCSC Identity Management team and your vendor, you'll be asked to test the integration. This entails visiting the URLs your vendor provided, verifying that they reedirect to our Shibboleth login page and back into the vendor's application site once you've authenticated. Confirm that the consent form is not visible if you asked to have it hidden in step 3. You may also want to test what happens for a user who does not have permission to use the application to ensure error messaging provided by the vendor is clear.
Local/HomeGrown Installation and Configuration
This information below describes the basic steps needed to install and configure an Internet2 provided Shibboleth Service Provider for authentication on Apache and IIS servers. Other SP software doesn't follow these configuration steps but should be fairly similar.
In this document <SHIB_HOME> refers to the directory where Shibboleth is installed. In IIS this defaults to c:\opt\shibboleth. In Apache this is /etc/shibboleth.
1) Download and Install
Download page for Shibboleth Service Providers:
https://wiki.shibboleth.net/confluence/display/SP3/Installation
Shibboleth SP for Apache (Linux)
Shibboleth must be installed. If your server is managed by the ITS Core Tech team, you need to create a ITR ticket at https://itrequest.ucsc.edu and request the installation. For servers not managed by our Core Tech team, instructions are available on the Shibboleth documentation page https://wiki.shibboleth.net/confluence/display/SP3/LinuxInstall.
Shibboleth SP for IIS (Windows)
Get the latest msi at https://wiki.shibboleth.net/confluence/display/SP3/Install+on+Windows and run the installer.
2) Configure Shibboleth Conf Files
The Shibboleth conf files are located in /etc/shibboleth (for Unix).
sp-key.pem and sp-cert.pem
Generate the keys by running the keygen utility found in <SHIB_HOME> (in Windows: keygen.bat, and in Apache: keygen.sh). For example, on our web servers as configured by CoreTech:
cd /etc/shibboleth ./keygen.sh -u shibd -g app_admin -f -e https://<your hostname>/shibbolethAllow the keygen utility to overwrite the default existing keys. In a load balanced scenario, the hostname is the CNAME used by the load balancer to reach your proxy servers (e.g., wcms.ucsc.edu, wcms-stage.ucsc.edu); the key/cert files are created on a single server, then copied over to all the other load balanced servers.
Shibboleth2.xml
Make or verify the following changes:
Configure the entityID of your server in the shibboleth2.xml file. In a load balanced scenario, the hostname is the CNAME used by the load balancer to reach your proxy servers (e.g., wcms.ucsc.edu, wcms-stage.ucsc.edu).
<ApplicationDefaults entityID="https://<your_service_name>.ucsc.edu/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
Edit the entityID attribute in the SSO tag inside the shibboleth2.xml file to use UCSC IdP server. Set the entityID to "https://login.ucsc.edu/idp/shibboleth":
<SSO entityID="https://login.ucsc.edu/idp/shibboleth" discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF"> SAML2 SAML1 </SSO>
Your Shibboleth installation needs to load the trust data from the login servers. Look for the section that has the text "Example of remotely supplied batch of signed metadata" and add the following underneath it:
<MetadataProvider type="XML" uri="http://login.ucsc.edu/metadata/idp-metadata.xml" backingFilePath="login-metadata.xml" reloadInterval="7200"> </MetadataProvider>
Verify that shibboleth2.xml references the correct key/certificate:
<!-- Simple file-based resolver for using a single keypair. --> <CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>
The combination of virtual host and path for Shibboleth to protect. In a load balanced scenario, the hostname is the CNAME used by the load balancer to reach your proxy servers (e.g. wcms.ucsc.edu, wcms-stage.ucsc.edu).
<Host name="<your hostname>"> <Path name="secure" authType="shibboleth" requireSession="true"/> </Host>
On IIS only, it is also necessary to configure the site ID. This is a combination of the ID that IIS automatically assigns to your website and the hostname.
<Site id="1" name="cascade-dev.ucsc.edu"/>
Shibboleth, and SAML2 in general, can have different security profiles. Here is an example of a default UCSC security profile:
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem" checkAddress="false" handlerSSL="true" cookieProps="https">
3) Configure Apache Conf File Directives
In Apache you may also specify protected content in a Location tag (usually within a <VirtualHost> container):
<Location <your protected dir>> AuthType shibboleth ShibRequireSession On require valid-user </Location>
Using Shibboleth with proxies presents no major challenges. It is important to remember that the URL /Shibboleth.sso is a special URL that must be processed by the Shibboleth daemon. If you are running a proxy from the root directory of a host then you should prevent the proxy from forwarding traffic meant for shibd by using directives such as these:
ProxyPass /Shibboleth.sso ! ProxyPass /shibboleth-sp !
The second one provides the images that are part of Shibboleth's error handling pages.
If forwarding the Shibboleth attributes to a back-end server or application then you must add "ShibUseHeaders On" to your Location element in order to let the module know to place the values into headers instead of environment variables.
4) Restart Shibboleth Daemon
After configuration it is necessary to start the Shibboleth daemon (shibd). It may sometimes be necessary to restart your web server after restarting shibd.
On Red Hat:
sudo /sbin/service shibd stop/start/restart
On IIS:
net start /stop shibd_Default
5) Generate Metadata file
Navigate to https://<your_hostname>/Shibboleth.sso/Metadata. Your browser should attempt to display or download the metadata xml. This is the metadata file that you will upload to your Shibboleth integration request in Step 6.
Note that your metadata file will contain a public key that expires. When the public key expires, the metadata expires and the Shibboleth integration will cease to function. Service Providers are responsible for tracking their metadata expiration, creating new public keys and metadata files and providing them to the Identity Management team on a schedule that ensures no lapse in the authentication service.
6) Request Metadata Import to IdP
At this point you are ready to request the IdP configuration be done by the IdM team. Fill out the Shibboleth Integration Request Form in SlugHub and attach your metadata to the request. The IdM team will use it to provide the other end of the connection.
7) Test
Your request ticket will be updated to let you know when it is ready for testing. To test, open a new private browsing window and navigate to protected content. You should be redirected to the IdP login server. Use your CruzID and Gold password. Once authenticated you should be redirected to the protected content. You may also navigate to /Shibboleth.sso/Session to view your session information, and logout with /Shibboleth.sso/Logout to force a new authentication.
Other Considerations
Shibboleth and Load Balancers
The main gotcha when using load balanced servers with Shibboleth is that only one shibd on one web server knows that you have logged in, and the multiplicity of time outs. Currently:
Load Balancer Stickiness (cannot be set per application):
- time out port 443: 5 min (although for www2, it has been set to 20 min)
- time out port 80: none
- lifetime not used
Shibd Stickiness (can be set per application):
- time out: 1 hour
- lifetime: 8 hours
The stickiness is reset as long as there is activity (i.e., traffic) between your workstation and the web server. This is true for the load balancer timeout on port 443, and the shibd time out (up to its maximum allowed lifetime).
Any application needs to keep some traffic to keep their connection active. If javascript is enabled, I don't see why it could not generate some traffic automatically by fetching some tiny image (1 pixel) to reset the time out counter. But, yes, this complicates writing apps.
To avoid the load balancer stickiness issues, we would need to have shibd running on a single web server, and have all traffic go to it. But this reduces redundancy, and we would no longer be able to do maintenance by taking off-line the server hosting shibd without much juggling. Another solution would be a shibd cluster/service that all web servers could use, much like we have a database back-end and common storage (e.g., AFS).
Forcing Authentication
Single sign-on (SSO) allows users who have signed into one Shibboleth application to access many other Shibboleth applications without having to sign in again for 12 hours. SSO can reduce the number of times users need to log in during the day.
With the implementation of multi-factor authentication most applications are allowing SSO, but a few applications “force authentication” - require the user to enter CruzID and password every time they enter the application - due to higher risk data and confidential information such as payroll. SAML2 provides a mechanism that allows a service provider (SP) to request that the IdP (identity provider/login server) re-challenge the user to provide a login CruzID and password.
Forcing authentication is called forceAuthn in the SAML world. It is a request that is honored by the login server if your service provider (Shibboleth SP) is configured to do so. There are two tags in shibboleth2.xml that need settings added as shown below. The first, maxTimeSinceAuthn, checks that an actual username and password was entered in the last x seconds (the example here sets it to 5 seconds), and the second, forceAuthn, is set to true so the login server knows to ignore the request to perform SSO logins:
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem" maxTimeSinceAuthn="5" checkAddress="false" handlerSSL="true" cookieProps="https"> <SSO entityID="https://login.ucsc.edu/idp/shibboleth" forceAuthn="true" discoveryProtocol="SAMLDS" discoveryURL="https://ds.example.org/DS/WAYF"> SAML2 SAML1 </SSO>
