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
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.
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/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 :
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 :
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.
"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.|
Attribute Release Value Comparison
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
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.
By default, users are prompted to consent to release all attributes except for the blacklisted attribute IDs
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|
|Attribute IDs that users should be prompted to consent to|
|Attribute IDs that users should not be prompted to consent to|
|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 :
Attribute Display Order List 3.2.1
To customize the order in which attributes are displayed, define a bean with ID
shibboleth.consent.attribute-release.AttributeDisplayOrder in conf/intercept/consent-intercept-config.xml representing the desired order. The values of the list are attribute IDs.
The following example displays the
Attribute Display Order Comparator
For advanced customization of the attribute display order, a custom Comparator may be provided. Define a bean with ID
shibboleth.consent.attribute-release.AttributeIDComparator in conf/intercept/consent-intercept-config.xml which implements
Comparator<String>. For example :
Attribute Display Name and Values
TODO : Customization
Rejection of Attribute Release Consent
When a user rejects consent to attribute release, an
AttributeReleaseRejected error page will be displayed. The text presented to the user may be modified via messages/messages.properties, see Messages.
shibboleth.consent.terms-of-use.Key, which defaults to the relying party ID. For example :
shibboleth.consent.terms-of-use.Key in conf/intercept/consent-intercept-config.xml :
terms-of-use to the post authentication flows in conf/relying-party.xml.
For example for use with SAML 2.0 requests, replace :
TermsRejected error page will be displayed. The text presented to the user may be modified via messages/messages.properties, see Messages.
The velocity template can be customized in a similar way to the Login pages.
Messages displayed to users may be localized in the standard Spring way, for example, by providing messages/messages_de.properties.
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 property, overridable in messages/messages.properties.
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 3.2) or server-side (database). The default is to store consent client-side via cookies.
The storage service used to store consent is configured by the
idp.consent.StorageService property in conf/idp.properties.
Limiting the Number of Stored Consent Records
If server-side storage is used, the number of stored consent records should probably be unlimited, represented by a limit of -1 or 0.
The maximum number of stored consent records is configured via the
idp.consent.maxStoredRecords property in conf/idp.properties.
Limiting Storage Size via Symbolics
The default mapping of attribute IDs to numbers is defined by the
shibboleth.consent.DefaultAttributeSymbolics bean in system/conf/profile-intercept-system.xml.
Additional mappings of attribute IDs to numbers may be added to the
shibboleth.consent.AttributeSymbolics bean in conf/intercept/consent-intercept-config.xml.
Storage Record Lifetime
The default lifetime for consent storage records is 1 year, and may be configured via the
idp.consent.storageRecordLifetime in conf/idp.properties. When consent storage records expire, they will be deleted by the storage service.
Storage Record Format
The below information is provided for reference but is not a public interface of the system. You may not depend on the format remaining unchanged across even patch releases.
Consent storage records consist of a key and value, similar to other StorageRecords.
The storage key for consent records is a concatenation of the user key and the relying party ID.
The storage value for consent records is the JSON serialized form of a Map of Consent objects.
A per-user index is maintained in order to expire or limit the number of stored records.
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.terms-of-use.AuditFormattingMap beans in conf/intercept/consent-intercept-config.xml.
Consent flows (like any other profile intercept flow) may be run conditionally based on activation conditions.
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:
Beans defined in conf/intercept/consent-intercept-config.xml :
|Whitelist of attribute IDs for which consent should be obtained|
|Set<String>||Blacklist of attribute IDs for which consent should not be obtained|
|String||Regular expression matching the attribute IDs for which consent should be obtained|
Attribute release audit log format, maps logger name to audit fields
|Audit fields in addition to the default fields populated at the start of the consent flow|
|Audit fields in addition to the default fields used when writing the audit log|
|Limits storage record size by mapping attribute IDs to numbers|
Relevant properties defined in conf/idp.properties :
|Name of storage service used to store users' consent choices|
DEPRECATED Name of function used to return the String storage key representing a user, defaults to the principal name
|idp.consent.attribute-release.userStorageKey 3.4||Bean ID|
|Replacement for "idp.consent.userStorageKey" specific to attribute-release flow|
|idp.consent.terms-of-use.userStorageKey 3.4||Bean ID|
|Replacement for "idp.consent.userStorageKey" specific to terms-of-use flow|
|String||uid||DEPRECATED Attribute whose value is the String storage key representing a user, only used when idp.consent.userStorageKey = shibboleth.consent.AttributeConsentStorageKey|
|idp.consent.attribute-release.userStorageKeyAttribute 3.4||String||uid||Replacement for "idp.consent.userStorageKeyAttribute" specific to attribute-release flow|
|idp.consent.terms-of-use.userStorageKeyAttribute 3.4||String||uid||Replacement for "idp.consent.userStorageKeyAttribute" specific to terms-of-use flow|
Whether not remembering/storing consent is allowed
Whether consent to any attribute and to any relying party is allowed
Whether per-attribute consent is allowed
Maximum number of records stored when using space-limited storage (e.g. cookies), 0 = no limit
Maximum number of records stored when using larger/server-side storage, 0 = no limit
Time in milliseconds to expire consent storage records
Relevant messages overridable via messages/messages.properties :
|Title of error page displayed when attribute release consent is rejected|
|Text of error page displayed when attribute release consent is rejected|
Velocity templates in views/intercept :
|views/intercept/attribute-release.vm||Default attribute release Velocity template|
Although consent in IdPv3 was modeled after the uApprove and uApproveJP plugins to IdPv2, at this time it is not possible to upgrade consent from IdPv2 to IdPv3 because the storage implementations are not compatible.