Shibboleth Service Provider (SP) - SAML2

Installation Resources

Installation Packages

Required Packages:

• libcurl-openssl

• liblog4shib1

• opensaml-schemas

• shibboleth

• xml-security-c-bin

• xmltooling-schemas

Dependencies that should install automatically:

• libsaml8

• libxerces-c-3_1

• libxml-security-c17

• libxmltooling6

• unixODBC

Servers

Version Compatibility

PCR-360 uses the Shibboleth SP version 3, which is the latest version and should be fully supported by Shibboleth IdP 4. In fact, either SP version (2 or 3) should work with any IdP supporting SAML2 regardless of the IdP version. Customers should feel free to use Shibboleth ldP 4 at their discretion.

Entity Server

In order to authenticate, PCR-360 must connect to an entity server

• this is mapped in the shibboleth configuration file located at /etc/shibboleth/shibboleth2.xml

• and generally follows a pattern such at https://url-of-the-entity-server/shibboleth-sp

Metadata Provider

PCR-360 needs to connect to a metadata provider in order to receive and format attributes

• this is mapped in the shibboleth configuration file located at /etc/shibboleth/shibboleth2.xml

• and generally follows a pattern such at https://url-of-the-metadata-provider/metadata.xml

Attribute Mapping

PCR-360 can map any attributes (up to 7) that Shibboleth sends as long as it knows:

• The attribute name (oid:1.3.6.1.4.1.5923.1.1.1.6 )

• the attribute id (eduPersonPrincipalName).

TLDR:

1. At minimum, we need the attribute name and and attribute id.

2. Shibboleth genrally send these attributes by default:

   1. a unique id (eppn, uid, or similar)

   2. first name

   3. last name

   4. email address

3. Any attributes not released by default, but needed by the customer for for mapping, such as phone number, will need to be released specifically to PCR-360 application by the Shibboleth server.

4. The attributes will update if changed on the Shibboleth server.

Common Attributes

The most common attributes PCR-360 recieves are:

• eduPersonPrincipalName, eppn, or uid

• displayName

• givenName

• surname or sn

• phone

• mail or email

• memberOf or isMemberOf

  Most Comon Mappings /etc/shibboleth/attribute-map.xml

  CODE

      <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
      <Attribute name="urn:oid:2.5.4.4" id="surname"/>
      <Attribute name="urn:oid:2.5.4.42" id="givenName"/>
      <Attribute name="urn:oid:0.9.2342.19200300.100.1.3" id="mail"/>
      <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/>

  
  

Here is how the attributes are mapped to values used by PCR-360

1. Accessing and Modifying Configuration INI Files

2. More information about the AUTH_ROLEMAPPING Attribut

auth.AUTH_ATTRMAP_USERID       = eduPersonPrincipalName (uid or unfederated-id)
auth.AUTH_ATTRMAP_DISPLAYNAME  = displayName
auth.AUTH_ATTRMAP_FIRSTNAME    = givenName (ucscpersonofficialgivenname)
auth.AUTH_ATTRMAP_LASTNAME     = surname (ucscpersonofficialsn)
auth.AUTH_ATTRMAP_EMAIL        = mail
auth.AUTH_ATTRMAP_PHONE        = phone
auth.AUTH_ATTRMAP_GROUPS       = isMemberOf

Required Attributes

While PCR-360 can map up to to 7 attributes, the only required attributes are:

1. unique id (eppn or similar)

2. first name

3. last name

4. email address

The other attributes are optional and will give the PCR-360 more information when creating Users.

Role Mapping

You may view more information on PCR-360 Users and Permissions here: Admin:User_Management

Roles are mapped into the PCR-360 in one of three ways: More info about Roles

Default Settings

All SSO groups are ignored and all New User are added as a guest

auth.AUTH_ROLEMAPPING = false
auth.roles.default    = "Guest"

Contact Type Mapping

1. Contact types are manually mapped to roles in the application config INI

2. Contact Mapping follows the form of auth.roles.{CONTACT_TYPE_LISTS.CODE} = {ROLE_NAME}

   1. More info about Workers/Contacts#ContactTypesContactTypes

   2. More info about Roles

   3. PHP

      auth.AUTH_ROLEMAPPING  = false
      auth.roles.default     = "Guest"
      auth.roles.SYSADMIN    = "Administrator"
      auth.roles.COORDINATOR = "Coordinator"
      

SSO Mapping

Shibboleth, Active Directory, etc

1. SSO Role Mapping allows mapping an SSO group to a PCR-360 Role.

2. To use SSO mapping these values should be set in the PCR360 INI

   CODE

   // enables role mapping from the SSO
   auth.AUTH_ROLEMAPPING   = true
   
   // this is default role added to all users, a minimum access level
   auth.roles.default      = "Guest"
   
   ; this assumes the group attribute from the SSO is isMemberOf
   auth.AUTH_ATTRMAP_GROUPS = "isMemberOf"
   
   ; This is the default value, if your Fully Qualified Group Name contains commas, this will need to be changed to a semicolon ";"
   auth.AUTH_ATTR_SEPARATOR = ","

3. Shibboleth also needs to be configured to parse the group attribute from the SSO:

   /etc/shibboleth2/attribute-map.xml
   

   CODE

   // this assumes the SSO is passing the group as the LDAP group attribute
   // the name needs to be the actuall attribute name from the SSO.
   <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="isMemberOf"/>

4. The value of the SSO attribute is then mapped on the Role:

   1. Enabling the AUTH_ROLEMAPPING setting enables the Authentication Mapping field on the Roles form.

   2. The Fully Qualified Group Name is entered here to map the Role to the SSO Group
      

      

5. Once implemented, the Application will

   1. Map the Fully Qualified Group Name to the Role via the attribute configured by AUTH_ATTRMAP_GROUPS

   2. Add/Update the Role to users in the Fully Qualified Group Name