(2022.1) Shibboleth Service Provider (SP) - SAML2

Installation Resources

<VirtualHost *:443> 
    ServerName pcr360.pcr.com 
    ErrorLog logs/ssl_error_log 
    TransferLog logs/ssl_access_log 
    LogLevel warn 

    SSLEngine on
    # TLS 1.2 is currently considered the only secure transport type at this time
    SSLProtocol -all +TLSv1.2 +TLSv1.3
    SSLCipherSuite HIGH:MEDIUM:!aNULL:+SHA1:+MD5:+HIGH:+MEDIUM     SSLHonorCipherOrder on
    SSLCertificateFile /etc/pki/tls/certs/pcr360_pcr_com_cert.cer 
    SSLCertificateChainFile /etc/pki/tls/certs/pcr360_pcr_com_interm.cer S
    SLCertificateKeyFile /etc/pki/tls/private/pcr360.pcr.com.key 

    DocumentRoot /var/www/pcr360/prod/public 
    SetEnv APPLICATION_ENV "prod" 
    SetEnv APPLICATION_INI "/home/vcu/pcr360/configs/pcr.ini"          

    # file system
    <Directory /var/www/pcr360/prod/public>
        DirectoryIndex index.php
        AllowOverride None
        Include /var/www/pcr360/prod/public/.htaccess
        Require all granted
      </Directory>

    # Require all traffic to go through shibboleth authentication, except the metadata
    <LocationMatch "^(?:(?!/metadata/?).)*$">
        Order deny,allow
        Deny from all
        AuthType shibboleth
        ShibRequireSession On
        # ShibRequestSetting applicationId is used in multi server configurations only
        # The setting goes into the virtual host for the test server in order to
        # specify the name of the corresponding ApplicationOverride ID in the shibboleth.2.xml file
        # ShibRequestSetting applicationId pcr360test
        ShibRedirectToSSL 443
        ExpiresActive Off
        require valid-user
        #Allow from 74.124.26.130
        Satisfy Any
    </LocationMatch>

     <Location /shibboleth-sp>
        Require all granted
    </Location>

   <Files ~ "\.(cgi|shtml|phtml|php3?)$">
		SSLOptions +StdEnvVars 
	</Files> 
</VirtualHost>

[prod : default]
; Authorization
auth.AUTH_ADAPTER = "Shibboleth"
; Shibboleth logout url used to remove shibboleth authentication cookie
auth.AUTH_LOGOUT_URL = "https://pcr360.customerurl.edu/Shibboleth.sso/Logout"
 
auth.AUTH_IDENTITY = "uid"
auth.AUTH_CREATE_USERS = true
auth.AUTH_UPDATE_USERS = true
; Enable Role Mapping - Shibboleth Security
; Groups are mapped to PCR360 Roles
auth.AUTH_ROLEMAPPING = true
; Role name to assign when no other role is mapped
auth.AUTH_DEFAULT_ROLE = "Dept Coordinator"
 
; Map these shibboleth attributes when
; Creating/updating authenticated users
auth.AUTH_ATTRMAP_USERID = "uid"
auth.AUTH_ATTRMAP_DISPLAYNAME = "displayName"
auth.AUTH_ATTRMAP_FIRSTNAME = "givenName"
auth.AUTH_ATTRMAP_LASTNAME = "sn"
auth.AUTH_ATTRMAP_EMAIL = "mail"
auth.AUTH_ATTRMAP_PHONE = "phone"
auth.AUTH_ATTRMAP_GROUPS = "isMemberOf"

[pcrprod : prod]
auth.AUTH_ADAPTER = "Native"
auth.AUTH_LOGOUT_URL = "/core/auth/"

[pcrtest : test]
auth.AUTH_ADAPTER = "Native"
auth.AUTH_LOGOUT_URL = "/core/auth/"

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

      <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. /wiki/spaces/PCRIN/pages/17266417
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. auth.AUTH_ROLEMAPPING  = false
      auth.roles.default     = "Guest"
      auth.roles.SYSADMIN    = "Administrator"
      auth.roles.COORDINATOR = "Coordinator"
      

SSO Mapping

Shibboleth, Active Directory, etc

auth.AUTH_ROLEMAPPING   = true
auth.roles.default      = "Guest"
auth.AUTH_ATTRMAP_GROUPS = "isMemberOf"
; This is the default value, if your Fully Qualified Shibboleth Group Name contains commas, this will need to be changed to a semicolon ";"
auth.AUTH_ATTR_SEPARATOR = ","

1. SSO Role Mapping allows mapping an SSO group to a PCR-360 Role.
2. 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 (2022.1) Roles form.
   2. The Fully Qualified Shibboleth Group Name is entered here to map the Role to the Shibboleth group
      
3. Once implemented, the Application will
   1. Map the Fully Qualified Shibboleth Group Name to the Role via the attribute configured by AUTH_ATTRMAP_GROUPS
   2. Add/Update the Role to users in the Fully Qualified Shibboleth Group Name