This page is a guide to installing a Shibboleth 3.x IdP - based on the Installing a Shibboleth 2.x IdP page, but updated for Shibboleth IdP version 3. This page assumes the IdP would be installed on a minimal-OS-install-only Linux system (typically a virtual machine) and follows from that point on. The IdP will be installed with the Shibboleth IdP application.

This guide is periodically updated as new versions of the software installed become available. This guide is current for IdP 3.4.0, the latest versions available as of October 2018. The guide assumes the Linux distribution would be CentOS/RHEL 7 with Tomcat7 (required). It should be possible to also use this for other Linux distribution / other operating systems, varying as needed.

If you are interested in upgrading an existing IdP to the latest release, please see Upgrading a Shibboleth 3.x IdP.

For instructions on upgrading a 2.x IdP to 3.x, please see Upgrading a 2.x IdP to 3.x.

If you are interested in linking an existing IdP into Tuakiri, please see Configuring a Shibboleth Identity Provider to join the Tuakiri Federation.

Prerequisites

Modifications to Identity Management system

Your Identity Management System (IdMS) will very likely have most of the attributes asked for by the federation - or will have enough information to synthesize the specific attribute values on the fly inside the IdP. But for some attributes, the IdMS might not have enough information. The following information should be considered for adding into your IdMS:

Preliminaries

System firewall configuration

A typical default firewall configuration on RedHat systems permits only incoming SSH.  To permit incoming connections to ports 443 and 8443:

Please remember that besides the incoming connections discussed here, the IdP also needs outgoing connections to TCP ports 80 and 443, and also to UDP port 514 for Centralized logging (more details below)

Outgoing connections are open in the default configuration of a local RHEL/CentOS firewall, but please make sure the perimeter firewall permits these connections too.


Bootstrapping the VM

We assume a standard install of either CentOS or RHEL, version 7. The IdP web application (as of version 3) needs Tomcat at least at version 7 (or the upstream instructions recommend Jetty). Also, the IdP java binaries are compiled in class format 51.0 and need Java7.  However, given that Java7 is being phased out, the IdP works well with Java8, and the compatibility issues (see the Scripted Attributes section below) are easy to resolve, we recommend installing Java8 on platforms where it's available (which does include CentOS/RHEL 7).

Install packages

Local configuration

RHEL/CentOS distributions (both 6 and 7) come with SELinux.

SELinux improves the security of the system and we recommend leaving SELinux turned on.

Up until late 2017, Tomcat was running in the unconfined context and the IdP web application did not directly benefit from SELinux, but even so, at least Apache interactions were controlled by SELinux.  And the only SELinux-specific step this manual had to cover was permitting the Apache to LDAP communication needed for ECP.

As of late 2017 (RHEL/CentOS 7.4), Tomcat runs in a confined domain.  This has serious impact on operating an IdP - as the IdP web application running inside Tomcat now runs under SELinux restrictions, it now needs all actions explicitly permitted.

We still recommend running with SELinux in enforcing mode.  A new section (Configuring SELinux for Tomcat) further below details the steps needed.  Please follow the instructions carefully - otherwise, the IdP would fail to start.


Securing the MySQL server

On RHEL/CentOS7, the mariadb-server package by default configures the MySQL server with:

Actual ways of securing the MySQL server may depend on local security policy, but overall, our recommendations are:

The following MySQL code does that - just substitute your chosen password - you can create one e.g. with: openssl rand -base64 24

DROP DATABASE test;
DROP USER ''@'localhost';
DELETE FROM mysql.user WHERE user='' and host=@@global.hostname;
UPDATE mysql.user SET password=PASSWORD('MySQL-root-password') WHERE user='root';
FLUSH PRIVILEGES;

And, you can check the list of users with:

SELECT user,host,password FROM mysql.user;

There should be no anonymous users (username blank) and all accounts should have a password set (displayed as hash, but should be non-blank).

Basic Shibboleth IdP installation

Rationale and planning

From the very beginning, we will install the Shibboleth IdP:

Having done these steps early in the installation prevents them from slipping later on.

Please note that historically, this guide was separately documenting installation of the uApprove application for users to grant consent over attribute release. This application has now been integrated into the main IdP application as the consent module - and is therefore installed (and enabled) in a basic IdPV3 deployment.

The IdP installation paths (IDP_HOME) will be /opt/shibboleth-idp (default)

Your IdP hostname will be idp.institution.domain.ac.nz
Your scope, home organization name and security domain will be institution.domain.ac.nz
Your IdP entityId will be https://idp.institution.domain.ac.nz/idp/shibboleth

Basic Shibboleth Installation

In general, it should not be necessary to re-run the installer.

  • Re-running the installer would overwrite system files under $IDP_HOME/system, but would preserve configuration files under $IDP_HOME/conf
  • But the installer would only be re-run to perform an upgrade - running the installer from a newer version distribution directory would overwrite system files in the installation directory $IDP_HOME, but would preserve the (assuming compatible) configuration files in $IDP_HOME/conf.

To just rebuild the WAR file, run $IDP_HOME/bin/build.sh instead.


Configure Tomcat and deploy the IdP WAR

Historically, the installation process involved deploying XML parser libraries as endorsed libraries in Tomcat. Since IdP 2.4.3, this is no longer needed and the step has been removed.


Configure Apache

Apache needs to be configured to:

Note: historically, this guide used to recommend to disable SSL session cache to work around a bug - while the bug was never fully tracked, the current version of OpenSSL/ShibbolethSP/httpd/mod_ssl no longer demonstrate this bug, so for performance reasons, we recommend keep SSL session caching turned on. Also, as the bug was in the back-channel communication which is rarely used with SAML2, even the impact in the unlikely case the bug reoccurs should be quite minimal.


Basic Shibboleth Configuration

Earlier documentation was instructing to create backup copies of all configuration file before modifying them - to easily identify locally made changes. This is no longer necessary since the version 3 installer creates pristine copies of all configuration files under /opt/shibboleth-idp/dist/conf


Earlier documentation was instructing to modify the generated metadata and fix the scope. This is no longer necessary because:

  • The installer now specifically asks for scope (instead of just guessing it from the hostname), so the generated metadata should contain the correct scope
  • The generated local IdP metadata is no longer used by the IdP directly.

However, the contents of $IDP_HOME/metadata/idp-metadata.xml is served by the IdP at the URL corresponding to the default IdP entityID - https://idp.institution.ac.nz/idp/shibboleth

If this URL is used anywhere to obtain the IdP metadata (we recommend against this practice, as it is insecure and fragile, but this gets used in some bilateral setups), this file will have to be kept up-to-date with the actual IdP metadata.  However, the installer should initially create it with the correct contents.



Please note that historically (in IdP 2.x), the IdP was  also loading its own metadata.  This is no longer needed and the $IDP_HOME/metadata/idp-metadata.xml file now exists only for informative purposes.


Configure the IdP to use secure cookies: by default Shibboleth IdP 3.x uses session cookies not marked as secure - which means the browser would also send them over a plain unencrypted HTTP connection.

Mark the cookies as secure by adding the following line into $IDP_HOME/conf/idp.properties:

idp.cookie.secure = true



Configure LDAP Authentication

The IdP can authenticate against a number of sources, but here we assume the authentication would be done against an LDAP directory server. For other options, please see theprimary documentation at https://wiki.shibboleth.net/confluence/display/IDP30/AuthenticationConfiguration.

By default IdPV3 already comes with a login screen (which needs to be branded with institutional logo, as discussed later on below).

While an IdP uses an LDAP server for both authentication and for resolving user attributes, these are configured as separate connections. However, the way configuration files are organized in IdPV3, both of them can be configured in $IDP_HOME/conf/ldap.properties - and this way, it is enough to configure the settings just once for the authentication part - and the attribute resolver by default copies the authentication settings.

The exact settings would very much depend on your exact LDAP server settings (and e.g., whether it requires TLS/SSL, whether it's using a self-signed certificate or a private root CA), but the settings below are what would typically need to be done (see the snippet just below for concrete examples):

These are typical settings for a simple LDAP server:

idp.authn.LDAP.authenticator                    = bindSearchAuthenticator
idp.authn.LDAP.ldapURL                          = ldap://ldap.example.org
idp.authn.LDAP.baseDN                           = ou=People,dc=example,dc=org
idp.authn.LDAP.bindDN                           = cn=read,dc=example,dc=org
idp.authn.LDAP.bindDNCredential                 = PASSWORD-GOES-HERE
# in IdP 3.2.x only
#idp.attribute.resolver.LDAP.returnAttributes    = displayName,mail,uid
idp.authn.LDAP.useStartTLS                      = false
# As we are not setting trustCertificates/trustStore, switch the sslConfig to point to jvmTrust to avoid errors for broken references....
idp.authn.LDAP.sslConfig                        = jvmTrust

And these are the settings for an Active Directory server:

idp.authn.LDAP.authenticator                    = bindSearchAuthenticator
# explicit failover over multiple DCs
idp.authn.LDAP.ldapURL                          = ldap://dc1.example.org ldap://dc2.example.org ldap://dc3.example.org
idp.authn.LDAP.baseDN                           = ou=People,dc=example,dc=org
idp.authn.LDAP.bindDN                           = cn=read,dc=example,dc=org
idp.authn.LDAP.bindDNCredential                 = PASSWORD-GOES-HERE
# in IdP 3.2.x only
# idp.attribute.resolver.LDAP.returnAttributes    = displayName,mail,sAMAccountName
idp.authn.LDAP.subtreeSearch                    = true
idp.authn.LDAP.userFilter                       = (sAMAccountName={user})
# leave TLS on
# deploy local root CA certificate as $IDP_HOME/credentials/ldap-server.crt


The default behavior for LDAP is to perform a case-insensitive search for username.  And the default behavior for the IdP is to accept the username in exactly the form as entered by the user.  Which can lead to inconsistent behavior of the IdP if the user changes the form how the username is entered (lower-case/upper-case/mixed-case...)

Force the IdP to normalize to lower-case by setting shibboleth.authn.Password.Lowercase to TRUE in /opt/shibboleth-idp/conf/authn/password-authn-config.xml:

    <util:constant id="shibboleth.authn.Password.Lowercase" static-field="java.lang.Boolean.TRUE"/>


Link your Attribute Resolver to your LDAP server

The attribute resolver is configured in /opt/shibboleth-idp/conf/attribute-resolver.xml. In the next section, we will define attributes that the IdP would be releasing about the user.

The first step is to connect the attribute resolver to the LDAP server. Edit /opt/shibboleth-idp/conf/attribute-resolver.xml and copy in the definition of the LDAP DataConnector from the sample configuration file $IDP_HOME/conf/attribute-resolver-ldap.xml

This definition is using the properties defined in ldap.properties file (configured in the previous section), so the key connection parameters should be already set.

However, it may be necessary to make some customizations:

For completeness, the definition to copy from attribute-resolver-ldap.xml is:

    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
        baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
        principal="%{idp.attribute.resolver.LDAP.bindDN}"
        principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
        useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
        connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
        trustFile="%{idp.attribute.resolver.LDAP.trustCertificates}"
        responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}">
        <FilterTemplate>
            <![CDATA[
                %{idp.attribute.resolver.LDAP.searchFilter}
            ]]>
        </FilterTemplate>
        <ConnectionPool
            minPoolSize="%{idp.pool.LDAP.minSize:3}"
            maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
            blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
            validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
            validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
            expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"
            failFastInitialize="%{idp.pool.LDAP.failFastInitialize:false}" />
    </DataConnector>

Configure Attribute Resolver - define attributes

All attribute configuration is done in /opt/shibboleth-idp/conf/attribute-resolver.xml.

IdPV3 provides two additional files that can be used as an example, attribute-resolver-full.xml and attribute-resolver-ldap.xml.  We recommend copying individual snippets (attribute and connector definitions) from these files into attribute-resolver.xml.

Edit the file and implement the following changes:

Earlier versions of the IdP were using several namespaces under urn:mace:shibboleth:2.0:resolver (urn:mace:shibboleth:2.0:resolver:ad, urn:mace:shibboleth:2.0:resolver:dc, and also neighbouring urn:mace:shibboleth:2.0:attribute:encoder).

As of IdP 3.3.0, the definitions moved into the main resolver namespace, urn:mace:shibboleth:2.0:resolver - and at the same time, switched to the convention of not using explicit XML namespace prefixes (instead relying on the default namespace being set to this single namespace).  This new type definition permits arbitrary order of the elements.

This also applies to the XSI types - these are now also specified without prefixes, and some have had their name changed (namely: ad:Script changed to ScriptedAttribute).

One exception is the SharedToken connector, which is a custom extension to the IdP and is defined in a separate namespace - the recommended sharedToken definition now uses the st: prefix for its custom namespace.

All other attribute definitions in this section here have been updated to the new syntax.


IdP 3.4.0 replaces Dependencies of Attribute Definitions and Data Connectors on other Attribute Definitions and Data Connectors with instead declaring them as inputs - and also shifts the sourceAttributeID from the attribute definition into the input specification.  This has strong implications only for very specific edge cases (where multiple dependencies produced attributes of the same name) - and otherwise is a syntactic change only.

The syntactic change is trivial: as per the upstream instructions:

  • replace a Dependency referencing an attributes with an InputAttributeDefinition referencing the same attribute.
  • replace a Dependency referencing a data connector in a definition with a sourceAttributeID with an InputDataConnector referencing the same connector and selecting the attribute from the sourceAttributeID definition:

    • e.g., turn

          <AttributeDefinition id="commonName" xsi:type="Simple" sourceAttributeID="cn">
              <Dependency ref="myLDAP" />


    • into

          <AttributeDefinition id="commonName" xsi:type="Simple">
              <InputDataConnector ref="myLDAP" attributeNames="cn" />


  • replace a Dependency referencing a data connector in a definition with no sourceAttributeID with an InputDataConnector referencing the same connector and selecting all attributes:

    <InputDataConnector ref="myLDAP" allAttributes="true" />


This documentation has already been updated to this new syntax - but existing attribute resolver configuration files will need to be transformed accordingly.  Version 3.4 will work with legacy configuration, but would produce deprecation warnings.  And support for legacy configuration will be removed in V4.


Delete existing definitions

The default attribute-resolver.xml defines the following attributes as derived from the authenticated username. While useful as interesting examples, delete the following definitions:

eduPersonPrincipalName
uid
mail
eduPersonScopedAffiliation

Link existing attributes

Define static attributes

We need to define several attributes that would have a static value for each user. We do so by first defining a StaticDataConnector (expand on the definition included in attribute-resolver.xml):

    <!-- Static Connector -->
    <DataConnector id="staticAttributes" xsi:type="Static">
        <Attribute id="o">
            <Value>The Institution</Value>
        </Attribute>
        <Attribute id="homeOrganization">
            <Value>institution.domain.ac.nz</Value>
        </Attribute>
        <Attribute id="homeOrganizationType">
            <Value>urn:mace:terena.org:schac:homeOrganizationType:int:university</Value>
        </Attribute>
    </DataConnector>

Now define the attributes:

    <AttributeDefinition id="homeOrganization" xsi:type="Simple" >
        <InputDataConnector ref="staticAttributes" attributeNames="homeOrganization" />
        <AttributeEncoder xsi:type="SAML1String" name="urn:oid:1.3.6.1.4.1.25178.1.2.9" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.9" friendlyName="homeOrganization" />
    </AttributeDefinition>

    <AttributeDefinition id="homeOrganizationType" xsi:type="Simple" >
        <InputDataConnector ref="staticAttributes" attributeNames="homeOrganizationType" />
        <AttributeEncoder xsi:type="SAML1String" name="urn:oid:1.3.6.1.4.1.25178.1.2.10" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.10" friendlyName="homeOrganizationType" />
    </AttributeDefinition>

Define scripted attributes

The eduPersonAffiliation and eduPersonPrimaryAffiliation describe the affiliation type of the user authenticating. The typical question is: "Is this person staff or student?" The full set of values (with definitions available in the AAF Attribute Recommendation: eduPersonAffiliation) is: faculty / student / staff / employee / member / affiliate / alum / library-walk-in. The eduPersonAffiliation attribute is multi-valued and should include all values that apply to the user, while eduPersonPrimaryAffiliation should contain only a single, the most relevant value.

Typically, the LDAP server will not be directly providing values for these attributes, but it would have some attributes that allow to determine at least some of the affiliation type values applying to the user - e.g. to tell whether the user is a staff member or a student.

In this case, we recommend defining the attributes using a scriptlet, synthesizing the value from the LDAP attributes available.

This would be very specific for each institution. We illustrate this in an example (based on an actual setup), where we assume the LDAP server has attributes:

We decide to give anyone with isStaff=TRUE the "staff" affiliation, and to anyone with isUnderGrad=TRUE OR isPostGrad=TRUE the "student" affiliation. Also, anyone who is staff or student also gets the "member" affiliation.

    <!-- prerequisite to scripted eduPersonAffiliation -->
    <AttributeDefinition id="isUnderGrad" xsi:type="Simple">
        <InputDataConnector ref="myLDAP" attributeNames="isUnderGrad" />
        <!-- no encoder needed -->
    </AttributeDefinition>

    <AttributeDefinition id="isPostGrad" xsi:type="Simple">
        <InputDataConnector ref="myLDAP" attributeNames="isPostGrad" />
        <!-- no encoder needed -->
    </AttributeDefinition>

    <AttributeDefinition id="isStaff" xsi:type="Simple">
        <InputDataConnector ref="myLDAP" attributeNames="isStaff" />
        <!-- no encoder needed -->
    </AttributeDefinition>
    <AttributeDefinition id="eduPersonAffiliation" xsi:type="ScriptedAttribute">
        <InputAttributeDefinition ref="isUnderGrad" />
        <InputAttributeDefinition ref="isPostGrad" />
        <InputAttributeDefinition ref="isStaff" />
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:eduPersonAffiliation" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" friendlyName="eduPersonAffiliation" />
        <Script>
        <![CDATA[
                is_UnderGrad = isUnderGrad != null && isUnderGrad.getValues().size()>0 && isUnderGrad.getValues().get(0).equals("TRUE");
                is_PostGrad = isPostGrad != null && isPostGrad.getValues().size()>0 && isPostGrad.getValues().get(0).equals("TRUE");
                is_Staff = isStaff != null && isStaff.getValues().size()>0 && isStaff.getValues().get(0).equals("TRUE");

                if (is_Staff) { eduPersonAffiliation.getValues().add("staff"); };
                if (is_UnderGrad || is_PostGrad ) { eduPersonAffiliation.getValues().add("student"); };
                if (is_UnderGrad || is_PostGrad || is_Staff ) { eduPersonAffiliation.getValues().add("member"); };
        ]]>
        </Script>
    </AttributeDefinition>
    <AttributeDefinition id="eduPersonPrimaryAffiliation" xsi:type="ScriptedAttribute">
        <InputAttributeDefinition ref="isUnderGrad" />
        <InputAttributeDefinition ref="isPostGrad" />
        <InputAttributeDefinition ref="isStaff" />
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.5" friendlyName="eduPersonPrimaryAffiliation" />
        <Script>
        <![CDATA[
                is_UnderGrad = isUnderGrad != null && isUnderGrad.getValues().size()>0 && isUnderGrad.getValues().get(0).equals("TRUE");
                is_PostGrad = isPostGrad != null && isPostGrad.getValues().size()>0 && isPostGrad.getValues().get(0).equals("TRUE");
                is_Staff = isStaff != null && isStaff.getValues().size()>0 && isStaff.getValues().get(0).equals("TRUE");

                if (is_Staff) { eduPersonPrimaryAffiliation.getValues().add("staff"); }
                else if (is_UnderGrad || is_PostGrad ) { eduPersonPrimaryAffiliation.getValues().add("student"); };
        ]]>
        </Script>
    </AttributeDefinition>

Define sharedToken

The instructions below are based on the original ARCS instructions, now archived at https://github.com/REANNZ/arcs-shibext/blob/master/INSTALL-SharedToken.md

The shared token value MUST be stored in either the LDAP server itself (preferred, keeps the values alongside primary identity information), or alternatively in a MySQL database (easier to get going by running a MySQL server directly on the IdP).

In this section, some instructions are specific to storing the shared token values in an LDAP server, some are specific to storing the values in a local MySQL server - please choose accordingly.

The arcs-shib-ext module versions 1.5.x and older are only compatible with IdP v2.x - and are not compatible with IdP V3.

The most recent version is 1.9.0 (as of October 2018) and this version is compatible only with IdP 3.4.0.

For IdP 3.2.x and 3.3.x, use version 1.8.4.

Please note that earlier versions (up to and including 1.8.2) break with Tomcat 7.0.66+, so to avoid issues with Tomcat updates (as they appear in the RHEL7 update stream as of January 2017), please update the plugin to the latest version suitable for your IdP version).

Older versions compatible with older 3.x releases are 1.7.x for IdP 3.1.x+ and 1.6.x for IdP 3.0.x

Please see https://github.com/REANNZ/arcs-shibext/releases for up-to-date information.


Configuring a MySQL database for storing sharedToken values

Defining sharedToken attribute (both LDAP and MySQL)

eduPersonTargetedID / PersistentNameID

Persistent targeted ID attributes are used to uniquely identify a user when visiting a site (an SP), but each value is targeted to that SP - and when visiting another site (a different SP), the value is different. The value can be either calculated on the fly as a hash (through the ComputeID connector), or stored in a database. We strongly recommend storing the values in a database, as it:

Historically, there were several different (conflicting) ways of defining the persistent targeted ID attribute as the eduPersonTargetedID attribute. Earlier versions of this document were referring to https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPTargetedID (instructing to define eduPersonTargetedID in the "new" format only, ignoring the "old" format).

However, as IdPv3 deprecates eduPersonTargetedID ( see ComputedIdConnector and StoredIdConnector documentation) and instead recommends using a Persistent NameID in the SAML envelope. This would make the IdP interoperable with other SAML implementations - and is still compatible with existing Shibboleth SP deployments - in the default configuration, a Shibboleth SP accepts both SAML2 Persistent Name ID and eduPersonTargetedID values as the persistent-id. However, it is crucial that an IdP only issues either the SAML2 Persistent Name ID or eduPersonTargetedID but not both - otherwise, the Shibboleth SP would accept both (identical) values as multiple values of the persitent-id attribute - and would present these values to applications in a misformatted way, concatenating them with a semicolon into a single string.

As part of the IdPv3 upgrade, we strongly encourage all IdPs to switch to SAML2 Persitent Name ID.

Earlier versions of this manual were instructing when performing an upgrade from a 2.x IdP that was using ComputedIdConnector for eduPersonTargetedID (i.e., not storing the values in a database), to first follow the instructions at Configuring an 2.x IdP to use StoredID Connector.

While it is still strongly recommended to store the values in a database, it is no longer deemed necessary to change the configuration of the version 2 IdP, as the version 3 IdP would be producing the same values.

However, if the existing persistent ID values are not stored in a database, it is crucial to use the identical salt value on the old 2.x and the new 3.x IdP.


To configure SAML2 Persistent NameID (based on https://wiki.shibboleth.net/confluence/display/IDP30/NameIDGenerationConfiguration):


 For historical purposes, we also include the original documentation on setting up eduPersonTargetedID.  However, as per above, we strongly encourage the migration to SAML2 Persistent NameID.


  1. Add the following attribute definition into attribute-resolver.xml (unfortunately, IdPV3 does NOT provide any template definition in the default configuration files):

        <resolver:AttributeDefinition xsi:type="ad:SAML2NameID" id="eduPersonTargetedID" 
                                      nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" sourceAttributeID="computedID">
            <resolver:Dependency ref="StoredIDConnector" />
            <resolver:DisplayName xml:lang="en">Targeted ID (opaque per-service username)</resolver:DisplayName>
            <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
            <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" />
        </resolver:AttributeDefinition>


  2. Add the connector definition.  To use the recommended StoredIDConnector connector, add the following definition:

        <resolver:DataConnector id="StoredIDConnector" 
                                xsi:type="dc:StoredId" 
                                sourceAttributeID="uid"
                                salt="SALSALSALTTTSALT"
                                generatedAttributeID="computedID">
            <resolver:Dependency ref="myLDAP" />
            <dc:ApplicationManagedConnection
                jdbcDriver="com.mysql.jdbc.Driver"
                jdbcURL="jdbc:mysql://localhost/idp_db?autoReconnect=true&amp;sessionVariables=wait_timeout=31536000"
                jdbcUserName="idp_admin"
                jdbcPassword="IDP_ADMIN_PASSWORD"
            />
        </resolver:DataConnector>


    making the following changes as needed:

    • Adjust the database connection accordingly (the above snippet assumes it would be reusing the idp_db database created for storing SharedToken values - storing the eduPersonTargetedID values in a separate table shibpidin the same database.
      • If choosing a different database, create that database.
      • Create the table shibpid with the following DDL code (coming from https://wiki.shibboleth.net/confluence/display/IDP30/PersistentNameIDGenerationConfiguration , and setting ENGINE to InnoDB to work around key length restrictions):

        CREATE TABLE shibpid (
            localEntity VARCHAR(255) NOT NULL,
            peerEntity VARCHAR(255) NOT NULL,
            persistentId VARCHAR(50) NOT NULL,
            principalName VARCHAR(50) NOT NULL,
            localId VARCHAR(50) NOT NULL,
            peerProvidedId VARCHAR(50) NULL,
            creationDate TIMESTAMP NOT NULL,
            deactivationDate TIMESTAMP NULL,
            PRIMARY KEY (localEntity, peerEntity, persistentId)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8;


    • If also adding storage support via JPA (see section Database Storage further below), it is possible to reuse the DataSource definition created for JPA instead of having a duplicate database connection definition in the ApplicationManagedConnection inside the StoredIDConnector.

       <dc:BeanManagedConnection>shibboleth.JPAStorageService.DataSource</dc:BeanManagedConnection>


    • Using just the username attribute (typically cn, uid or sAMAccountName) as the source attribute.
      • Note: the attribute chosen must be unique, persistent, and non-reassignable - if usernames are reused at your institution, you must choose a different attribute (e.g., objectGUID on AD servers works well for this purpose)
    • Using a value of salt generated (only at the first install, to be reused later) with:

      openssl rand -base64 36


      • Note: if converting from an existing configuration using ComputeId connector, reuse the existing salt values.  The StoredIdConnector is designed to be backwards-compatible and if provided with the same salt, will generate the same values as ComputeId connector.

    • Make sure the id and the generatedAttributeID in the connector definition match the dependency ref and the sourceAttributeID in the attribute definition.
  3. If it is not possible to use the StoredIDConnector, use instead the ComputedId connector:

        <DataConnector xsi:type="ComputedId"
                                id="computedID"
                                generatedAttributeID="computedID"
                                sourceAttributeID="uid"
                                salt="abcef123YOURVALUE">
            <resolver:Dependency ref="myLDAP" />
        </DataConnector>


    • Remember to still populate the sourceAttributeID and salt values appropriately (using the same instructions as for StoredIdConnector above)
    • Update the dependency ref in the attribute definition to match the connector id="computedID"




For reference, to deactivate a particular value for a particular user, set the deactivationDate timestamp on that value's record directly in the database - e.g. with the following SQL code:

UPDATE shibpid SET deactivationDate=NOW() WHERE principalName='user123' AND peerEntity='https://sp.example.org/shibboleth';



eduPersonAssurance

The eduPersonAssurance expresses both levels of identity assurance and authentication assurance (i.e., both how sure an IdMS is about the identity of a user and how strong authentication mechanisms were used to establish the session). These attributes would ideally have per-user values, based on information captured about the users in the IdMS - e.g., an attribute tracking whether the business process for creating the user's credentials involved checking official photoID documents and e.g. what kind of password policy applies to the user.

In the absence of such information in the IdMS, we recommend to at least define this attribute as a static attribute (providing the same value for all users) at level 1 (floor of trust). The basic requirements for level 1 are that the institution has documented processes for issuing credentials and is following good practice in managing credentials.

To configure the level 1 values as static attributes:

eduPersonEntitlement

The eduPersonEntitlement attribute is a multivalued container for arbitrary strings (URNs) that identify privileges. Most values are yet-to-be-defined, one commonly used value is urn:mace:dir:entitlement:common-lib-terms. If not adding the eduPersonEntitlement to your IdMS, we recommend defining eduPersonEntitlement as a static attribute with this value (representing "this user has library privileges") being the only value defined.

Configuring Attribute Release

Register the IdP into the federation

Please follow the instructions on registering an IdP into the Tuakiri federation (using Federation Registry URL https://registry.tuakiri.ac.nz/federationregistry/ for the Tuakiri federation or https://registry.test.tuakiri.ac.nz/federationregistry/ for Tuakiri-TEST)

For IdP version 3, these instructions need to be slightly adjusted, as IdPv3 generates three certificates/keypairs: signing, encryption and back-channel:

Advanced IdP Configuration

Configure Database Storage

The IdPV3 comes with several components that need a storage service, and several implemented and configured storage services.

However, the storage services that come enabled by default only store data in either client-side cookies (session or long-lived, possibly cryptographically encrypted and sealed), or in server memory (discarded during a server restart).

In this section, we document setting up a database storage service through JPA (Java Persistence API) and Hibernate. This sequence follows the documentation at https://wiki.shibboleth.net/confluence/display/IDP30/StorageConfiguration, adding in minor bits (that are being integrated into the documentation).

We assume the database is MySQL and for Tomcat deployments, we recommend the Tomcat JDBC pool implementation for connection pooling (defining a DataSource).

The steps to configure the database storage are:

Now that the JPAStorageService is configured, we can start reconfiguring the IdP to use this storage service in various parts - all configured in idp.properties via properties that should expand to the name of the storage service bean ( shibboleth.JPAStorageService ) :

To set all of these four modules to use the JPA Storage service, add the relevant directives into $IDP_HOME/conf/idp.properties

idp.session.StorageService=shibboleth.JPAStorageService
idp.consent.StorageService=shibboleth.JPAStorageService
idp.replayCache.StorageService = shibboleth.JPAStorageService
idp.artifact.StorageService = shibboleth.JPAStorageService

Enabling automatic reload

The default services.properties file makes most services reload their configuration every 15 minutes.  This should be considered sufficient for deploying configuration changes on a production system without having to restart the web application; for development, we recommend tweaking this setting to a lower value - e.g., to reload the attribute resolver configuration more frequently when developing attribute mappings, set:

idp.service.attribute.resolver.checkInterval = PT5S

Please note that refresh intervals configured in services.properties only apply to resources directly referenced from the service configuration ( services.xml ) - but in the case of Metadata service, not to actual metadata - this applies only to the metadata-providers.xml file itself. See the documentation on configuring metadata above for details on adjusting metadata refresh intervals.


Load Attribute Filter

This step should be done only after fully registering your IdP into the federation.

To automatically release attributes to new services registered in the federation, we will configure the IdP to load an additional attribute filter generated by the Federation Registry. Because of how resources are configured in IdPV3 (just a list of URIs), it is not possibly configure a locally-backed HTTP resource. We therefore configure the IdP to load the attribute filter from a local file, and set up independent refreshing of the local file.

If registering the IdP into multiple federations (such as into Tuakiri and AAF), load the attribute filter for each of the federations according to the respective instructions.

To configure each additional attribute filter, follow these steps:


Alternatively, set up the fetching via an external script and configure the IdP to only load an additional local file:


For both federations, please note:

  • The attribute names used in the download policy file must match the local attribute names. Check that the attribute names in the downloaded attribute filter against their names in existing configuration files:
    • attribute-resolver.xml (attribute definitions, match against the ID in the AttributeDefinition element)
    • attribute-filter.xml (local attribute filter)
  • But please note that no attributes need to be renamed with the Federation Registry since December 2010 (current as of April 2015).

ECP support

To allow your IdP to be used with the ECP profile (access via non-browser clients) to let your users access ECP-enabled services in the federation:

In order for the ECP handler (running as part of the IdP web application inside Tomcat) to receive the REMOTE_USER variable set by Apache, the AJP connector in Tomcat must have the tomcatAuthentication="false" as instructed above.

ECP will not work if the AJP connector is left with the default settings.

For information on protecting the ECP endpoint from within Tomcat instead, please see https://wiki.shibboleth.net/confluence/display/IDP30/ECPConfiguration

Configuring Single Logout

The Shibboleth IdP supports at least a minimalist implementation of Single Log Out (SLO). (This support has been added in 2.4.0 and provides the same functionality in the 3.0.x and 3.1.x release branches)

The software side of the SLO implementation comes enabled out of the box on IdPV3 installations, however, we recommend making the following changes:

Step 1: Make the following adjustments to the settings in $IDP_HOME/conf/idp.properties:

Step 2: Customize the Logout page ($IDP_HOME/views/logout.vm). 


Step 3: Register the following additional endpoints as Single Logout Service in your IdP metadata the Federation Registry, with the following bindings names and URL values (substituting your IdP hostname in the URLs):

BindingURL
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirecthttps://idp.example.org/idp/profile/SAML2/Redirect/SLO
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POSThttps://idp.example.org/idp/profile/SAML2/POST/SLO
urn:oasis:names:tc:SAML:2.0:bindings:SOAPhttps://idp.example.org:8443/idp/profile/SAML2/SOAP/SLO


On IdP 3.2.1 only, it may be necessary to apply a fix to the Logout webflow.  The issue has already been fixed upstream and the fix will be included with IdP 3.3.0 once released - this patch is to be applied to 3.2.1 only.

To avoid getting a NullPointerException from stale HttpRequest objects, make the following change to /opt/shibboleth-idp/system/flows/logout/logout-flow.xml:

--- /root/inst/shibboleth-identity-provider-3.2.1/system/flows/logout/logout-flow.xml      2015-12-19 21:48:00.000000000 +1300
+++ system/flows/logout/logout-flow.xml    2016-09-13 12:53:04.632080786 +1200
@@ -70,21 +70,21 @@
         <transition on="proceed" to="NextRelyingPartyContext" />
     </action-state>
     <view-state id="LogoutView" view="logout">
-        <on-entry>
+        <on-render>
             <evaluate expression="WriteAuditLog" />
             <evaluate expression="environment" result="viewScope.environment" />
             <evaluate expression="opensamlProfileRequestContext" result="viewScope.profileRequestContext" />
             <evaluate expression="opensamlProfileRequestContext.getSubcontext(T(net.shibboleth.idp.session.context.LogoutContext))" result="viewScope.logoutContext" />
             <evaluate expression="opensamlProfileRequestContext.getSubcontext(T(net.shibboleth.idp.profile.context.MultiRelyingPartyContext))" result="viewScope.multiRPContext" />
             <evaluate expression="T(net.shibboleth.utilities.java.support.codec.HTMLEncoder)" result="viewScope.encoder" />
             <evaluate expression="flowRequestContext.getExternalContext().getNativeRequest()" result="viewScope.request" />
             <evaluate expression="flowRequestContext.getExternalContext().getNativeResponse()" result="viewScope.response" />
             <evaluate expression="flowRequestContext.getActiveFlow().getApplicationContext().containsBean('shibboleth.CustomViewContext') ? flowRequestContext.getActiveFlow().getApplicationContext().getBean('shibboleth.CustomViewContext') : null" result="viewScope.custom" />
-        </on-entry>
+        </on-render>
         <transition on="propagate" to="LogoutPropagateView" />
         <transition on="end" to="LogoutCompleteView" />
     </view-state>
     <!-- Terminus -->

Please see https://issues.shibboleth.net/jira/browse/IDP-956 for further information.

Configuring Consent Module

Privacy laws, depending on the jurisdiction where the IdP is deployed, may require the IdP to get an explicit consent from the user before releasing personal information about the user to other parties. Thus, before proceeding with a SAML login and sending the user's attributes to the Service Provider, the IdP must first obtain the user's consent. This was historically done through a separate application, uApprove, which has now (in IdPV3) been integrated into the IdP as the consent module.

The consent module steps in the first time the user is logging in to a service, and asks the user for permission to release the required (and desired) attributes to the service. There are several options (discussed below) on when the user would be asked again - these depend on the choices made available in the configuration and on the selection user makes on the consent screen.

The consent module is turned on by default and can be used as it is, we however recommend doing (or at least considering) the following recommendations:

This completes the consent configuration.  In IdPV3, the login screen already comes configured with a check-box for resetting the consent information - which erases all consent information, including the global consent (if enabled and granted).

For additional information on configuring the consent module, please see the upstream documentation at https://wiki.shibboleth.net/confluence/display/IDP30/ConsentConfiguration

Excluding SPs from requiring consent

An institution may decide to bypass the consent module for Service Providers (SPs) operated by the institution internally - as the attributes being released are not crossing organizational boundaries. This can be configured by defining a conditon and attaching the condition as activationCondition to the intercept/attribute-release flow in /opt/shibboleth-idp/conf/intercept/profile-intercept.xml.


    <bean id="shibboleth.AvailableInterceptFlows" parent="shibboleth.DefaultInterceptFlows" lazy-init="true">
        <property name="sourceList">
            <list merge="true">
                <bean id="intercept/context-check" parent="shibboleth.InterceptFlow" />
                <bean id="intercept/terms-of-use" parent="shibboleth.consent.TermsOfUseFlow" />
                <bean id="intercept/attribute-release" parent="shibboleth.consent.AttributeReleaseFlow" p:activationCondition-ref="AttributeReleaseActivationCondition" />
            </list>
        </property>
    </bean>


    <bean id="AttributeReleaseActivationCondition" parent="shibboleth.Conditions.AND">
        <constructor-arg>
            <!-- The default condition from system/conf/profile-intercept-system.xml -->
            <bean parent="shibboleth.Conditions.OR">
                <constructor-arg>
                    <bean parent="shibboleth.Conditions.NOT">
                        <constructor-arg value="%{idp.consent.allowPerAttribute:false}" />
                    </bean>
                </constructor-arg>
                <constructor-arg>
                    <bean class="net.shibboleth.idp.saml.profile.config.logic.IncludeAttributeStatementPredicate" />
                </constructor-arg>
            </bean>
        </constructor-arg>
        <constructor-arg>
            <!-- A custom condition -->
            <bean parent="shibboleth.Conditions.NOT">
                <constructor-arg>
                    <bean parent="shibboleth.Conditions.RelyingPartyId">
                        <constructor-arg>
                            <bean class="com.google.common.base.Predicates" factory-method="containsPattern"
                                c:pattern="^https://[^/]+\.institution\.domain\.ac\.nz/shibboleth$" />
                        </constructor-arg>
                    </bean>
                </constructor-arg>
            </bean>
        </constructor-arg>
    </bean>




Friendly attribute names

By default, uApprove would be representing attributes by their local alias - which may not provide the best possible user experience. Names like "eduPersonPrincipalName" look quite cryptic to an ordinary user. The metadata syntax allows to provide friendly names (even locale-specific multiple names) in the attribute-resolver.xml file, and uApprove will pick the attribute names from there.

The syntax for specifying the attribute names is:

    <AttributeDefinition xsi:type="Simple" id="email" >
        <InputDataConnector ref="myLDAP" attributeNames="mail" />
        <DisplayName xml:lang="en">Email address</resolver:DisplayName>
        <AttributeEncoder xsi:type="SAML1String" name="urn:mace:dir:attribute-def:mail" />
        <AttributeEncoder xsi:type="SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" />
    </AttributeDefinition>

Add the following attribute descriptions for the respective attributes into attribute-resolver.xml, right between the Dependency and AttributeEncoder elements:

uid:                           <DisplayName xml:lang="en">Local user ID</DisplayName>
email:                         <DisplayName xml:lang="en">Email address</DisplayName>
commonName:                    <DisplayName xml:lang="en">Common name</DisplayName>
surname:                       <DisplayName xml:lang="en">Surname</DisplayName>
givenName:	                   <DisplayName xml:lang="en">Given name</DisplayName>
eduPersonPrincipalName:        <DisplayName xml:lang="en">Global username (EPPN)</DisplayName>
displayName:	               <DisplayName xml:lang="en">Display name</DisplayName>
organizationName:              <DisplayName xml:lang="en">Institution name</DisplayName>
organizationalUnit:            <DisplayName xml:lang="en">Organisational Unit</DisplayName>
homeOrganization:              <DisplayName xml:lang="en">Institution domain</DisplayName>
homeOrganizationType:          <DisplayName xml:lang="en">Institution type</DisplayName>
eduPersonAffiliation:          <DisplayName xml:lang="en">Affiliation type</DisplayName>
eduPersonScopedAffiliation:    <DisplayName xml:lang="en">Affiliation type (with institution)</DisplayName>
eduPersonPrimaryAffiliation:   <DisplayName xml:lang="en">Primary affiliation type</DisplayName>
eduPersonEntitlement:          <DisplayName xml:lang="en">Entitlements</DisplayName>
eduPersonAssurance:            <DisplayName xml:lang="en">Identity assurance level</DisplayName>
eduPersonTargetedID:           <DisplayName xml:lang="en">Targeted ID (opaque per-service username)</DisplayName>
auEduPersonSharedToken:        <DisplayName xml:lang="en">Shared token</DisplayName>
auEduPersonLegalName:          <DisplayName xml:lang="en">Legal name</DisplayName>
auEduPersonAffiliation         <DisplayName xml:lang="en">Affiliation type (Australian extensions)</DisplayName>
postalAddress                  <DisplayName xml:lang="en">Business postal address</DisplayName>
telephoneNumber                <DisplayName xml:lang="en">Business phone number</DisplayName>
mobileNumber                   <DisplayName xml:lang="en">Mobile phone number</DisplayName>

DataSealer Key Refreshing

The IdP uses an encryption mechanism, primarily used for the client-side storage (storing information in encrypted client-side cookies), where the IdP relies on an AES secret key. This key needs to be periodically refreshed.  The IdP can be configured to keep around a given number of past versions of the key (defaulting to 30).  Any new information gets encrypted with the newest key; any information received encrypted with older key can still be decrypted as long as the old key is still retained.  For further information, please see https://wiki.shibboleth.net/confluence/display/IDP30/SecretKeyManagement.

In the Database Storage section above, we have recommended to configure server-side database storage to use instead of the client-side cookie storage service.  If this has been done and the client-side storage is not being used, this step can be skipped.

Otherwise, configure a cron job that would be periodically refreshing the encryption key.  The recommended command to refresh they key is:

IDP_HOME=/opt/shibboleth-idp JAVA_HOME=/usr/lib/jvm/java /opt/shibboleth-idp/bin/seckeygen.sh --versionfile /opt/shibboleth-idp/credentials/sealer.kver --storefile /opt/shibboleth-idp/credentials/sealer.jks --storepass changeit  --alias secret 

To run this as a cronjob, run crontab -e as either root or tomcat and add this entry to rotate the key each night:

3 3 * * * IDP_HOME=/opt/shibboleth-idp JAVA_HOME=/usr/lib/jvm/java /opt/shibboleth-idp/bin/seckeygen.sh --versionfile /opt/shibboleth-idp/credentials/sealer.kver --storefile /opt/shibboleth-idp/credentials/sealer.jks --storepass changeit  --alias secret 



Centralized Usage Logging

Reporting on federation usage is difficult, in particular because not all services use the centralized Discovery Service.

To address this, IdPv3 adds supporting for sending anonymized usage data in the F-TICKS format to a centralized log service (via syslog messages to UDP port 514).

Tuakiri runs such a service on hosts:

Once configured, an IdP would send a syslog message to the centralized log service for each session established. The message includes:

A sample message may look like:

F-TICKS/Tuakiri-TEST/1.0#TS=1467772333#RP=https://attributes.staging.tuakiri.ac.nz/shibboleth#AP=https://virtualhome.test.tuakiri.ac.nz/idp/shibboleth#PN=b61fca51c22df2e5ddb961bb5dfec9a672e627668b4bf2c45de0a719540179cc#RESULT=OK#


To enable this service, please make the following changes (based on upstream instructions at https://wiki.shibboleth.net/confluence/display/IDP30/FTICKSLoggingConfiguration):

Please make sure the firewall permits outgoing UDP packets to port 514 (at least for the Tuakiri log collection server)


Configuring SELinux for Tomcat

We recommend operating an IdP with SELinux in enforcing mode.

Since CentOS 7.4, Tomcat runs inside a confined domain, providing additional security.  However, as a result, there are additional configuration steps that need to be taken go give the IdP application  (or to Tomcat as the application server) permissions to access certain files.

Implementing these steps is required - otherwise, the IdP would fail to start.

The IdP needs R/W access to /opt/shibboleth-idp - primarily read access, but write access for updating local copies of federation metadata and attribute filters.

Tomcat has R/W access to content labeled as tomcat_var_lib_t.  However, as the IdP also needs access to the back-channel certificate in /opt/shibboleth-idp/credentials, we need to use the cert_t label here - to give both Apache and Tomcat read access to the certificate.

On CentOS 7.4 only, it is necessary to implement a workaround to give Tomcat permission to connect to MySQL.

On CentOS 7.5, the missing permission has been added and this workaround is no longer necessary - you can skip the rest of this section.

If you are running CentOS 7.4, please unfold the box below to see the details of the workaround - archived otherwise for histroical purposes only.

Tomat needs to be able to connect to MySQL - and unfortunately, this has been so far omitted in the SELinux policy for target.  While we expect this to be fixed in future updates to the SELinux policy, for now, we have to use a workaround - create a custom policy module.

  • Create a policy type enforcement file defining a policy module tomcat-to-mysql - in a working directory (e.g., /root/inst) create tomcat-to-mysql.te with the following contents:

    module tomcat-to-mysql 1.0;
    
    require {
            type tomcat_t;
            type mysqld_port_t;
            class tcp_socket name_connect;
    }
    
    #============= tomcat_t ==============
    allow tomcat_t mysqld_port_t:tcp_socket name_connect;


  • Compile, package and load the module with:

    checkmodule -m -M -o tomcat-to-mysql.mod tomcat-to-mysql.te
    semodule_package -o tomcat-to-mysql.pp -m tomcat-to-mysql.mod
    semodule -i tomcat-to-mysql.pp


With these in place, Tomcat should have all the SELinux permissions required and the IdP should operate normally.


Enabling HSTS

Since version 3.4.0, the IdP supports HSTS - HTTP Strict Transport Security:

This setting is controlled by the idp.hsts property in idp.properties.
To enable HSTS, change its max-age property from the default value 0 (disabled) to a reasonably long value (industry practice is at least 6 months, preferably 1 year):


idp.hsts = max-age=31536000


Additional Information

Please see the IdPv3 wiki for further information. Useful pages for additional configuration options are:

Compatibility workaround (IdP 3.1.x only)

Login breaks on IdP 3.1.x with SPs misconfigured to request AuthenticationType urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified.

Version 2 IdP just ignores that misconfiguration and login works. Version 3.2.0 includes a proper workaround, allowing to add a list of contexts to be ignored, with this value being included by default.

On IdP 3.1.x, as an interim workaround, modify $IDP_HOME/system/conf/general-authn-system.xml and add this value to the list of supportedPrincipals in the shibboleth.AuthenticationFlow bean:

--- /opt/shibboleth-idp/system/conf/general-authn-system.xml.dist 2015-11-18 10:55:36.713111653 +1300
+++ /opt/shibboleth-idp/system/conf/general-authn-system.xml    2015-11-18 10:55:39.520094266 +1300
@@ -40,6 +40,8 @@
                     c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" />
                 <bean parent="shibboleth.SAML2AuthnContextClassRef"
                     c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
+                <bean parent="shibboleth.SAML2AuthnContextClassRef"
+                    c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified" />
                 <bean parent="shibboleth.SAML1AuthenticationMethod"
                     c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
             </list>

For further details, please see https://issues.shibboleth.net/jira/browse/IDP-780

Note that as this interim workaround is applied to a file under $IDP_HOME/system/, it would get overwritten in an upgrade - but, the next version the upgrade would be introducing should already have the proper permanent workaround included.

No action is required on IdP 3.2.0+

Starting the IdP

Customization and Branding

In a default install, the IdP login screen is displaying the Shibboleth project logo, a default prompt for username and password, and text (embedded in the logo) saying that this screen should be customized. To establish trust with users, this page should at the very least have the proper institution logo and name and the instructions to customize the page should be removed. Each institution may also wish to customize the graphics to match the style of their login pages - and also the consent pages, logout pages and error pages to give a consistent professional look.

Historically, all of the pages have been JSP pages. While JSP is still left as an option, the default way IdPV3 renders these pages is from a Velocity template under $IDP_HOME/views. The main advantage is not having to rebuild the IdP WAR file after a change to the dynamic pages.

However, any images, css files (as well as any other static HTML content) are served from within the WAR file. But, for development of the branding, this can be worked around with Apache aliases to serve the files directly - see below.

We therefore recommend customizing the Velocity login page (and a few additional pages), adding supplementary images and CSS files (or modify existing) as needed, and leave out the JSP files.

The Velocity templates can be configured through message properties defined in message property files. The exact location depends on the IdP version.

We recommend configuring at least the following properties:

Overall, the changed message properties might look like:

idp.title = University of Example Login Service
idp.logo = /images/logo.jpg
idp.logo.alt-text = University of Example logo
idp.footer = Copyright University of Example
root.footer = Copyright University of Example

This would cover the basic customization.  Depending on branding requirements, it may be sufficient to edit the CSS files in $IDP_HOME/edit-webapp/css, or it may be necessary to start editing the template pages.

Most of the branding can be done with CSS and with customizing messages in $IDP_HOME/messages/auth-messages.properties (and also consent-messages.properties and error-messages.properties in the same directory.

Please note that the consent module uses a separate CSS file: while the login page and most other pages use $IDP_HOME/edit-webapp/css/main.css, the consent module uses $IDP_HOME/edit-webapp/css/consent.css with different element names.

Note that if using CSS to customize the logo appearance, while the consent module pages use the federation_logo class on the logo <img> element, the other pages (login and logout) do not.  It may help to edit these templates and add class="federation_logo" to the logo <img> tag.

Besides the logo, the login page (and several other pages) display a toolbox on the right with placeholders for links to password-reset and help-desk pages.  These can be customized by editing $IDP_HOME/messages/authn-messages.properties and setting (with values appropriate to local context):

idp.url.password.reset = http://help.institution.ac.nz/ChangePassword/
idp.url.helpdesk = http://help.institution.ac.nz/

Alternatively, it is also possible to hide the whole toolbox (the whole <div class="column two"> element) from all of the relevant pages (essentially, login.vm and all (three) logout pages: logout.vmlogout-complete.vm and logout.propagate).  This can be easily done by adding the following CSS snippet into $IDP_HOME/edit-webapp/css/main.css:

.column.two {
    display: none;
}


Overall, the pages under $IDP_HOME/views we recommend customizing are:

For any change done to one page, we recommend applying the change to all of the above pages.

An additional page to customize (but based on a different template) is:

This page still reuses the Logo settings from error-messages.properties above, but does not have the toolbox and footer used by the other three pages above.  It is a deployment decision whether to unify the look of these pages or keep the slightly different look of the attribute release page.

We however recommend to at least change the width of the .box element in /opt/shibboleth-idp/edit-webapp/css/consent.css from 600px to 800px to accommodate the full width of the  friendly attribute names:

diff --git a/idp-war/src/main/webapp/css/consent.css b/idp-war/src/main/webapp/css/consent.css
index 5daabeed0..a5b6313b3 100644
--- edit-webapp/css/consent.css.orig
+++ edit-webapp/css/consent.css
@@ -1,5 +1,5 @@
 .box {
-    width:600px;
+    width:800px;
     margin-left: auto;
     margin-right: auto;
     margin-top: 50px;


Earlier versions of this documentation were recommending to aid with developing the branding by temporarily serving the CSS and image files out of the /opt/shibboleth-idp/webapp directory directly.  However, since Shibboleth IdP 3.4.0, the webapp directory is considered a temporary artififact of the build process and the build script deletes it after building the WAR file.  (And this technique was also getting more complicated with Apache and Tomcat being in different SELinux containers).  Therefore, these instructions have been removed.

When done with changes to the images and css directories, remember to rebuild the WAR file and restart Tomcat:

$IDP_HOME/bin/build.sh
service tomcat restart

Administrative Interface

The IdPV3 software comes with an administrative interface, that provides several functions:

For all of these functions, the IdP uses a (configurable) access control mechanism - which is initially the same across all the above functions and is by default IP addressed based, permitting only localhost.

The policy in use can be configured in the $IDP_HOME/conf/admin/general-admin.xml file.

The policy selection used to be in $IDP_HOME/conf/idp.properties with the below properties - but this has been removed in 3.3.x.  Now the policy selection is done in $IDP_HOME/conf/admin/general-admin.xml directly:

idp.status.accessPolicy= AccessByIPAddress
idp.resolvertest.accessPolicy= AccessByIPAddress
idp.reload.accessPolicy= AccessByIPAddress


The policy itself is configured in $IDP_HOME/conf/access-control.xml and we recommend adding at least the external address of the IdP itself to allow resolver testing to work. And it would be also recommended to add the IP address of the local monitoring system to permit monitoring access, and possibly also the IP address of a management console from where an admin could trigger the reload of the services (this can be the IdP itself the administrator is able to run a browser there).

The IP addresses are specified as a comma-separated list of CIDR expressions - the example below adds a single IPv4 address to the default configuration (permitting IPv4 and IPv6 localhost):

    <util:map id="shibboleth.AccessControlPolicies">

        <entry key="AccessByIPAddress">
            <bean parent="shibboleth.IPRangeAccessControl"
                p:allowedRanges="#{ {'127.0.0.1/32', '::1/128', '192.168.0.1/32' } }" />
        </entry>

    </util:map>


After configuring access, the administrative functions can be accessed with either a browser or any HTTP capable tool, by accessing the following URLs:

Earlier versions of the IdP (2.x) had a publicly accessible URL /idp/profile/Status that would return simple "ok".  This URL was long marked as deprecated and has been removed in IdPV3...

Testing

The best way to test an IdP is to try to log into a Service Provider in the federation. Tuakiri provides a service specifically designed for this purpose, the Attribute Validator.  The Attribute Validator displays all of the attributes received from the IdP, and in addition to that performs a number of checks to confirm the values are valid.  Tuakiri is running an attribute reflector in both Tuakiri-production and Tuakiri-TEST federations. Both reflectors are running as standalone services at URLs listed below and are requesting all attributes available in the federation - hence, they work very well for testing all the attributes released by your IdP.

The attribute reflector URLs are:

An alternative tool for testing IdP is the Attribute Authority Command Line Interface client - aacli.sh.

The tool output is the whole set of attributes that would be released for this user to the given user (the Tuakiri Attribute Validator in the example below - if testing for another service, pass the entityId of the service in the --requester option).

Contrary to how this tool functioned in earlier version (2.x - where it launched the full IdP engine in parallel), the tool uses the resolvertest functionality on the IdP itself (see Administrative Interface above - also for instructions on setting up access control).

We recommend connecting the aacli.sh tool to the IdP via the public-facing HTTPS interface (as the default Apache idp.conf does not map the plain-http space to the IdP tomcat web application).  Therefore, run the aacli tool as:

$IDP_HOME/bin/aacli.sh --principal TEST-USER --requester https://attributes.tuakiri.ac.nz/shibboleth --url https://idp.instition.domain.ac.nz/idp

where the parameters are:

Alternatively, it is also possible to access the resolvertest URL directly via a browser (as documented above in Administrative Interface).   These URLs are subject to access control (by default accessible only from localhost); the options for gaining access include:

Other options for testing including using the UnsolicitedSSO: invoking a URL directly at the IdP and pretending as if an SP initiated the request. This can be used for testing even in situations where the IdP is not yet registered in the federation (but is already loading the federation metadata).  While the SSO would not be accepted by the SP in that case (the IdP would not be trusted through the federation), it allows to test the full login and attribute release process at the IdP.  To test SSO against the Tuakiri Attribute Reflector, open the following URL (substituting the correct IdP hostname): https://idp.institution.ac.nz/idp/profile/SAML2/Unsolicited/SSO?providerId=https://attributes.tuakiri.ac.nz/shibboleth