Consent and preference management

The consent and preference management module enables you to define customized consents, specify consent workflows, and register user consents.

Consent is an important concept in the protection of natural persons with regard to the processing of personal data. The specific rules that need to be followed in Europe and for EU citizen data are determined by the General Data Protection Regulation (GDPR). The rules state among that the controller (such as a company offering its services) must be able to demonstrate that the user consented to the processing of their personal data, which means that the controller must register and keep track of its users' consents.

Examples of consents

"I agree with the general terms and conditions of company A."
"I agree that company A, using services provided by company Y, uses my email address to send me a monthly newsletter."

The OneWelcome Identity Platform distinguishes between two types of consents:

Document consents give consent to a document and are often required to gain access to a company's service.
Attribute consents give consent to the use of personal data (referred to as attributes) for a specific purpose. They are always optional and indicate a preference of the user.

To help with consent and preference management, the OneWelcome Identity Platform provides a consent management API that you use to:

Define customized document and attribute consents.
Register user consents and log each action with regard to these consents.

The consent management API enables tenants to set up consent definitions. Each definition has one or more versions, which contain one or more documents. There is a distinction between objects for document consents and attribute consents. An AttributeConsentDocument can also be referred to as a policy.

consent information model

Object	Unique identifier	Example	Description
ConsentDefinition	`name`	terms-and-conditions	The (Attribute)`ConsentDefinition` is a master data object that groups all information about one logical consent. For documents, it indicates whether the consent is mandatory for use of the tenant's services. Each `ConsentDefinition` can have one or more `ConsentVersions`.
ConsentVersion	`version`	2023.1	The (Attribute)`ConsentVersion` groups minor revisions of (Attribute)`ConsentDocuments` for multiple locales. This object also determines the opt-in method for registering consent to these documents and can contain an `endOfLife` property that specifies when these registered consents expire.
ConsentDocument	`version` `language` (`listOfAttributes`)	2023.1.1 nl-BE (email)	The (Attribute)`ConsentDocument` represents one specific `version` of the actual document (stored in the `url`) or policy (`processingPurpose`) that must be agreed upon by users of a specific locale (`language`) to use the tenant's specified service. The `effectiveDate` specifies the moment in time when the (Attribute)`ConsentDocument` can obtain the Document states. Policies for attribute consents are further identified by the set of personal data (`listOfAttributes`) for which use consent is requested (such as email,firstName,phoneNumber). As a result, an `AttributeConsentVersion` can contain multiple policies with the same processing purpose (for example, newsletter), but with different options for the data that the user shares. Policies also store the `legalBasis` for processing the user's data.

Modification rules

An (Attribute)ConsentDocument can be modified until its effectiveDate. Documents with status:draft can always be modified.
An (Attribute)ConsentVersion, and therefore the associated optInConfig, can be modified as long as all of its ConsentDocuments can be modified.
An endOfLife can be added to a ConsentVersion at any time. After it's added, it can be modified until its startDate.
An (Attribute)ConsentDefinition can be modified as long as all of its ConsentVersions can be modified.

optInConfig property

The opt-in configuration specifies how to process new opt-ins, that is, requests to register a user's consent. There is currently one opt-in method:

Direct opt-in: The request to register a consent is processed immediately.

	User action	Request	Back-end action
1	The user clicks the I agree button.	The client requests to register the user's consent: Register my UserConsent	The user's consent is processed (see Registration of User Consents).

endOfLife property

To regulate the transition to a new ConsentVersion, an endOfLife can be added to the previous ConsentVersion. This property indicates when the transition starts (startDate) and when documents from the previous version are no longer valid (endDate). The endOfLife also specifies the duration of the period a user gets to agree to the new version (gracePeriod). This grace period starts at the moment the user receives the first invitation to accept the new ConsentDocument.

The actual grace period for a specific user never extends past the endDate of the endOfLife (see user B in the example of required consents).

Updating consents

When consent documents require an update, new (Attribute)ConsentDocuments and, for major updates, new (Attribute)ConsentVersions must be created. This results in multiple documents for one locale within the same (Attribute)ConsentDefinition. A set of logical rules determines the state of each of these documents and the action which might be required from the user.

Document states

(Attribute)ConsentDocuments have a status property that indicates whether the document is a draft or is released (active). Documents also have a lifecycle status that is determined by a set of conditions (see table). For each locale in an (Attribute)ConsentDefinition, there is one active document, that is, the document that should currently be offered to (new) users. However, user consents to all currently valid documents grant access to the tenant's service. In contrast, user consents for archived documents are no longer accepted.

Lifecycle status	Requirements
valid	The `effectiveDate` lies in the past. If specified, the `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the future. The `status` is not `draft`.
active	The document's `effectiveDate` is the most recent across all valid (Attribute)ConsentDocuments for the document's locale (`language`) that belong to the same (Attribute)ConsentDefinition.
archived	The `endOfLife.endDate` of the (Attribute)ConsentVersion to which the document belongs, lies in the past.

In practice, there are three types of valid documents:

The active document.
Documents located in the same ConsentVersion as the active one (in other words, the active document is only a minor update).
Documents belonging to a ConsentVersion that is currently in its endOflife period (between startDate and endDate).

Managing updates

When (Attribute)ConsentDocuments reach their effectiveDate, they can no longer be modified (unless it is a draft). A new (Attribute)ConsentDocument must be created to apply minor (such as formulation) or major (content) changes. The below scheme explains how to manage these updates.

Update	Configuration	User action required?
minor	(Attribute)ConsentDocuments with minor differences should be located in the same ConsentVersion. Documents for different locales do not need a simultaneous update.	No. The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user can continue using the service.
major	A new (Attribute)ConsentDocument must be created for each locale in a new ConsentVersion.	Yes. Every user must consent to a new (Attribute)ConsentDocument. The transition to the new (Attribute)ConsentVersion makes use of a grace period. During the grace period: The (Attribute)ConsentDocument for which the user already gave their consent, is still valid. The user may continue using the service, but should be reminded of the need to renew their consent. After the grace period: The user's access to the service will be denied until the user agrees to the currently active (Attribute)ConsentDocument.

Warning

The grace period is defined in the endOfLife of the ConsentVersion to which the previously accepted (Attribute)ConsentDocument belongs.

Attribute example

The minimal set of attributes required to subscribe to a newsletter change from email to email,fullName. The policy with listOfAttributes:email is thus no longer valid. Because this is a major change, a new AttributeConsentVersion must be created and all AttributeConsentDocuments that are (still) applicable must be (re)created. In addition, an endOfLife must be specified for the previous AttributeConsentVersion.

Example of required consents

consent example

The above image shows an example where user consents are required before, during, and after the endOfLife period associated with the ConsentVersion Green. All users in the example request a Spanish ConsentDocument.

Users A, B, and C already gave their consent for ConsentDocument G1 and are only invited to agree with a new document after startDate.
New users W and X are offered a different ConsentDocument due to the timing of their requests in relation to the effectiveDate of ConsentDocument G3.
New user Y (in contrast to new user Z) still receives a ConsentDocument from the Green ConsentVersion, since the recently created Blue ConsentVersion does not yet have an effective ConsentDocument.
User A gets the full grace period, while user B does not because the remaining time to endDate is less than gracePeriod. User C requests access after endDate and receives no grace period.

Good practices for ConsentVersion

The transition to a new ConsentVersion is most efficient when following a few good practices:

The new ConsentVersion should be ready to be used at the endOfLife.startDate of the previous ConsentVersion:
- ConsentDocuments should be provided in (at least) the same locales as provided in the previous ConsentVersion (to avoid the absence of a valid document for a specific language).
- The first ConsentDocument(s) in the new ConsentVersion should have an EffectiveDate equal to the endOfLife.startDate of the previous ConsentVersion.
From endOfLife.startDate onwards, no new ConsentDocuments should be added to the ConsentVersion associated to the endOfLife.

The consent management API handles the actual registration of user consents. When user consents are processed, the OneWelcome Identity Platform stores two types of information:

A UserConsent object contains the user's identifier and the properties needed to uniquely identify an (Attribute)ConsentDocument. These objects are used to check whether a user gave their consent for a specific document.
An audit-log (RegisterEvent) stores all user requests and actions for audit purposes.

alt_text

An (Attribute)ConsentDocument is uniquely identified by four properties:

The (Attribute)ConsentDefinition's name
The (Attribute)ConsentVersion's version
The (Attribute)ConsentDocument's version and language

Conceptual example of audit-log

Time	Consent	User	Action
`2019-11-10T23:00:49Z`	terms_conditions_2019	John Doe	Registered via direct opt-in method.
`2020-01-10T04:50:02Z`	daily_newsletter	Jane Doe	Token requested for double opt-in method.
`2020-01-10T04:55:05Z`	daily_newsletter	Jane Doe	Registered via double opt-in method.
`2020-01-10T20:03:00Z`	terms_conditions_2020	John Doe	Registered via direct opt-in method.
`2020-01-10T20:10:32Z`	terms_conditions_2020	John Doe	Revoked.

Endpoints overview

The following diagram shows the configuration and consent management endpoints for document consents. For attribute consents, a similar set of configuration endpoints is available.

endpoints overview

Suggest A Change