How do I use Shibboleth/ SAML for SSO?

A knowledge base article about How do I use Shibboleth/ SAML for SSO? provided by the UC Berkeley IT Service Hub - Knowledge Portal

About Shibboleth and SAML

Shibboleth is a web-based Single Sign-On infrastructure. It is based on SAML, a standard for the exchange of authentication data. Shibboleth has been adopted by the University of California as the basis for federated Single Sign-On between the UC campuses. Shibboleth allows one to authenticate using a local institutional service (IdP) to gain access to remote resources and services.

Understanding Shibboleth and SAML is much easier if you know some terminology. A successful deployment of Shibboleth involves two critical software components:

Identity Provider (IdP)

This is the server that handles authentication of users. UC Berkeley has deployed an IdP at shib.berkeley.edu. Only one IdP is needed per campus.

Service Provider (SP)

An IdP is useless without Service Providers. Service Providers are web applications, resources, or other services which require authentication. The Shibboleth SP software allows most web servers (namely Apache and IIS) to integrate with an IdP or a number of IdPs. Examples of SPs are: UCReady, the UCB Learning Center (a SumTotalSystems application hosted at UCOP by SumTotalSystems), and At Your Service (AYSO, hosted at UCOP).

The SP software consists of several components:

ISAPI Filter - This is only used for IIS deployments. It intercepts requests to IIS and redirects users to an IdP or WAYF. After the user authenticates, it also handles the callback which tells your SP that the user has authenticated. During handling of this callback the ISAPI Filter collects attributes which describe the authenticated user. The filter is configured through shibboleth.xml.

Apache Module - This is only used for Apache deployments. It is essentially the same as the ISAPI Filter but for the Apache web server. In addition to shibboleth.xml, some configuration is required via httpd.conf.

Shibd - This is a service (Windows) or daemon (UNIX) which handles attributes request queries from the SP to the IdP. Shibboleth attribute requests are part of the SAML standard and are made via a back channel SOAP call to the IdP (usually on port 8443). In order to receive user attributes, this service must be running.
Attribute Acceptance Policy - This policy dictates which attributes the SP wants and which IdPs are authorized to provide them. It may also define specific formats that the values must match. In addition, the AAP determines what HTTP headers will be used for mapping attributes that are supplied by the IdPs. There are two files that combine together for this functionality, the attribute-map.xml and attribute-policy.xml.

How to set up SSO with Shib

To setup SSO/SAML with your service, or change an existing service, you will need to submit a Service Request form via ServiceNow.

Be sure to have all of the following information before submitting your request:

Info About Your Service

Provide a link to any documentation provided by the vendor.
Determine what attributes they need from our IDP.
UID (urn:oid:0.9.2342.19200300.100.1.1) ?
SN (urn:oid:2.5.4.4), Givenname (urn:oid:2.5.4.42) ?
DisplayName (urn:oid:2.16.840.1.113730.3.1.241) ?
CalNetID (urn:oid:1.3.6.1.4.1.4995.2.200.10.1.5.4) friendly name is different (berkeleyEduKerberosPrincipalString) ?
Affiliations (urn:oid:1.3.6.1.4.1.5923.1.1.1.1) friendly name eduPersonAffiliation. Note: also available in scoped format. ?
Email Address (urn:oid:0.9.2342.19200300.100.1.3) ?
Will they need a NameID as part of the assertion?
Determine what identifier the accounts on your server will use. The uid is immutable (doesn't change). Our EPPN (Edu Person Principal Name) is the person's scoped CalNetID, ex. joe_user@berkeley.edu(link sends e-mail). All of these possible account identifiers can be formatted as a NameID.
UID?
CalNetID?
Email Address?
EPPN?
Procure the metadata from the server (SP).
Determine if you want to do the setup in our test IDP initially or go straight to prod?
Determine your audience for the service (staff, faculty, students, all campus community).
If you'll need to use the email address of the users of your service, we will need to request authorization from the appropriate source system (HR, SIS).

INFO From IDP

You'll need some information about our IDP to complete setup.

Our IDP metadata
Production IDP Metadata
Test IDP Metadata

Some services can use the metadata directly, but many will need several elements separated.

IDP EntityID
Production - urn:mace:incommon:berkeley.edu
Test - https://shib-test.berkeley.edu/idp/shibboleth
Login URL (choose between)
Production: Binding = HTTP-Redirect, URL = https://shib.berkeley.edu/idp/profile/SAML2/Redirect/SSO
Production: Binding = HTTP-POST, URL = https://shib.berkeley.edu/idp/profile/SAML2/POST/SSO

Test: Binding = HTTP-Redirect, URL = https://shib-test.berkeley.edu/idp/profile/SAML2/Redirect/SSO
Test: Binding = HTTP-POST, URL = https://shib-test.berkeley.edu/idp/profile/SAML2/POST/SSO
Logout URL (can add ?service=The_URL_of_my_service) must be registered with auth.b.e
Production: URL = https://shib.berkeley.edu/idp/logout
Test: URL = https://shib-test.berkeley.edu/idp/logout

Installation (Apache or IIS)

These instructions have been simplified and are UC Berkeley specific. If you need more complete instructions visit the Shibboleth Wiki - Installation page(link is external).

Configuration can be a difficult process; this is because it is both a new subject and one that is modifying XML. The main file that you will be editing is the shibboleth2.xml file. You will find this file in the configuration directory of your install and there are several sections that you will need to edit.

Request Mapper

Under the section RequestMapper in the RequestMap tag you'll need to edit the host name. The path name "secure" is the directory that shibboleth will protect on your web server. We will use

<Host name="yourserver.berkeley.edu">

<Path name="secure"

authType="shibboleth"

requireSession="true"/>

</Host>

Application Defaults

You'll need to change the EntityID for your host. The convention is listed below. While the example listed is a URL, the entityID is used as an identifier in the metadata for your SP. The URLs used to contact your SP will be part of the metadata.

<ApplicationDefaults id="default" policyId="default"

entityID="https://yourserver.berkeley.edu/shibboleth-sp"

REMOTE_USER="eppn persistent-id targeted-id"

signing="false" encryption="false">

SSO (for versions >= 2.4)

The SSO section replaces much of the manual setup. If you need to add a discovery service, you add that later.

Replace the SSO section with:

<SSO entityID="https://shib-test.berkeley.edu/idp/shibboleth"(link is external)>

SAML2

</SSO>
Using a SAML Discovery Service:

<SSO discoveryProtocol="SAMLDS" discoveryURL="https://shib-test.berkeley.edu/ds/ucready.wayf"(link is external)>

SAML2

</SSO>

Session Initiator (for version < 2.4)

The session initiator is used to determine which IdP to send your SP for authentication and authorization information. It can either be a specific server or discovery service which allows the user to pick from a list of IdPs. Here are two examples:

specific server (The entityId is for our production IdP. The entityId for a test IdP is entityID="https://shib-test.berkeley.edu/idp/shibboleth(link is external)")

<SessionInitiator type="Chaining" Location="/Login" isDefault="true" id="Intranet"

relayState="cookie" entityID="urn:mace:incommon:berkeley.edu">

<SessionInitiator type="SAML2"

acsIndex="1" template="bindingTemplate.html"/>

<SessionInitiator type="Shib1" acsIndex="5"/>

</SessionInitiator>

discovery service (the URL for the test IdP is URL="https://shib-test.berkeley.edu/ds/ucready.wayf(link is external)")

<SessionInitiator type="Chaining"

Location="/DS"

id="DS"

relayState="cookie"

isDefault="true">

<SessionInitiator type="SAML2"

defaultACSIndex="1"

template="bindingTemplate.html" />

<SessionInitiator type="Shib1"

defaultACSIndex="5" />

<SessionInitiator type="SAMLDS"

defaultACSIndex="1"

URL="https://shib.berkeley.edu/ds/ucready.wayf"(link is external) />

</SessionInitiator>

Metadata Provider

Here you need to specify where you are getting the metadata that will identify either the specific IdP or the list of IdPs. The metadata for shib-test.berkeley.edu is attached to this page, see below.

<MetadataProvider type="Chaining">

<MetadataProvider type="XML"

uri="https://md.incommon.org/InCommon/InCommon-metadata-idp-only.xml(link is external)"(link is external)

backingFilePath="incommon-metadata.xml" reloadInterval="7200"> or [calnet:shib-test-metadata.xml]

</MetadataProvider>

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

</MetadataProvider>

Example of a UC Berkeley IdP SAML2 assertion:

<?xml version="1.0" encoding="UTF-8"?>
<saml2:AttributeStatement xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml2:Attribute FriendlyName="uid" Name="urn:oid:0.9.2342.19200300.100.1.1"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">123456</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="berkeleyEduPrimaryDeptUnit"
            Name="urn:oid:1.3.6.1.4.1.4995.2.200.10.1.1.19"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">ABCDEF</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="givenName" Name="urn:oid:2.5.4.42"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">Firstname</saml2:AttributeValue>
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">Firstname2</saml2:AttributeValue>
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">Firstname Secondname</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="departmentNumber"
            Name="urn:oid:2.16.840.1.113730.3.1.2"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">ABCDEF</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="berkeleyEduAffiliations"
            Name="urn:oid:1.3.6.1.4.1.4995.2.200.10.1.1.7"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">AFFILIATE-TYPE-ADVCON-ALUMNUS</saml2:AttributeValue>
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">EMPLOYEE-TYPE-STAFF</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="berkeleyEduKerberosPrincipalString"
            Name="urn:oid:1.3.6.1.4.1.4995.2.200.10.1.5.4"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">calnetid</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">calnetid@berkeley.edu</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="sn" Name="urn:oid:2.5.4.4"
            NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">Lastname</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>

Shibboleth Logout

If an SP kills its own browser sessions, then call https://shib.berkeley.edu/idp/logout(link is external), the Shibboleth and CAS sessions in the browser are both closed as well. The Shibboleth logout URL removes Shibboleth cookies in the browser then redirects to the CAS logout URL which does the same for any CAS cookies. Other browser sessions with other SPs are potentially unaffected by this action which therefore does not guarantee a global SSO logout but rather effects (1) Shibboleth and CAS SSO session terminations for the browser and (2) termination of the one application's browser session for the SP invoking the call.