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
To enable a single Terms of Use text to be presented to all users once before they see the attribute release consent dialog,
apply these four steps:
/opt/shibboleth-idp/conf/relying-party.xml in the bean definitionshibboleth.DefaultRelyingParty replace:
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" />with:
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" />
and replace:
<bean parent="SAML2.SSO" p:postAuthenticationFlows="attribute-release" />with:
<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"/>with:
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" p:includeAttributeStatement="true"/>
/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="com.google.common.base.Functions" factory-method="constant">
<constructor-arg value="my-terms-of-use" />
</bean>
The value my-terms-of-use is the key into the properties file that gets updated next.
/opt/shibboleth-idp/messages/messages.properties
delete (or comment out with a leading #) these three properties:
https\://sp.example.org = 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> \
...
</p>
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. \
</p>
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 local.properties file, provided you adopted the optional configuration in section Messages Translations in the IdP installation guide.
/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...").html property, now that the .text property is only used as key.
Add translations for the consent messages the same way as for other messages.properties files. In the Shibboleth Wiki you find translated consent-messages.properties files.
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.
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:
transientIdpersistentIdeduPersonTargetedIDSince 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.
swissEduPersonUniqueIDeduPersonPrincipalNameeduPersonUniqueIdFurther 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.
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.
Copyright: SWITCH
Author: aai@switch.ch
Date: 2017-10-04
Changelog