Installing and configuring the consent module

The consent module is implemented as an Authentication Processing Filter. That means it can be configured in the global config.php file or the SP remote or IdP hosted metadata.

It is recommended to run the consent module at the IdP, and configure the filter to run after all attribute mangling filters is completed, to show the user the exact same attributes that are sent to the SP.

Read more about processing filters in simpleSAMLphp

1 Configure the user ID

In order to generate the privacy preserving hashes in the consent module, you need to name one attribute that always is available and that is unique to all users. An example of such an attribute is eduPersonPrincipalName.

In your saml20-idp-hosted.php add the name of the user ID attribute:

'userid.attribute' => 'uid',

If the attribute defined above is not available for a user, an error message will be shown, and the user will not be allowed through the filter. So make sure that you select an attribute that is available to all users.

2 The first step: consent module with cookie as storage

We reccomend to try to enable the consent module with cookie as a storage, before setting up a database.

To enable the consent module, touch an enable file, in the consent module:

touch modules/consent/enable

Then edit config.php and look for the authproc.idp configuration. Uncomment the followig filter configuration:

90 => array(
    'class'     => 'consent:Consent', 
    'store'     => 'consent:Cookie', 
    'focus'     => 'yes', 
    'checked'   => TRUE
),

Then login through an SP and make sure that you are asked for consent.

3 Setting up a database

Here is the initialization SQL script for PostgreSQL:

CREATE TABLE consent (
    consent_date TIMESTAMP NOT NULL,
    usage_date TIMESTAMP NOT NULL,
    hashed_user_id VARCHAR(80) NOT NULL,
    service_id VARCHAR(255) NOT NULL,
    attribute VARCHAR(80) NOT NULL,
    UNIQUE (hashed_user_id, service_id)
);

4 Configuring the processing filter

4.1 Options

The following options can be used when configuring the Consent module

ìncludeValues: Boolean value that indicate whether the values of the attributes should be used in calculating the unique hashes that identifies the consent. If includeValues is set and the value of an attribute changes, then the consent becomes invalid. This option is optional and defaults to FALSE.
checked: Boolean value that indicate whether the "Remember" consent checkbox is checkd by default. This option is optional and defaults to FALSE.
focus: Indicates whether the "Yes" or "No" button is in fucus by default. This option is optional and can take the value 'yes' or 'no' as strings. If omitted neither will recive focus.
store: Configuration of the Consent store. See seperate section on setting up consent using different storage methods.
hiddenAttributes: Whether the value of the attributes should be hidden. Set to an array of the attributes that should have it value hidden. Default behaviour is that all attribute values are shown

4.2 Options set elswhere

The following options can be set in otherplaces

privacypolicy: This is an absolute URL for where an user can find a privacy policy for SP. If set, this will be shown on the consent page. %SPENTITYID% in the URL will be replaced with the entityID of the service provider.; This option can be set in SP-remote metadata and in IdP-hosted metadata. The entry in the SP-remote metadata overrides the option in the IdP-hosted metadata.
consent.disable: Disable consent for a set of services. See section Disabling consent
userid.attribute: Unique identifier that is released for all users. See section Configure the user ID.

Example config using PostgreSQL database:

90 => array(
    'class'     => 'consent:Consent', 
    'store'     => array(
        'consent:Database', 
        'dsn' => 'pgsql:host=sql.uninett.no;dbname=andreas_consent',
        'username' => 'simplesaml',
        'password' => 'sdfsdf',
    ),
    'focus'     => 'yes', 
    'checked'   => TRUE
),

5 Disabling consent

It is possible to disable consent for a given service. You can add an option in the matadata on the IdP, that will disable consent for det given service. Add 'consent.disable' array option and enter the entityids of the services, that you do not want consent for.

Example:

'consent.disable' => array(
    'sp.example.com',
    'sp2.example.com',
    ...
),