Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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.

{ "jdoe:https://sp1.example.org":{ "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\"}]", "x":1479847202110 }, "jdoe:https://sp2.example.org":{ "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\"}]", "x":1479847206825 }, "jdoe:https://sp3.example.org":{ "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\",\"appr\":false}]", "x":1479847566214 }, "jdoe:_key_idx":{ "v":"[\"jdoe:https://sp1.example.org\",\"jdoe:https://sp2.example.org\",\"jdoe:https://sp3.example.org\"]" } }

Localtabgroup
tabStyleflat

Localtab live
titleLimiting Records

While the default client-side storage solution is HTML Local Storage, it is possible to use cookies. Because cookies provide limited storage capability, the number of stored consent records is also very limited. By default, for client-side storage via cookies, the maximum number of stored consent records is 10. Depending on the number of attributes released and whether released attribute values are compared, the default limit of 10 may be increased. It is not clear what a reasonable default value should be, but it may be significantly higher. We were conservative with the default.

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

Localtab live
titleRetention in V4.0

A map is supported to store numbers which refer to attribute IDs in order to reduce the size of consent storage records if desired. The default mapping of attribute IDs to numbers is defined by the shibboleth.consent.DefaultAttributeSymbolics bean, internally to the system.

Additional mappings may be added to the shibboleth.consent.AttributeSymbolics bean in conf/intercept/consent-intercept-config.xml

Localtab live
titleRetention in V4.1

The default lifetime for consent storage records is 1 year, and may be configured via idp.consent.storageRecordLifetime in conf/idp.properties. When consent storage records expire, they will no longer by visible via the storage service. Actual timing of deletion is specific to the storage implementation.

Localtab live
titleRecord Format


Localtab
titleRecord Format
Note

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, like all StorageRecords.

The (default) storage key for consent records is a concatenation of the user key and the relying party ID, though this is customizeable.

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.

Code Block
languagejs
collapsetrue
Code Block
{  
   "jdoe:https://sp1.example.org":{  
      "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\"}]",
      "x":1479847202110
   },
   "jdoe:https://sp2.example.org":{  
      "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\"}]",
      "x":1479847206825
   },
   "jdoe:https://sp3.example.org":{  
      "v":"[{\"id\":307},{\"id\":\"mail\"},{\"id\":\"uid\",\"appr\":false}]",
      "x":1479847566214
   },
   "jdoe:_key_idx":{  
      "v":"[\"jdoe:https://sp1.example.org\",\"jdoe:https://sp2.example.org\",\"jdoe:https://sp3.example.org\"]"
   }
}



Auditing

By default, consent audit logs are written to logs/idp-consent-audit.log as defined in conf/logback.xml.

...

The following example activates the attribute release flow if an attribute is present by combining the default activation condition with a custom condition:

Localtabgroup

Localtab-live
titleV4.0


Code Block
titleExample activation conditon in conf/intercept/profile-intercept.xml
collapsetrue
<bean id="intercept/attribute-release" parent="shibboleth.consent.AttributeReleaseFlow"
    p:activationCondition-ref="MyCondition" />

<bean id="MyCondition" parent="shibboleth.Conditions.AND">
    <constructor-arg>
        <list>
            <!-- The default condition from system/conf/profile-intercept-system.xml -->
            <bean parent="shibboleth.Conditions.OR">
                <constructor-arg>
                    <bean parent="shibboleth.Conditions.NOT">
                        <constructor-arg value="%{idp.consent.allowPerAttribute:false}" />
                    </bean>
                </constructor-arg>
                <constructor-arg>
                    <bean class="net.shibboleth.idp.saml.profile.config.logic.IncludeAttributeStatementPredicate" />
                </constructor-arg>
            </bean>
            <!-- A custom condition -->
            <bean class="net.shibboleth.idp.profile.logic.SimpleAttributePredicate" p:useUnfilteredAttributes="true">
                <property name="attributeValueMap">
                    <map>
                        <entry key="eppn">
                            <list>
                                <value>*</value>
                            </list>
                        </entry>
                    </map>
                </property>
            </bean>
        </list>
    </constructor-arg>
</bean>

Localtab-live
activetrue
titleV4.1+

To combine your own condition with the system default, you would define your bean in, e.g., conf/global.xml:

Code Block
languagexml
titleCustom condition bean in global.xml
collapsetrue
<bean id="example.AttributeReleaseCondition"
		class="net.shibboleth.idp.profile.logic.SimpleAttributePredicate"
		p:useUnfilteredAttributes="true">
    <property name="attributeValueMap">
        <map>
            <entry key="eppn">
                <list>
                    <value>*</value>
                </list>
            </entry>
        </map>
    </property>
</bean>

Then define the property idp.consent.attribute-release.activationCondition to example.AttributeReleaseCondition (your custom bean's ID) to install it and it will be combined with the system's default condition for you.


Reference

true

Localtabgroup

Localtab

active
-live
titleBeans

Beans defined, or expected to be defined, in conf/intercept/consent-intercept-config.xml :

Bean ID / TypeFunction

shibboleth.consent.terms-of-use.Key

Function<ProfileRequestContext,String>

Function which returns the key used to (1) lookup terms of use messages and when concatenated with the user key to (2) lookup storage records, defaults to the relying party ID

shibboleth.consent.attribute-release.rp.Key 4.1

Function<ProfileRequestContext,String>

Function which returns the key which is concatenated with the user key to lookup storage records, defaults to the relying party ID.

Overriding this bean allows a single consent record to cover multiple Relying Parties.

shibboleth.consent.attribute-release.PromptedAttributeIDs 4.1

shibboleth.consent.attribute-release.WhitelistedAttributeIDs
(DEPRECATED)

Set<String>

List of attribute IDs for which consent should be obtained

shibboleth.consent.attribute-release.IgnoredAttributeIDs 4.1

shibboleth.consent.attribute-release.BlacklistedAttributeIDs
(DEPRECATED)

Set<String>

List of attribute IDs for which consent should not be obtained

shibboleth.consent.attribute-release.MatchExpression

Pattern

Regular expression matching the attribute IDs for which consent should be obtained

shibboleth.consent.attribute-release.AuditFormattingMap

Map<String,List<String>>

Attribute release audit log format, maps logger name to audit fields

shibboleth.consent.terms-of-use.AuditFormattingMap

Map<String,List<String>>

Terms of use audit log format, maps logger name to audit fields

shibboleth.consent.PreConsentAuditExtractors

Map<String,Function<ProfileRequestContext,Object>>

Audit fields in addition to the default fields populated at the start of the consent flow

shibboleth.consent.ConsentAuditExtractors

Map<String,Function<ProfileRequestContext,Object>>

Audit fields in addition to the default fields used when writing the audit log

shibboleth.consent.AttributeSymbolics

Map<String>

Limits storage record size by mapping attribute IDs to numbers

shibboleth.consent.DefaultAttributeSymbolics                             

Map<String>

Default map that can be used as a parent bean for the bean above to merge in additional values

shibboleth.consent.AttributeQuery.Condition

Predicate<ProfileRequestContext>

Condition that determines whether to apply prior consent decisions in server-side storage to back-channel query requests. Defaults to FALSE.


Localtab-live
activetrue
titleProperties

Relevant properties defined in conf/idp.properties :

PropertyTypeDefaultFunction

idp.consent.StorageService                                                    

Bean ID

shibboleth.ClientPersistentStorageService

Name of storage service used to store users' consent choices

idp.consent.userStorageKey

Bean ID

shibboleth.consent.PrincipalConsentStorageKey

DEPRECATED

Name of function used to return the String storage key representing a user, defaults to the principal name

idp.consent.attribute-release.userStorageKeyBean ID

shibboleth.consent.PrincipalConsentStorageKey

Replacement for "idp.consent.userStorageKey" specific to attribute-release flow
idp.consent.terms-of-use.userStorageKeyBean ID

shibboleth.consent.PrincipalConsentStorageKey

Replacement for "idp.consent.userStorageKey" specific to terms-of-use flow

idp.consent.userStorageKeyAttribute

Stringuid

DEPRECATED

Attribute whose value is the storage key representing a user, only used when idp.consent.userStorageKey = shibboleth.consent.AttributeConsentStorageKey

idp.consent.attribute-release.userStorageKeyAttributeStringuidReplacement for "idp.consent.userStorageKeyAttribute" specific to attribute-release flow
idp.consent.terms-of-use.userStorageKeyAttributeStringuidReplacement for "idp.consent.userStorageKeyAttribute" specific to terms-of-use flow
idp.consent.attribute-release.activationCondition 4.1Bean IDshibboleth.Conditions.TRUEOptional condition to apply to control activation of attribute-release flow along with system default behavior
idp.consent.terms-of-use.activationCondition 4.1Bean IDshibboleth.Conditions.TRUEOptional condition to apply to control activation of terms-of-use flow

idp.consent.allowDoNotRemember

Booleantrue

Whether not remembering/storing consent is allowed

idp.consent.allowGlobal

Booleantrue

Whether consent to any attribute and to any relying party is allowed

idp.consent.allowPerAttribute

Booleanfalse

Whether per-attribute consent is allowed

idp.consent.compareValues

Booleanfalse

Whether attribute values and terms of use text are stored and compared for equality

idp.consent.maxStoredRecords

Integer10

Maximum number of records stored when using space-limited storage (e.g. cookies), 0 = no limit

idp.consent.expandedMaxStoredRecords

Integer0

Maximum number of records stored when using larger/server-side storage, 0 = no limit

idp.consent.storageRecordLifetimeDuration P1Y4.0 Infinite4.1+

Time in milliseconds to expire consent storage records


Localtab-live

id

titleMessages

title

Anchor
Messages
Messages

Relevant messages overridable via messages/messages.properties:

MessageText

no-release.title

Title of error page displayed when attribute release consent is rejected

no-release.message

Text of error page displayed when attribute release consent is rejected

no-terms.title

Title of error page displayed when terms of use consent is rejected

no-terms.message

Text of error page displayed when terms of use consent is rejected



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.

...