Shibboleth IdPv3 User Consent Configuration Guide

    This guide describes how to tailor the most important features in the user consent configuration for the Shibboleth Identity Provider (IdP) v3.x for deployments in the SWITCHaai federation. To learn about all possible configuration options, consult the IdPv3 user consent configuration reference in the Shibboleth Consortium Wiki.
    This guide is targeted at system administrators who are familiar with XML syntax.

    Note: For Shibboleth IdPv2.x installations, consult the uApprove documentation.


    You have installed the Shibboleth IdPv3.x according to the Shibboleth Identity Provider (IdP) 3 Installation Guide for deployments in the SWITCHaai federation

    Enable a Single 'Terms Of Use' Text

    To enable a single Terms of Use text to be presented to all users once before they see the attribute release consent dialog, A single example Terms of Use text
    apply these four steps:

    1. In the file /opt/shibboleth-idp/conf/relying-party.xml in the bean definitionshibboleth.DefaultRelyingParty replace:
      <bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" />
      <bean parent="Shibboleth.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" />
      and replace:
      <bean parent="SAML2.SSO" p:postAuthenticationFlows="attribute-release" />
      <bean parent="SAML2.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" />
      and a bit further down in the bean definition RelyingPartyByGroup replace:
      <bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" p:includeAttributeStatement="true"/>
      <bean parent="Shibboleth.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" p:includeAttributeStatement="true"/>
    2. In the file /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml disable the alias for shibboleth.consent.terms-of-use.Key by commenting it out:
      <alias alias="shibboleth.consent.terms-of-use.Key" name="shibboleth.RelyingPartyIdLookup.Simple" />
      and insert this comment together with the alias definition and the bean definition:
      This activates a single Terms of Use text to be presented once before the user
      sees the first time the attribute release consent dialog.
      <alias alias="shibboleth.consent.terms-of-use.Key" name="shibboleth.SingleTermsOfUseText" />
      <bean id="shibboleth.SingleTermsOfUseText"
              class="" factory-method="constant">
          <constructor-arg value="my-terms-of-use" />

      The value my-terms-of-use is the key into the properties file that gets updated next.

    3. In the file /opt/shibboleth-idp/messages/ delete (or comment out with a leading #) these three properties:
      https\:// = example-tou-1
      example-tou-1.title = Example Terms of Use
      example-tou-1.text  = <em>*** This is an example ToU - tailor due to your needs ***</em> \
      and add these four properties with your own Terms of Use text, title and html:
      my-terms-of-use = my-tou-v1_0
      my-tou-v1_0.text = My Organization Version 1.0 Terms of Use, 1 January 2017
      my-tou-v1_0.title = My Organization Terms of Use
      my-tou-v1_0.html = <h1>My organization Terms of Use</h1> \
                    <p>Lorem ipsum dolor sit amet, \
                    consectetur adipiscing elit. \

      The property my-terms-of-use maps to the value my_tou-v1_0 that gets used as key for the text, title and html for your Terms of Use information. Feel free to use another string as key, just use it consistent. The IdP uses the value in .text as key into the database to find out whether the user already accepted this version.
      By introducing a separate .html property for the text really displayed to the user, you could fix typos and other minor glitches in the text without enforcing ToU re-approval for all users. To deliberately change the ToU version modify the text in .html and increase the version number in the .text property.

      Note: You can apply the above changes to your file, provided you adopted the optional configuration in section Messages Translations in the IdP installation guide.

    4. In the template file /opt/shibboleth-idp/views/interept/terms-of-use.vm customize the look-and-feel as you like, but replace at least the following line
          #springMessageText("${termsOfUseId}.text", "Terms of Use Text...")
          #springMessageText("${termsOfUseId}.html", "Terms of Use Text...")
      to display the contents of the .html property, now that the .text property is only used as key.

    Add Translations for Consent Messages

    Add translations for the consent messages the same way as for other files. In the Shibboleth Wiki you find translated files.

    Attribute Sequence in the Attribute Release Consent

    Without an AttributeDisplayOrder list [feature introduced in IdPv3.2.1] defined in the file /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml, attributes get listed in alphabetical order of their IDs.

    Note: In IdPv3.2 the ordering could only be achieved with a whitelist. Since IdPv3.2.1, this is no longer necessary. Therefore, SWITCH recommends to configure an empty whitelist together with a catchall MatchExpression as in the consent-intercept-config.xml template provided by SWITCH.
    In case you would ever whitelist an attribute this catchall match expression prevents the IdP to treat all further attributes as they were blacklisted. Without the catchall match expression they would be released but not displayed on the consent screen.

    Hide Attributes from Attribute Release Consent

    By default, attribute release consent lists all attributes to be released. As an exception to this rule, a default blacklist contains three attributes with cryptic, opaque identifiers:

    • transientId
    • persistentId
    • eduPersonTargetedID

    Since IdPv3.2, the SWITCH IdP installation guide includes a template that blacklists also the following three unique identifiers that usually have cryptic values. In the former default uApprove configuration for IdPv2, unique identifiers were already blacklisted.

    • swissEduPersonUniqueID
    • eduPersonPrincipalName
    • eduPersonUniqueId

    Further attributes can be listed in the file /opt/shibboleth-idp/conf/intercept/consent-intercept-config.xml in the bean configuration shibboleth.consent.attribute-release.BlacklistedAttributeIDs.
    SWITCH does not recommend to blacklist further attributes unless you have a very good reason to hide them from the users.

    Note: In IdPv3.2.0, for the blacklist to be effective, you needed to list these values also in the whitelist. That was fixed in IdPv3.2.1.

    Suppress Consent for 'Trusted' Service Providers

    It is possible to suppress the user consent dialog for SWITCHaai service providers operated by specific home organizations and/or types of home organizations. This option is provided for backwards compatibility with IdPv2's uApprove's services/services.blacklist settings, for sites wishing to retain the existing behavior.
    In general, SWITCH recommends using the IdPv3 default settings, i.e. enabling user consent for all SPs.

    Edit the file /opt/shibboleth-idp/conf/relying-party.xml and follow the instructions included in that file.

    Version Information

    Copyright: 	SWITCH
    Date:		2017-10-04