Installation Resources

Apache Virtual Host Example Configuration

Apache 2.4 - Notice the SSL configuration is included as SSL is required for Shibboleth login.

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

Installing Shibboleth

Install the Shibboleth Repo

Install using RPM: https://wiki.shibboleth.net/confluence/display/SP3/RPMInstall

Visit https://shibboleth.net/downloads/service-provider/RPMS/, choose your platform, then click Generate

Metadata Generation

Service Provider Metadata

All customers using the Shibboleth module will require metadata generated form the Application installed in their SSO
If Shibboleth is configured and running the Metadata will be generated by the application

PCR-360 Example Configuration

[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/"

Shibboleth Configuration

Be sure to check the version when configuring Shibboleth.
Updates to the configuration have occurred in version 3 that make the configurations and certificates for version 2 incompatible.

Version 2

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:

At minimum, we need the attribute name and and attribute id.
Shibboleth genrally send these attributes by default:
1. a unique id (eppn, uid, or similar)
2. first name
3. last name
4. email address
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.
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

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:

unique id (eppn or similar)
first name
last name
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

Contact types are manually mapped to roles in the application config INI
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 = ","

SSO Role Mapping allows mapping an SSO group to a PCR-360 Role.
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 Shibboleth Group Name is entered here to map the Role to the Shibboleth group
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

Browser not supported