Skip to main content

Tutorial

info

This tutorial doesn’t assume any existing knowledge of the blindnet devkit or even any privacy-related technologies.

The purpose of the following tutorial is to serve as an entry point for the blindnet devkit, by simply walking you through its different components to give you a better understanding of the overall structure and logic.

Doing so, we'll answer the following questions:

  • What is the purpose of the Privacy Computation Engine;
  • How to add Privacy Requests features to your Web page or applications in a snap;
  • How to easily add privacy requests management features to your "back-office" web page or applications;
  • How to automatically update stored data when managing Privacy Requests.
Further Readings

We strongly recommend reading the linked sections of the documentation for more details.

1. Set Up a Privacy Computation Engine

The Privacy Computation Engine is the core of blindnet devkit. It is a simple service you can interact with via a Rest API to create and track your users' Privacy Requests.

Using the Privacy Computation Engine goes into three steps:

  1. Set Up a UID: register and obtain a unique ID for your system;
  2. Configuration: configure the service using its configuration API;
  3. Development: call the Privacy Computation Engine from your registered applications to handle Privacy Requests
System ID

In its current stage of development, the PCE is provided with a preconfigured system ID. As a consequence, step (1) Set Up a UID doesn't need to be addressed for this tutorial.

Pre-requisites

For this tutorial, we'll simply use the privacy-computation-engine code source repository, as it is provided with several tools to help you get started.

To use these tools, you'll first need to install and setup a Java Development Kit, sbt, and docker-compose on your machine.

Quick Install with SDKMAN

Mac OS and Linux users can directly install sbt with the recommended JDK using SDKMAN, with the following commands:

# IF you need to install SDKMAN quickly
curl -s "https://get.sdkman.io" | bash

# install the recommended JDK
sdk install java $(sdk list java | grep -o "\b8\.[0-9]*\.[0-9]*\-tem" | head -1)

# install sbt
sdk install sbt

As indicated in the sbt documentation, using SDKMAN has two advantages.

  1. it will install the official packaging by Eclipse Adoptium, as opposed to the “mystery meat OpenJDK builds“.
  2. it will install tgz packaging of sbt that contains all JAR files. (DEB and RPM packages do not to save bandwidth)

Java Development Kit

For the JDK, we recommend Eclipse Adoptium Temurin JDK 8, 11, or 17, following sbt own recommendation, but any JDK should do (if you encounter an issue with any other JDK, please don't hesitate to open an issue).

The Eclipse Adoptium Temurin JDK is available for Windows (via winget), Mac OS (via homebrew) and many Linux distributions (via RPM and DEB packages). Refer to the installation documentation for all details. Arch-based Linux distributions can also install the Eclipse Temurin JDK via the associated non-official AUR package.

sbt

The PCE is developed with Scala. As this tutorial will require you to build the PCE from source, we'll use sbt, the de-facto build tool in the Scala community.

The sbt download page will give you instructions to install it:

  • on any system via cs setup, the Scala installer powered by Coursier
  • on Mac OS via SDKMAN or homebrew
  • on Windows via a msi file, Chocolatey or Scoop
  • on Linux via a deb or rpm package, or a universal package

Refer to the more extensive sbt "installing sbt" documentation for more information.

docker-compose

In the following steps, we'll also use a docker-compose configuration to run the PCE with its required dependencies (including a PostgreSQL instance).

You'll therefore either need Docker Desktop (which provides a full Docker installation, including Compose) or the Compose standalone installation.

Remember the Start the Docker Daemon

Make sure the Docker daemon is running and accessible to your current user before anything.

When using Systemd, you can run sudo systemctl status docker to check the status of the Docker daemon, and sudo systemctl start docker to start it.

Setup and Run the PCE

Now, to clone the privacy-computation-engine repository, run:

git clone git@github.com:blindnet-io/privacy-computation-engine.git
cd privacy-computation-engine

Here, you only need to run one script for everything: building the project, creating a dedicated Docker image, starting a Postgres instance, execute database migrations and run the Privacy Computation Engine:

./scripts/start.sh

After this script has been executed successfully, a new PCE instance should be available on your machine, with its API exposed on port 9000.

You can verify the service is running and available by calling the health endpoint:

curl -v localhost:9000/v0/health
Remember to stop it

After completing this tutorial, make sure to stop and clean up all associated docker containers with:

./scripts/stop.sh

Configuration

Now, your PCE instance needs some configuration.

Here again, you only need one script: ./scripts/init-config.sh.

This script includes all the different API calls needed to configure the PCE instance, with default configuration values.

Just execute this script, and your PCE instance is good to go.

./scripts/init-config.sh

You can make a GET /configure/general-info request to check the preconfigured general information configuration:

curl -v localhost:9000/v0/configure/general-info
Real-World Scenario

In a real-world scenario, you can use the exact same script to configure your PCE instance in one go, after replacing the example values with the ones which fit your real context.

Refer to the associated documentation for all details.

Using the Privacy Computation Engine

You can now directly call the standalone Privacy Computation Engine REST API from your applications and services.

However, the true strength of the blindnet devkit comes when combining its various components, thus drastically improving your developer experience and productivity while giving you access to additional features.

Starting with our premade user interfaces.

2. Add Privacy-Rights Management Capabilities to Your Application

User interfaces for the blindnet devkit (aka Privacy Components for the Web) are delivered as standard Web Components available on both npm and a CDN.

As a consequence, installing the blindnet devkit web interfaces doesn't involve any specificity, as you can install and use them as you would with any other standard Web Component.

info

See Using Web Components for more information on how to integrate Web Components in your existing project.

In the interest of simplicity and clarity, let's see how to integrate these components into a simple static HTML page, starting with the Privacy Request Capture Interface (PRCI).

PRCI is a simple interface allowing your users to assert their privacy rights by sending you a simple yet standardized Privacy Request. It is an entry point for your user to privacy, not only allowing you to cover GDPR and other privacy-related legislations but also and more importantly, to build trust by showing your users their privacy rights are tangibly handled, enforced and respected.

To integrate this interface into your web page, you'll first need to load the associated bundle (included in the @blindnet/prci npm package) from the unpkg CDN by adding a <script> tag to your HTML document:

<script src="https://unpkg.com/@blindnet/prci/dist/index.core.min.js?module" type="module"></script>
info

Here, we use the core module build for performance improvement.

As this build only integrates the core parts of the library, external dependencies like Lit will only be loaded once, even after we add other privacy components to this same web page.

Your specific context might be different. This is why each Privacy Component for the Web includes different builds and bundles covering any specific needs, as detailed in the User Interfaces - Install section.

Then, you only need to add the associated entry-point custom element <bln-priv-request> to your HTML document:

<h2 id="priv-request">Make a privacy request</h2>

<bldn-priv-request></bldn-priv-request>

The bldn-priv-request custom element support several attributes and properties to interact with it and configure its behavior.

Here, we only need to use the computation-base-url attribute to tell it to use our local PCE instance instead of the central one.

<bldn-priv-request computation-base-url="http://localhost:9000/v0"></bldn-priv-request>

Leading us to the following HTML file:

<!DOCTYPE html>
<html lang="en-GB">
<head>
<meta charset="utf-8" />
<title>Privacy Components for the Web - Minimal Static Demo</title>
</head>
<body>
<h1>Privacy Components for the Web - Minimal Static Demo</h1>

<h2>Assert Your Privacy Rights</h2>

<bldn-priv-request computation-base-url="http://localhost:9000/v0"></bldn-priv-request>

<script src="https://unpkg.com/@blindnet/prci/dist/index.core.min.js?module" type="module" ></script>
</body>
</html>
Demo

This simple static demo can be tested live on blindnet-io.github.io.

Code can be found in the privacy-components-web repository.

Check Out our Demo Web App

Need to see a more advanced use case? We got you covered.

Check it out

See our Demo Web App in action on blindnet-io.github.io and read its code in the privacy-components-web repository.

We keep this project as minimalist as possible for the sake of simplicity. It only use lit, with Carbon Web Components and the Vaadin Router. The build system has been set up using the Open WC generator (refer to the README for more information).

You can either directly clone the whole monorepo locally:

git clone git@github.com:blindnet-io/privacy-components-web.git
cd privacy-components-web/demos/devkit-simple-tutorial/

or use git sparse-checkout to only download the project itself:

mkdir devkit-web-demo
cd devkit-web-demo
git init
git remote add -f origin git@github.com:blindnet-io/privacy-components-web.git
git config core.sparsecheckout true
echo "demos/devkit-simple-tutorial" >> .git/info/sparse-checkout
git pull origin main

Then, you'll need to install the project's dependencies using classic yarn (v1) or npm:

yarn install
# OR
npm install

Then, start the development server:

yarn start
# OR
npm start

and open the application in your browser using the given URL.

info

The next steps have been already developed in this demo project. You can therefore refer to it whenever in doubt.

3. Assert Your Privacy Rights

Now, open the demo web app or static page in your browser to see this component in action:

first screen of the PRCI component

Here, your users can directly choose from a wide range of privacy request types.

This includes the classical consultation (access), deletion and modification of their data, of course, but also more advanced operations, including but not limited to:

  • requesting the portability of their data to a compatible system
  • advanced management of their consents (by objecting to and restricting proceeding of their data, or revoking previously given consents)
  • and retrieving more generic privacy-related information regarding your organization (via the "transparency" request type).
note

These are just requests. You determine how those are handled and answered, manually or automatically.

If, for example, your users want to make an Access request, and click on the Access button, they will be able to ask you to give them access to all the data you have on them, or to only select a subset of it.

First screen for an Access Request in the PRCI component Second screen for an Access Request in the PRCI component

Depending on your configuration, two scenarios can then happen.

If like in this example, you set up everything to automatically treat the request, then your users will directly see their request granted (or rejected, depending on the parameters you defined).

Status of a Delete Request as shown in the PRCI component: under review

Other scenarios might however require to be manually handled. In this case, your users will see their request is "pending" (i.e. waiting to be handled by your organization).

In this demo, you can see this happen when sending a delete request:

Status of a Delete Request as shown in the PRCI component: under review

4. Add an Admin Interface

An additional Privacy Component for the Web, called the "Data Consumer Interface", is here to help you handle these requests. It offers a simple interface to allow relevant members of your organization (e.g. system administrators or DPOs) to manage all privacy requests related matters.

To add the Data Consumer Interface Web Component to your project, simply follow the same steps as for the Privacy Request Capture Interface one, but with the @blindnet/dci npm package, and <bldn-data-consum> HTML custom element.

<!DOCTYPE html>
<html lang="en-GB">
<head>
<meta charset="utf-8" />
<title>Privacy Components for the Web - Minimal Static Demo</title>
</head>
<body>
<h1>Privacy Components for the Web - Minimal Static Demo</h1>

<h2>Assert Your Privacy Rights</h2>

<bldn-priv-request computation-base-url="http://localhost:9000/v0"></bldn-priv-request>

<h2>Manage Your Users' Requests</h2>

<bldn-data-consum computation-base-url="http://localhost:9000/v0"></bldn-data-consum>

<script src="https://unpkg.com/@blindnet/prci/dist/index.core.min.js?module" type="module" ></script>
<script src="https://unpkg.com/@blindnet/dci/dist/index.core.min.js?module" type="module" ></script>
</body>
</html>
danger

The computation-base-url parameter is part of the global privacy components for the web configuration via the @blindnet/core package. As a consequence, setting the computation base URL for a component impact all the other components attached to the same document.

Here, as we have two components on the same page, the value for the computation-base-url has to be the same for both.

Instead, we recommend setting the global configuration via the BlindnetCore.configure() method as follow:

<!DOCTYPE html>
<html lang="en-GB">
<head>
<meta charset="utf-8" />
<title>Privacy Components for the Web - Minimal Static Demo</title>
</head>
<body>
<h1>Privacy Components for the Web - Minimal Static Demo</h1>

<h2>Assert Your Privacy Rights</h2>

<bldn-priv-request></bldn-priv-request>

<h2>Manage Your Users' Requests</h2>

<bldn-data-consum></bldn-data-consum>

<script src="https://unpkg.com/@blindnet/prci/dist/index.core.min.js?module" type="module" ></script>
<script src="https://unpkg.com/@blindnet/dci/dist/index.core.min.js?module" type="module" ></script>

<script type="module">
globalThis.BlindnetCore.configure({
computationBaseURL: "http://localhost:9000/v0"
})
</script>
</body>
</html>

5. Answer Your Users' Requests

👷‍♂️ writing in progress

Open your web app / page, and follow the instructions given in the Data Consumer Interface Web Component.

6. Set-up Storage

👷‍♂️ writing in progress

A Data Access Component is here to transform requests from the Privacy Computation Engine to efficiently execute automated operations on your data storage.

You can choose to use the Capture Component and directly store the captured data in blindnet's preconfigured storage, or your own storage service.

You can also directly connect the Data Access Component to your own storage service without using the Capture Component. For see sake of simplicity, we'll choose this option for this tutorial.

For that, we'll set up a dedicated demo storage service in Java, and connect it to the Capture Component using the Java Storage Connector library.

Code for this demo stage service can be found in the example directory in the librarie's repository: github.com/blindnet-io/storage-connector-java > example.