Page History

This example is based on the based on How to configure Shibboleth SP attribute checker

...

. Please see that wiki page for further description on how to use Shibboleth SP attribute checker.

Shibboleth Service Provider (SP)

The list of attributes released by an IdP varies heavily and occasionally required attributes needed by an SP are not released by the user's IdP. This leads to failed logins and the error page doesn't give clear information of the failure reason (eg. what attributes are missing). You can always check the attributes on an application level. The approach described here is done on the Shibboleth SP level (requires Shibboleth 2.5+) and does not require changes to the application using the attibutes.

Shibboleth SP provides a hook for performing attribute checks for required attributes and a attribute extractor for fetching Identity Provider (IdP) metadata attributes where the login was performed. The end result (from the user's perspective) then is an error message like shown below in case the user's Identity Provider did not release sufficiently user information to the service:One also finds some further explanation and a quick demo in this screen castWithout require any changes to the service the end user'will get an error message. THe example contains an a possiblity for the end user to send a detailed error report to their Identity Provider support contact.

In this example the Identity Provider is tested for

• metadata declaration for support of REFEDS SIRTFI; and
• attribute release based on REFEDS R&S.

Attribute Checker Handler

The AttributeChecker validates the user session against attributes specified as a required. If requirements are fulfilled, the login completes otherwise an error page is displayed instead. Note that the required attributes have to be "hard coded" here and kept in sync with the required attributes expressed in the Metadata.

Configuration

Add a sessionHook for attribute checker: sessionHook="/Shibboleth.sso/AttrChecker" to ApplicationDefaults.

...

 Add also the metadataAttributePrefix="Meta-" (This will be explained later).

In context: /etc/shibboleth/shibboleth2.xml -> ApplicationDefault element

<ApplicationDefaults entityID="https://<HOST>/shibboleth"
  REMOTE_USER="eppn persistent-id targeted-id"
  signing="front" encryption="false"
  sessionHook="/Shibboleth.sso/AttrChecker"
  metadataAttributePrefix="Meta-" >

Add the attribute checker handler with the list of required attributes to Sessions

...

.

/etc/shibboleth/shibboleth2.xml -> Sessions element

...

...

If you want to describe more complex scenarios with required attributes, operators such as "AND" and "OR" are available.

<Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html" flushSession="true">
  <AND>
    <!-- Check for REFEDS SIRTFI Assurance Declaration in metadata -->
    <Rule require="Meta-AssuranceCertification">https://refeds.org/sirtfi</Rule>
    <!-- Check for REFEDS R&S compliant attribute release -->
    <Rule require="eppn"/>
    <Rule require="mail"/>
    <OR>
      <Rule require="displayName"/>
      <AND>
        <Rule require="givenName"/>
        <Rule require="surname"/>
      </AND>
    </OR>
  </AND>
</Handler>

Now we have an session hook for the attribute checker to check specified attributes before a user login is completed.

Add the AttributeExtractor element of the type metadata next to the already existing type XML: (<AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/>)

For customization of and error checks on the error page (attrChecker.html) we want to enable the "Attribute Extractor" with the type "metadata" to be able to fetch IdP attributes from the metadata feed. The Attribute attributes we need is the email address addresses of the IdP support contactand security contacts. We've already added metadataAttributePrefix to the ApplicationDefaults element.

Add the AttributeExtractor element of the type metadata next to the already existing type XML: (<AttributeExtractor type="XML" validate="true" path="attribute-map.xml"/>)

/etc/shibboleth/shibboleth2.xml -> ApplicationDefault element

<!-- Extracts support information for IdP from its metadata. -->
<AttributeExtractor type="Metadata" errorURL="errorURL" DisplayName="displayName"
                    InformationURL="informationURL" PrivacyStatementURL="privacyStatementURL"
                    OrganizationURL="organizationURL">
  <ContactPerson id="Support-Contact"  contactType="support" formatter="$EmailAddress" />
  <ContactPerson id="Other-Contact"  contactType="other" formatter="$EmailAddress" />
  <Logo id="Small-Logo" height="16" width="16" formatter="$_string"/>
</AttributeExtractor>

...

When you modify shibboleth2.xml you can test validity of the configuration file with command "shibd -t". If configuration file is still valid XML you can now restart your shibboleth with "sudo service shibd restart". Shibboleth should anyways reload configuration file if it detects any change on it.

Add attribute definition for the metadata Assurance Certification attribute

To be able to check for REFEDS SIRTFI you need to add a definition for the metadata based attribute Assurance Certification. We've already added metadataAttributePrefix to the ApplicationDefaults element in shibboleth2.xml.

/etc/shibboleth/attribute-map.xml -> Attributes element

<!-- Metadata based attribute for Assurance Certification -->
<Attribute name="urn:oasis:names:tc:SAML:attribute:assurance-certification" id="AssuranceCertification"/>

Logging

Shibboleth SP doesn't track nor log failed logins due to missing attributes. The Shibboleth SP web server can be used for "pixel tracking". This means that you load an image (eg: containing only one transparent pixel) from the web server from where you can monitor logs and observe access for you image. In the url of your image you can also insert details you want to see, eg: Authentication source (IdP) and missing attributes.

...

<img title="track" src="/track.png?idp=<shibmlp entityID/>&miss=<shibmlpifnot displayName>-displayName</shibmlpifnot><shibmlpifnot givenName>-givenName</shibmlpifnot><shibmlpifnot cn>-cn</shibmlpifnot><shibmlpifnot sn>-sn</shibmlpifnot><shibmlpifnot eduPersonPrinpalName>-eduPersonPrinpalName</shibmlpifnot><shibmlpifnot schacHomeOrganization>-schacHomeOrganization</shibmlpifnot><shibmlpifnot schacHomeOrganizationType>-schacHomeOrganizationType</shibmlpifnot>" alt="" width="1" height="1" />

Template customization

The attrChecker.html is located in the "/etc/shibboleth" directory. If you don't want to edit it by yourself, you can use the ready made template. The template has links to external components such as jquery and bootstrap. They are fetched on the fly from third party sources. Basically there are three locations needing modifications:

...