How to "Shibbolize" Your Application

Contents

Overview

For an overview of Shibboleth at UC Berkeley, see: Shibboleth Overview and Terminology.

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.

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. 

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")

    <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")

    <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"
    </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">
<!-- Example of remotely supplied batch of signed metadata from InCommon. -->
<MetadataProvider type="XML"
backingFilePath="incommon-metadata.xml" reloadInterval="7200"> or [calnet:shib-test-metadata.xml]
</MetadataProvider>
<!-- Example of locally maintained metadata. -->
<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, 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.