The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 wiki space for current documentation on the supported version.
ConsentConfiguration
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
- 1 Overview
- 2 Attribute Release Consent
- 2.1 Enabling Attribute Release Consent
- 2.2 Disabling Attribute Release Consent
- 2.3 Per Attribute Consent
- 2.4 Attribute Release Consent Duration
- 2.5 Attribute Release Value Comparison
- 2.6 Attribute Display
- 2.7 Attribute Display Order
- 2.8 Attribute Display Name and Values
- 2.9 Rejection of Attribute Release Consent
- 3 Terms Of Use Consent
- 4 User Interface
- 4.1 Customization
- 4.2 Localized Messages
- 4.3 Revoking Consent
- 5 Storage
- 6 Auditing
- 7 Activation Conditions
- 8 Reference
- 8.1 Beans
- 8.2 Properties
- 8.3 Messages
- 8.4 Views
- 9 V2 Compatibility
- 10 Notes
Overview
IdPv3 includes the ability to enforce user consent to attribute release as well as terms of use.
Consent to attribute release is enabled by default in new IdPv3 installations. It is not enabled during upgrades from IdPv2, but will become enabled if the legacy conf/relying-party.xml is replaced with the v3 default configuration.
Consent in IdPv3 was modeled after the uApprove and uApproveJP plugins to IdPv2.
It is not possible to upgrade consent data from uApprove to the IdPv3 implementation because the storage formats are not compatible, and there are no plans at present to provide such a migration path.
Consent is implemented by the intercept/attribute-release and intercept/terms-of-use intercept flows.
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 not currently support the application of consent decisions by a user to the data released in a back-channel query. If you intend to use the consent feature, 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 Attribute Release Value Comparison.
Enabling Attribute Release Consent
Attribute release consent is enabled by default for the SAML 1 and SAML 2 SSO profiles via the postAuthenticationFlows property in conf/relying-party.xml :
Default relying party configuration
<bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
<property name="profileConfigurations">
<list>
<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>Disabling Attribute Release Consent
To disable attribute release consent, remove the attribute-release post authentication flow from the profile configurations in conf/relying-party.xml.
For example, replace :
<bean parent="Shibboleth.SSO" p:postAuthenticationFlows="attribute-release" />
<bean parent="SAML2.SSO" p:postAuthenticationFlows="attribute-release" />with :
<bean parent="Shibboleth.SSO" />
<bean parent="SAML2.SSO" />Per Attribute Consent
To allow users to select the attributes they wish to be released, enable per attribute consent via idp.consent.allowPerAttribute in conf/idp.properties.
Attribute Release Consent Duration
Users may choose from three options when deciding the duration of their consent to attribute release. This functionality was derived from uApproveJP.
The duration options and descriptive text may be customized in messages/messages.properties.
Duration Option | Description |
|---|---|
"Ask me again at next login" | Users will be prompted to consent to attribute release at every log in. This is implemented by not storing consent. Note: Consent is not activated when user attributes are retrieved by an SP via the back-channel (e.g. SAML Attribute Query). Even though a back-channel request technical is not a "login" by the user, some users might misunderstand the implications of choosing this option. |
"Ask me again if information to be provided to this service changes" | The default. Users will be prompted to consent to attribute release if attributes have changed since consent was previously given. Note: Consent is not activated when user attributes are retrieved by an SP via the back-channel (e.g. SAML Attribute Query). |
"Do not ask me again" | Optional. Users will not be prompted to consent to attribute release again. All attributes will be released to any service provider. This was called "global consent" in uApprove. The presence of this option is controlled by idp.consent.allowGlobal. |
By default, users are prompted to consent to attribute release if a "new" attribute is released or if an "old" attribute is no longer released. "New" and "old" in this context indicate whether consent has already been given to an attribute ID regardless of the attribute's values. In other words, by default, users are not prompted to consent to attribute release if an attribute's values change.
To prompt users to consent to attribute release if the values of an attribute have changed, set idp.consent.compareValues to true in conf/idp.properties.
Prompting users to consent to attribute release if an attribute's value changes requires additional storage capability, because the hash of an attribute's values must be stored for comparison. If client-side storage (cookies) are used to store consent, comparing attribute values may reduce the number of records that may be stored. Since a consent record is stored for every Service Provider, this may increase how often users are prompted to consent to attribute release.
Attribute Display
By default, users are prompted to consent to release all attributes except for the blacklisted attribute IDs transientId, persistentId, and eduPersonTargetedID. Blacklisted attributes are released to relying parties but are not displayed to users. A whitelist, blacklist, and match expression determine whether consent should be obtained for an attribute based on the attribute ID.
To prevent an attribute from being displayed, add the attribute ID to the blacklist. If a match expression is defined in addition to a blacklist, make sure that the blacklisted attribute ID does not match the match expression. The match expression overrides the blacklist, consequently a blacklisted attribute will be displayed if it matches the match expression.
Type | Description | Bean in conf/intercept/consent-intercept-config.xml |
|---|---|---|
Whitelist | Attribute IDs that users should be prompted to consent to | shibboleth.consent.attribute-release.WhitelistedAttributeIDs |
Blacklist | Attribute IDs that users should not be prompted to consent to | shibboleth.consent.attribute-release.BlacklistedAttributeIDs |
Regex | Attribute IDs matching a regular expression that users should be prompted to consent to |
The AttributePredicate determines whether consent should be obtained for an attribute.
Attribute Display Order
Attributes are displayed in the natural order of their IDs. Deployers may wish to customize the order in which attributes are displayed to users, in order to present the most relevant or personal attributes first. The order in which attributes are displayed to users may be customized by providing a list of attribute IDs. Attributes not in the list will still be sorted in their natural order, but subsequent to attributes in the list.
Attribute Display Order List 3.2.0
Attributes are displayed in the order defined by the attribute ID whitelist. If the whitelist is empty or attributes are released which are not present in the whitelist, attributes will be ordered according to the natural order of their IDs, usually alphabetically.
The following example displays the eduPersonPrincipalName attribute first and then all other attributes in alphabetic order :