Files: conf/idp.properties, conf/intercept/consent-intercept-config.xml, messages/message.properties, views/intercept/attribute-release.vm, views/intercept/terms-of-use.vm
Format: Native Spring
Overview
The IdP includes the ability to require user consent to attribute release, as well as presenting a "terms of use" message prior to completing a login to a service, a simpler "static" form of consent.
Consent is implemented by the intercept/attribute-release and intercept/terms-of-use interceptor flows.
Enabling Module (V4.1+)
For V4.1+, configuring and using this feature requires that you first enable the "idp.intercept.Consent" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.
(Windows) C:\opt\shibboleth-idp> bin\module.bat -t idp.intercept.Consent || bin\module.bat -e idp.intercept.Consent (Other) $ bin/module.sh -t idp.intercept.Consent || bin/module.sh -e idp.intercept.Consent
Attribute Release Consent
Attribute release consent requires users to accept the release of attributes to Service Providers during front-channel authentication profiles that include attribute data in the response.
Note the "front-channel" caveat above. The default configuration prevents the consent intercept from imposing itself if it detects that attributes would not be included in the response and would instead perhaps be accessed via a back-channel query. This is true by default with SAML 1.1, for example.
The system does support the limited application of prior consent decisions by a user to the data released in a back-channel query, though this is disabled by default.
If you intend to use the consent feature and do not enable this support, it is your responsibility to ensure that attributes would not be accessible to the same relying parties via query or some other means. The system will not prevent this from happening if you leave features enabled that would allow this to happen.
Users are prompted to consent to attribute release :
on initial access to service provider resources
on release of an attribute to which consent has not been previously given
when an attribute previously consented to is no longer released
(optionally) when the value of an attribute previously consented to changes, see ConsentConfiguration#Attribute Release Value Comparison.
Attribute release consent is enabled for profiles that do user authentication via the postAuthenticationFlows property in conf/relying-party.xml.
Default relying party configuration
<bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
<property name="profileConfigurations">
<list>
<!-- SAML 1.1 and SAML 2.0 AttributeQuery are disabled by default. -->
<!--
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" />
<ref bean="SAML1.AttributeQuery" />
<ref bean="SAML1.ArtifactResolution" />
-->
<bean parent="SAML2.SSO" p:postAuthenticationFlows="attribute-release" />
<ref bean="SAML2.ECP" />
<ref bean="SAML2.Logout" />
<!--
<ref bean="SAML2.AttributeQuery" />
-->
<ref bean="SAML2.ArtifactResolution" />
</list>
</property>
</bean>
Terms Of Use Consent
Consent to terms of use is not enabled by default. To enable it, you will need to :
Configure terms of use message(s) to suit your needs.
Enable the terms of use intercept flow for the cases it should appear.
Configuring Messages
The "terms" are managed as Spring messages via the messages/messages.properties file (or localized versions of it) (see ConsentConfiguration#Messages).
The title and message of the terms of use page displayed to users is derived using the bean named shibboleth.consent.terms-of-use.Key, which defaults to the relying party ID. For example:
https\://sp.example.org = sp-example-org sp-example-org.title = Example Terms of Use sp-example-org.text = This is an example Terms of Use
You may add additional terms of use messages and web page titles specific to relying parties using this mechanism. Each key is mapped to a specific prefix used in the corresponding pair of message properties.
Customizing the Mapping of Relying Party to Terms of Use Message and Title
To customize the mapping of relying party to terms of use message and title, you override the shibboleth.consent.terms-of-use.Key bean in conf/intercept/consent-intercept-config.xml. The following example use a utility class available in the Guava library to turn a map into a compliant Function that is composed with a call to lookup the relying party ID. The example isn't all that interesting, but it illustrates the indirection. You can map multiple SPs to a single vale, and so forth.
<bean id="shibboleth.consent.terms-of-use.Key" parent="shibboleth.Functions.Compose">
<constructor-arg name="g">
<bean class="com.google.common.base.Functions" factory-method="forMap" c:defaultValue="terms-of-use">
<constructor-arg name="map">
<map>
<entry key="https://sp.example.org/shibboleth" value="example-terms" />
<entry key="https://other.example.org/shibboleth" value="example-terms" />
</map>
</constructor-arg>
</bean>
</constructor-arg>
<constructor-arg name="f">
<ref bean="shibboleth.RelyingPartyIdLookup.Simple" />
</constructor-arg>
</bean>
Using One Terms of Use Message for Every Relying Party
To configure a single terms of use page for every relying party, override the bean named shibboleth.consent.terms-of-use.Key in conf/intercept/consent-intercept-config.xml:
<bean id="shibboleth.consent.terms-of-use.Key" parent="shibboleth.Functions.Constant"> <constructor-arg value="my-terms"/> </bean>
and define the terms of use message and title in messages/messages.properties:
my-terms = my-tou my-tou.title = Example Terms of Use my-tou.text = This is an example Terms of Use
Enabling Terms Of Use Intercept Flow
To enable the flow, you would add terms-of-use to the postAuthenticationFlows profile setting in conf/relying-party.xml.
For example for use with SAML 2.0 requests, replace:
<bean parent="SAML2.SSO" p:postAuthenticationFlows="attribute-release" />
with :
<bean parent="SAML2.SSO" p:postAuthenticationFlows="#{ {'terms-of-use', 'attribute-release'} }" />
Rejection of Terms of Use Consent
When a user rejects consent to terms of use, a TermsRejected event will be signaled. The text presented to the user may be modified via standard ErrorHandlingConfiguration and via messages/messages.properties (see ConsentConfiguration#Messages).
User Interface
The user interface for the attribute release and terms of use consent flows are implemented as Velocity templates, views/intercept/attribute-release.vm and views/intercept/terms-of-use.vm respectively.
The templates can be customized in a similar way to the login pages and other views.
Messages displayed to users may be localized in the standard Spring way, for example, by providing messages/messages_de.properties. Some translations are already included in the distribution.
Revoking Consent
Users may revoke previous consent choices by selecting a checkbox on the login page (views/login.vm).
The text of the checkbox displayed on the login page is set by the idp.attribute-release.revoke message ID, overridable in messages/messages.properties.
Storage
In order to remember users' consent choices and to prompt users to consent to attribute release if attributes change, users' consent choices must be persisted by a storage service. User consent may be stored either client-side (cookies or HTML5 Local Storage) or server-side (database). The default is to store consent client-side via Local Storage, not out of any particular belief that it makes sense, but because it allows easy deployment of the feature for demonstration.
The storage service used to store consent is configured by the idp.consent.StorageService property in conf/idp.properties
See StorageConfiguration for more on the configuration of various approaches to storage.
Auditing
By default, consent audit logs are written to logs/idp-consent-audit.log as defined in conf/logback.xml.
The format of consent audit logs are defined by the shibboleth.consent.attribute-release.AuditFormattingMap and shibboleth.consent.terms-of-use.AuditFormattingMap beans in conf/intercept/consent-intercept-config.xml
See ConsentAuditFields and also the AuditLoggingConfiguration for additional fields available without additional work.
Activation Conditions
Consent flows (like any other interceptor flow) may be run conditionally based on ActivationConditions.
Because the attribute release flow has an internal condition attached already, customizing the condition for it requires combining the default activation condition with the custom activation condition. By default, the attribute release flow is not activated if both (1) attributes are not pushed and (2) per attribute consent is enabled.
The terms of use flow does not have a default activation condition.
Example
Consent flows may be activated based on the presence (or absence) of a particular attribute or value for a user.
The following example activates the attribute release flow if an attribute is present by combining the default activation condition with a custom condition:
Reference
V3 Compatibility
An IdP can be upgraded to the current version without any changes, but there are issues around the sorting and hashing of attribute values that may cause unexpected re-prompting for consent even when the actual values of an attribute haven't changed.
V4.1 resolves this bug going forward but cannot correct the issue retroactively.
Prior to V4.1, avoiding use of consent with multi-valued attributes is one workaround.