The Single Consent service enables easily sharing a user's consent or rejection of cookies across different websites. This ensures a seamless user experience by remembering a user's preferences without repeatedly asking for consent.

1. Cookie Consent: When you visit a Single Consent enabled website, you may encounter a pop-up or banner asking for your consent to use cookies.

2. Unique ID: If you respond, your consent to (or refusal of) cookies is then submitted to the Single Consent service, which assigns you a randomly generated unique ID. This ID does not contain any personal information about you.

3. Central Database: Your consent data is then associated with your unique ID and stored in the central Single Consent database.

4. Javascript Client: The website receives your unique ID via the Single Consent client, a small piece of Javascript code embedded in the website.

5. Link Decoration: The client automatically appends your unique ID as a parameter to the links you click on which lead to other Single Consent enabled websites.

6. Consent Lookup: When a Single Consent enabled website receives a request with a URL containing your unique ID, it uses this ID to look up your consent data in the central database. Using this data, the website can respect your preferences and avoid asking for consent again.

7. Revoking Consent: If you change your mind and refuse (or grant) consent to use cookies, you can modify your cookie settings on the current website and it will submit the updated data to the central database, making all other Single Consent enabled websites aware of your changed preferences.

8. ID Cookie: The Single Consent client also stores your unique ID in a cookie for the current website, so that if you return to the site without clicking a link (eg via a bookmark, or typing in the URL to the address bar in your browser), your consent preferences will be remembered.

To make use of the Single Consent service on your website, please see the Single Consent client Quick Start documentation

• DATABASE_URL (default is postgresql+asyncpg:https://localhost:5432/consent_api)
• ENV (default is development)
• PORT (default is 8000)
• SECRET_KEY (default is randomly generated)
• You can configure the number of web server worker processes with the WEB_CONCURRENCY environment variable (default is 1)

You can run all the services without setup needed:

make docker-build
docker compose up

When running docker commands, you will need a few extra environment variables.

It's easiest to use Direnv to load the environment.

Copy .envrc.template to .envrc and load it with direnv:

direnv allow

Those variables will be used by both docker-compose and the Makefile.

Additionally, we recommend hooking direnv with your shell, for automatic environment loading.

To run the API locally:

make install
make run

It will install poetry, our python dependencies manager, as well as the project dependencies.

Run unit tests with the following command:

make test

You will need to build a Docker image to run the tests against, using the following command:

make docker-build

You also need to have the Chrome Docker image already on your system, which you can do with the following command:

docker pull selenoid/chrome:110.0

Note Currently, Selenoid does not provide a Chrome image that works on Apple M1 hosts. As a workaround, you can use a third-party Chromium image:

docker pull sskorol/selenoid_chromium_vnc:100.0

Then set the following environment variable:

export SPLINTER_REMOTE_BROWSER_VERSION=sskorol/selenoid_chromium_vnc:100.0

The easiest way to run the end-to-end tests is in Docker Compose using the following command:

make test-end-to-end-docker

To run end-to-end tests you will need Chrome or Firefox installed. Specify which you want to use for running tests by setting the SELENIUM_DRIVER environment variable (defaults to chrome), eg:

export SELENIUM_DRIVER=firefox

You also need a running instance of the Consent API and two instances of webapps which have the Single Consent client installed.

Note For convenience, a dummy service is included in the API. You can run two more instances of the Consent API on different port numbers to act as dummy services:

CONSENT_API_ORIGIN=http:https://localho.st:8000 OTHER_SERVICE_ORIGIN=http:https://localho.st:8082 PORT=8081 make run

and

CONSENT_API_ORIGIN=http:https://localho.st:8000 PORT=8082 make run

The tests expect to find these available at the following URLs:

Due to CORS restrictions, the tests will fail if the URL domain is localhost or 127.0.01, so a workaround is to use localho.st which resolves to 127.0.0.1.

Run the tests with the following command:

make test-end-to-end

This project uses Github Flow.

• main branch is always deployable
• To work on something new, create a descriptively named branch off main
• Commit to that branch locally and regularly push to the same named branch on the server (Github)
• When you need feedback or help, or you think the branch is ready to merge, rebase off main and open a pull request
• After the pull request has been reviewed and automated checks have passed, you can merge to main
• Commits to main are automatically built, deployed and tested in the Integration environment.

New features are developed on feature branches, which must be rebased on the main branch and squashed before merging to main.

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and availabe under the terms of the Open Government 3.0 licence.

The Single Consent service is maintained by a team at Government Digital Service. If you want to know more about the service, please email the Data Infrastructure team or get in touch with them on Slack.

Team email: [email protected]

You can also contact the maintainers of this repository via email:

• Guilhem Forey: [email protected]