Pacem.Mvc.CookiePolicy 0.8.10-euler

Cookie Policy Middleware

About

Pacem.Mvc.CookiePolicy provides a lightweight middleware that helps to filter unconsented cookies according to European (GDPR) policies.

The following paragraphs exemplify the library utilization.

Getting started

Add required services and middlewares.

Like this:

// Program.cs

// services
services.AddPacemCookiePolicy(options => {
    // specify cookie sets and their category, e.g.:
    options.Necessary = ["Pacem/Pacem", Known1stPartyCookieSets.Azure /* ARRAffinity, ARRAffinitySameSite */];
    options.Functional = [Known3rdPartyCookieSets.GoogleYouTube];
    options.Performance = [Known3rdPartyCookieSets.GoogleAnalytics];
    options.Marketing = [Known3rdPartyCookieSets.GoogleAdSense];
});

// middleware
app.UsePacemCookiePolicy();

As you can see, a few (very few) of the most known CookieSets are available out of the box.

A CookieSet is a string formatted like {Provider}/{Product}.
Example: Google/YouTube.
It identifies a manifest (CookieProvider) that groups a set of cookies relevant to the specific Product.

If you need to include some other ones, configure them:

services.AddPacemCookiePolicy(options => {
    // custom cookie set
    options.Necessary = ["MyCompany/WebApp"];
    // ...
}).WithCustomCookieProviders(providerName => {
    if (providerName == "MyCompany")
    {
        // TODO: factory custom cookie provider 
        // with relevant product 'WebApp'...
    }
});

Consent and Revoke

The Provided/Opinionated Way

Requests to the server using the specific headers X-Pacem-CookieConsent and X-Pacem-CookieRevoke are designed to manage cookieset consents and revocations respectively:

Consent:

GET: /.pacem-cookies HTTP/1.1
X-Pacem-CookieConsent: Google/YouTube

Revoke:

GET: /.pacem-cookies HTTP/1.1
X-Pacem-CookieRevoke: Google/YouTube

Any url goes for this purpose. However, /.pacem-cookies is a peculiar path: its response returns the current, up-to-date and json-formatted, cookie configuration.

// example of a response from '/.pacem-cookies'
{
    // all the configured cookie sets to manage, grouped by category
    "managedCookieSets": {
        "necessary":[
            { 
                "provider": "MyCompany",
                "products": [
                    {
                        "name": "MyApp",
                        "set": {
                            "product": "MyApp",
                            "value": "MyCompany/MyApp",
                            "provider": "MyCompany",
                        },
                        "cookies": [
                            {
                                "name": "_mycomp.tracker",
                                "duration": {
                                    "duration": "1 year",
                                    "value": 1,
                                    "unit": "year"
                                },
                                "type": 0 // 0: Cookie, 1: LocalStorage, 2: Pixel
                                "description": "..."
                            },
                            // ...other 'MyApp' cookies
                        ],
                    },
                    // ...other 'MyCompany' products
                ]
            },
            // ...other 'necessary' providers
        ],
        "performance":[
            // ...'performance' providers
        ],
        "functional":[
            // ...'functional' providers
        ],
        "marketing":[
            // ...'marketing' providers
        ],
        "other":[
            // ...'other' providers
        ]
    },
    // all the consented cookie sets
    "consentedCookieSets": ["Pacem/Pacem", "MyCompany/WebApp"],
    // all the consented cookies
    "consentedCookieNames": [".pacem.cookieconsent", "_mycomp.tracker"],
}

Header-valued requests act atomically: each request adds or removes only the specified set of cookies, which can be comma-concatenated if necessary.

The Custom Way

You are free to manage consents and revocations in any less-opinionated way, as long as you lean on the ICookiePolicyService service, which is available among the injected DI services:

public interface ICookiePolicyService
{
    void Consent(CookieSet cookieSet);
    void Revoke(CookieSet cookieSet);
    void RevokeAll();
    IEnumerable<CookieSet> GetConsentedCookieSets();
}

Methods are self-explanatory.

More than a Cookie Guard

Not only this library's middlewares intercept proprietary cookie in responses, they may also help in managing some 3rd party contents.

Google Tag Manager

Strictly relevant to the provided implementation, a convenient TagHelper comes along to safely include Google's TagManager:

<script pacem-google-tag="my-Google-tag-ID" />

This very same TagHelper also injects some utility methods into the DOM. Example:

// JavaScript utility method that pushes path navigation:
/* window.*/Pacem.Utils.GoogleTag.push('/path');
// ...or any other event standard or custom:
/* window.*/Pacem.Utils.GoogleTag.push('event', 'subscribed', { channel: 'Blog 1', userId: 42});
/* window.*/Pacem.Utils.GoogleTag.push({ event: 'event', method: 'subscribed', channel: 'Blog 1', userId: 42});

Google Tag functionalities depend on the given consent provided by the middleware responses.
By default, they are switched off.

Google Tag Manager scripts are added to the page only after the user's consent.