Developer Documentation
Version 1.1
Abstract: This is the developer guide to integrating the consent building block into an application. This ensures user data is handled with transparency and adherence to regulatory standards. From an overview of the key components involved in Consent BB to installing and integrating, this document provides all the necessary resources to seamlessly embed and configure the Consent BB in an application.
| Version | Authors | Comments |
| v1.0 | Kashish Malik, George Padayatti, Lal Chandran | Pre-release, 8-Nov-2023 |
| v.1.1 | George Padayatti, Lal Chandran | GovStack release, 15-Nov-2023 |
- 1.0 Introduction
- 2.0 System architecture
- 3.0 Server installation guideline
- 4.0 Client SDK integration guideline
- 5.0 Developer workflows with APIs
- 6.0 API specifications
- Appendix A: Reference application - Data4Diabetes
- Appendix B: Postman API collection
- Appendix C: Admin configurations via the admin dashboard
- Appendix D: Kubernetes deployment user guide
- References
The Consent Building Block (BB) empowers individuals to approve utilising their personal data by establishing a comprehensive framework that outlines an information system's principles, functions and architectural components. Concurrently, it provides organisations engaged in personal data processing the means to ascertain an individual's intent and lawfully manage such personal data.
This document is intended for application developers to support their integration of Consent BB into their existing applications within their organisations. This document contains detailed API endpoint descriptions, sample code snippets, and step-by-step integration guides aimed at simplifying the development process. Whether troubleshooting, exploring functionalities, or building new applications, this documentation is your go-to reference, providing the essential tools and insights to leverage our technology in your projects efficiently.
Figure 01: Consent BB software component architecture and interactions
The Consent BB server comprises the following components:
- A backend microservice accessible through RESTful APIs
- An internal database for persistence
- Administrative dashboard for configurations
- Data sharing UI component
These are bundled together as installable components, described further in section 2.0, while section 3.0 details getting it up and running in the server.
Section 4.0 provides guidelines for adopting the Consent BB privacy dashboard SDKs for Android and iOS. It also provides guidelines for application developers to integrate and access the WebClient.
Three actors in the Consent BB system have distinct roles, contributing to specific use cases that implement the desired functionality. These actors, illustrated in Figure 02, form the fundamental dynamics of the ecosystem:
- The organisational (data controller or PII controller) Administrator representing an organisation processing personal data, relies on the Consent BB to facilitate compliance with consent-related regulations and ethical practices. They seek agreement (consent being one of the lawful bases) from individuals, outlining the envisaged data processing activities. The Administrator also ensures that data usage aligns with the provisions stated in the granted consent and adjusts operations in response to any alterations in individual preferences.
Figure 02: Key actors and use cases
-
Individuals (or data subject or PII principle) are the primary proprietors of their personal data and have the authority to grant or withhold consent for its use if the lawful basis of the process is of the type of consent, contract or legitimate interest. Their engagement entails initiating consent requests, scrutinising data processing intentions, and ultimately bestowing or retracting consent. Through this active involvement, individuals exercise control over their personal information and affirm their preferences.
-
A data processing Auditor(or regulatory body) oversees and assures adherence to legal and regulatory requisites within the system. The Auditor oversees the consent process to verify that organisations and individuals engage in transparent, compliant and responsible practices. By maintaining a vigilant stance, the Auditor upholds the integrity of the consent ecosystem, fostering trust between individuals and data processors.
These three actors collectively establish a harmonious and responsible consent system where transparency, individual autonomy and regulatory compliance converge to shape data processing parameters.
The software stack for consent BB is based on a microservice architecture. This architecture allows the designing of loosely coupled, independently deployed software components with well-known external interfaces that enable seamless interactions. Using containers (microservices) is at the core of the software architecture.
Figure 03: Consent BB microservice reference end-to-end architecture
The container technology allows building self-contained, small and independently deployable software components on a chosen platform, across platform(s) or on-premise. These components are illustrated in Figure 01. They can be deployed as containers (on docker) for local development during software development and be deployed on Kubernetes for production. High availability, resilience and service continuity are at the heart of the architecture. The Kubernetes platform provides the orchestration and management of containerised components. These components are always deployed with multiple instances and clustering for the database components (e.g. 3+1 deployment configuration in commercial environments). When an instance of the microservice fails, other instances can serve the requests, thus avoiding any single point of failure. The platform with probes monitors the containerised application and takes corrective action, including spinning up new instances when failures are detected. For the database, there are always an odd number of cases (3, 5 or more) that allow the database to tolerate instance failures and use their clustering mode to distribute the persistent data and allow data integrity at all times. A reverse proxy is set up to route traffic to the appropriate building block. This allows client applications like web or mobile applications to interact with the Consent BB microservice through the reverse proxy.
The software upgrade of the components can be done in a rolling fashion to ensure continuous service availability and to avoid multiple instances going down at the same time that might result in service failure and downtime.
In the Consent BB microservice architecture, the authentication mechanisms confirm the identity of users or services to allow the use of APIs. It allows the configuration of OpenID-Connect-based ID providers for authentication. It provides a standardised method for user authentication through tokens, enhancing security and the user experience. JSON web tokens (JWT) ensure the integrity and authenticity of the information exchanged during authentication, strengthening the system's overall security posture. The reference implementation is configured using KeyCloak-based identity and access management (IAM) and accommodates third-party authentication integration. The Consent BB could also employ user authentication, part of the GovStack solution based on OpenID Connect. The API always expects the JWT token embedded in the API calls to identify the user and ensure the security of the Consent BB solution.
The server installation includes the following components to be deployed:
- Application programming interface server
- Keycloak
- MongoDB
- Data sharing UI component
- Administrative Dashboard
The Consent BB server can be deployed to a target Kubernetes cluster by applying the manifest files using **kubectl. Refer to Appendix D for details.
It is an HTTP REST server written in Go. This instance is configured by passing a configuration file in JSON during the application startup. The different fields and values required in the configuration are given below. These parameters are defined in the config-development.json file.
| Configuration name | Value |
database
|
Defines the details needed to connect with the MongoDB database. A sample value is given below:
|
applicationMode
|
Defines the mode in which the application should start. There are two modes available:
|
organisation
|
Defines the details required for instantiating the root organisation. A sample value is given below:
|
user
|
Defines the details required for instantiating the root user. A sample value is given below:
|
type
|
Defines the details required for instantiating the organisation type or sector. A sample value is given below:
|
iam
|
Defines the details required to connect with Keycloak IAM. A sample value is given below:
|
smtp
|
Defines the details required to connect with SMTP server. A sample value is given below:
|
twilio
|
Defines the details required to connect with Twilio. A sample value is given below:
|
webhook
|
Defines the details required to configure webhooks. The sample value is given below:
|
privacyDashboard
|
Defines the details required to deploy the privacy dashboard (web client). A sample value is given below:
|
You can also run the API server locally or any server for internal tests by following the instructions below. Please refer to the README.md file in the Consent BB API server repository for the latest version. The prerequisites for getting the server up and running are as follows:
- The Configuration file described above is filled in with all default parameters.
- Docker is up and running on your server. You can use the command
docker psto check. - Pre-install jq (Available at: https://jqlang.github.io/jq), a lightweight and flexible command-line JSON processor for parsing and manipulating JSON data.
You can request a pre-defined configuration file and skip the following steps by contacting [email protected]. Please specify the desired admin username in your request. Alternatively, you can proceed with steps 3 and 4 for manually installing and configuring yourself.
- Install keycloak and use the parameters in step 4 configurations.
- The configuration parameters used by the Consent BB API server are created at
<server>/bb-consent-api/resources/config/config-development.json. This sets up the default parameters for the Consent BB server instance, such as organisation details, admin access security (with keycloak, etc. This can also be modified later but would require building the server again.
NOTE: It is recommended to remove all container instances and volumes running using
docker container rm -f $(docker container ls -aq)anddocker volume rm $(docker volume ls -q). If any of the steps below need to be repeated, we recommend this step to ensure a clean environment.
Now, follow the steps below to get the ConsentBB API server up and running:
- Clone this repository to your local server using
git clone. - Check out the latest release or any available release you wish to run. E.g.
git checkout tags/2023.10.4. - Execute
make setup. This sets up the necessary dependencies and configurations for running the Consent BB API server instance. - Execute
make build. The compiles and assembles source code into executable files or libraries, following the instructions specified in the Makefile of Consent BB API server instance. - Execute
make run. This executes a predefined set of instructions in the Makefile to launch or run the compiled Consent BB API server instance.
The server is up and running now locally at https://api.bb-consent.dev/v2. You can use openAPIs (Refer to Appendix B) or the admin dashboard (Refer to Chapter 3.2 Administrative Dashboard) to interact with the Consent BB API server instance.
Keycloak is an opensource tool for identity and access management. Consent BB leverages Keycloak for authentication of individuals and organisation admin. Keycloak instance is configured using the Kubernetes manifest files provided. You can use the trial keycloak instance or install a local instance from https://www.keycloak.org/, as mentioned in prerequisites after step 2.
MongoDB is a NoSQL database Consent BB uses to store data agreements, consent records, policies, etc. MongoDB instance is configured using the Kubernetes manifest files provided.
The Admin Dashboard can be deployed to a target Kubernetes cluster by applying the manifest files using **kubectl. Refer to Appendix D for details.
The admin dashboard is a ReactJS-based portal for organisation admins to configure a consent BB instance. It is configured using the Kubernetes manifest files provided. Follow the steps below to get the admin dashboard up and running locally. Follow the steps below to get the admin dashboard up and running locally.
- Clone this repository to your local server using
git clone. - Check out the latest release or any available release you wish to run.
- Modify the
.envfile in the root folder to point to your Consent BB API server instance. - Execute
make setup. This establishes the necessary dependencies and configurations for running the admin dashboard instance. - Execute
make build. The compiles and assembles source code into executable files or libraries, following the instructions specified in the Makefile of the admin dashboard instance. - Execute
make run. This executes a predefined set of instructions in the Makefile to launch or run the compiled admin dashboard server instance.
The admin dashboard can now be accessed at https://dashboard.bb-consent.dev.
Note: If you have security issues with your browser, you may install a self-signed certificate from the ConsentBB GitHub repo as an alternative to fix the issue.
These are ReactJS-based portals organisations can deploy for individuals once the data agreement models are defined in the admin dashboard. In the privacy dashboard, individuals can view all data agreements regardless of their lawful purposes. If the lawful purpose of processing defined in the data agreement is consent or legitimate use, they can opt in or out of the agreement at any time.
Technology stack: React.js and Typescript
Version - According to release guidelines here.
Repository: https://github.com/decentralised-dataexchange/bb-consent-privacy-dashboard
The Consent BB admin dashboard provides functionality for the organisation admin to manage the privacy dashboard instance and see the deployment details. Organisation admin can deploy an instance of a privacy dashboard to a Kubernetes cluster. During deployment, it is possible to specify the docker image version to be deployed and the domain URL using which the privacy dashboard can be accessed from the internet.
The privacy dashboard can be manually deployed to a Kubernetes cluster by applying the Kubernetes manifest files.
The privacy dashboard is available as a mobile SDK (Android) to manage consent for the individual. These support multiple languages, English being the default.
| Android SDKs |
Gradle Dependency - <Group name>.<Library name>.<version>
Group name - Library name - PrivacyDashboard (this is changeable) Version - According to https://github.com/decentralised-dataexchange/bb-consent-docs/wiki/release-guidelines Package manager - Jitpack Repository- https://github.com/decentralised-dataexchange/bb-consent-android-privacy-dashboard |
Gradle:
dependencies {
implementation 'com.github.decentralised-dataexchange:bb-consent-android-privacy-dashboard:<latest release>'
}
Maven:
<dependency>
<groupId>com.github.decentralised-dataexchange</groupId>
<artifactId>bb-consent-android-privacy-dashboard</artifactId>
<version><latest release></version>
</dependency>
We can initiate the privacy dashboard by calling the below.
PrivacyDashboard.showPrivacyDashboard().withApiKey(<API key>)
.withUserId(<User ID>)
.withOrgId(<Org ID>)
.withBaseUrl(<Base URL>).start(this)
To set the language, we just need to add the following before the start(this)
.withLocale(<language code>)
To enable user requests, we just need to add the following before the start(this)
.enableUserRequest()
To enable Ask Me, we just need to add the following before the start(this)
.enableAskMe()
The privacy dashboard is available as mobile SDKs (iOS) to manage consent for the individual. These support multiple languages, English being the default.
| iOS SDKs |
Library name - PrivacyDashboardiOS
Version - According to https://github.com/decentralised-dataexchange/bb-consent-docs/wiki/release-guidelines Package manager - Cocoapods \ \ Repository: https://github.com/decentralised-dataexchange/bb-consent-ios-privacy-dashboard |
PrivacyDashboardiOS is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'PrivacyDashboardiOS'
We can initiate the privacy dashboard using the code below in the ViewDidAppear method to invoke the SDK.
#import PrivacyDashboardiOS
BBConsentPrivacyDashboardiOS.shared.show(organisationId: <Org ID>, apiKey: <API key>, userId: <User ID>)
To enable User requests, add the following line:
BBConsentPrivacyDashboardiOS.shared.turnOnUserRequests = true
To enable the “Ask me” section in the attribute detail screen, add the following line:
BBConsentPrivacyDashboardiOS.shared.turnOnAskMeSection = true
To disable PrivacyDashBoardiOS presenting animation, invoke SDK as shown:
#import PrivacyDashboardiOS
BBConsentPrivacyDashboardiOS.shared.show(organisationId: <Org ID>, apiKey: <API key>, userId: <User ID>, animate: false)
Note: By default, this will be turned on.
Once the consent BB server is installed and up and running as described in section 3.0 Server installation guideline, the application developer will need to integrate the SDKs either in the end-user mobile apps or end-user web application as described in section 4.0 Client SDK integration guideline.
This section describes the key APIs the developers can integrate within the application on their server application. There are three broad categories of workflows possible from a DUS and DS perspective:
- Pre-registration workflow: Here, the user is not yet defined in the application.
- Post-registration workflow: This scenario applies when the application user is signed into the system and is triggering a real-time consent check.
- Consent verification workflow: Here, the organisational IT function can check if a data agreement record exists (e.g., consent record, if the lawful basis is consent).
Consent may or may not be with data sharing. In cases where a DS (Data Source) needs to expose data based on a request from a DUS, the Data Sharing UI is triggered. In this case, there are three possible scenarios based on whether Consent BB is deployed in the data-sharing organisations (DS and DUS):
-
Only DS has deployed Consent BB: Here, the DS application (Resource Server) knows the data agreement and redirects the DUS (Relying Party) workflows to a data sharing agreement screen if the consent does not exist in DS Consent BB. An example is as shown in Figure 4a.
-
Only DUS has deployed Consent BB: Here, the DUS must obtain consent to fetch data from a third-party provider. The individual is shown the data agreement screen to obtain consent the first time. Subsequent consents are managed via data agreement using the privacy dashboard offline. An example is shown in Figure 4b.
-
DS and DUS have deployed Consent BB: This is a combination of scenarios 1 and 2 where both parties store and manage consents. Only the DS screen is shown if the consent doesnt exist, and this is decided by the DUS application to ensure a seamless user experience. The DUS consent BB is updated based on the user interactions. Subsequent consents are managed by both parties (DS and DUS) using the privacy dashboard offline. An example is shown in Figure 4c.
This section explains the end-user interaction when the client UI SDKs are integrated with the third-party applications (APPLICATION) during a pre-registration workflow.
Figure 04a: Data sharing during pre-registration workflow (Only DS has Consent BB)
Figure 4a is a pre-registration workflow when Consent BB exists only in DS. In contrast, Figure 4b below shows when Consent BB exists only in the DUS application.
Figure 04b: Data sharing during pre-registration workflow (Only DUS has Consent BB)
A third pre-registration scenario is when Consent BB exists in DS and DUS.
Figure 04c: Data sharing during pre-registration workflow (Conbsent BB in both DS and the Application/DUS)
In all three scenarios above, the user can preview the exchanged attributes depending on the data agreement configurations. Once the individual accepts the data agreement, the pre-registration flow continues. For example, if Data4Diabtes consumes data from an (external) APPLICATION, it defines a data agreement as a data-using service. The individual, in this case, is presented with a data-sharing request for consent (For lawful basis consent) or authorisation for the data exchange. The individual can view the agreement details by clicking the “data agreement details” link, as shown in Figure 05. Here, the data agreement is shown as a pop-up with the details configured in the data agreement by the Data4Diabetes application provider.
Figure 05: The data agreement details screen shows if the user wishes for details.
Figure 06: The mobile version of data sharing and details screen.
This section explains the end-user interaction when the client UI SDKs are integrated with the end applications (APPLICATION) during a post-registration workflow.
Figure 07: Data sharing during post-registration workflow.
The steps in the post-registration workflow are below:
- The privacy dashboard knows the required data agreements and related objects (Controller) and is fetched from consent BB.
- The privacy dashboard fetches the individual from consent BB using foundational or functional ID.
- The privacy dashboard fetches the consent record for a data agreement.
- If a consent record doesn't exist, the privacy dashboard shows the data sharing UI to the individual.
- And proceeds to repeat steps 3 to 5 in the pre-registration workflow.
This section explains how the application performs consent verification by fetching consent records for an individual from the Consent BB.
Figure 08: Consent verification workflow
The steps in the consent verification workflow are as given below:
- The application fetches the latest active consent record and signature for verification using the data agreement ID and individual ID. Typically, this is handled by a workflow function.
- The application checks if the consent exists and proceeds with the necessary action.
The APIs are listed at https://consent-bb-swagger.igrant.io. Appendix B provides information on using the developer API collections for tests.
Empowering individuals with diabetes to take control of their health, Data4Diabetes is a cutting-edge app with decentralised capabilities. It serves as a powerful data intermediary within a secure dataspace ecosystem, connecting and sharing personal data from various sources to help individuals maintain their blood sugar levels in line with official recommendations. By leveraging a sophisticated Software Development Kit (SDK) that includes the 'Consent Building Block' (BB), Data4Diabetes allows users to determine what data they share based on MyData principles. This puts individuals in control of their personal health information while also providing the opportunity to contribute to valuable diabetes research. With a comprehensive framework that outlines principles, functions, and architectural components, this app ensures that personal data is managed lawfully and by the user's intent, ultimately promoting better diabetes management and data privacy.
**Configuration: **In the app module's **build.gradle (Module-level), add a dependency to include the bb-consent-android-privacy-dashboard SDK. Be sure to replace "latest_version"
dependencies { implementation 'com.github.decentralised-dataexchange:bb-consent-android-privacy-dashboard:<latest release>'
}
To enable data binding, add the following code snippet.
buildFeatures {
dataBinding = true
}
Integration: Initiate the privacy dashboard by calling the below inside the MainActivity file.
PrivacyDashboard.showPrivacyDashboard().withApiKey(<API key>)
.withUserId(<User ID>)
.withOrgId(<Org ID>)
.withBaseUrl(<Base URL>).start(this)
Configuration: Add the following code line inside the pod file to include bb-consent-ios-privacy-dashboard SDK.
(Note: The following code snippet will automatically execute the latest version of the SDK, so there's no need to specify the SDK version number.)
pod 'PrivacyDashboardiOS'
Integration: Add the following code inside the AppDelegate file to invoke Privacy Dashboard
#import PrivacyDashboardiOS
BBConsentPrivacyDashboardiOS.shared.show(organisationId: <Org ID>, apiKey: <API key>, userId: <User ID>)
All APIs are published at https://consent-bb-swagger.igrant.io/. If you wish to test it locally in Postman, follow the instructions below:
- Select the version you wish to test against.
- Download the open API spec.
- Import the downloaded openAPI spec to your Postman collection.
- Click View import settings as shown below.
- Choose “tags” that will organise APIs by tags in a proper manner.
- Return to the previous screen and click import to import the APIs locally. You can now see the APIs grouped into tags, audit, config, onboard and service, as shown.
- You can now continue testing the APIs against your local server by cloning the repo [email protected]:decentralised-dataexchange/bb-consent-api.git locally. Please contact [email protected] to obtain the required configuration files that you need to use to get your local server up and running.
Note: jq is a pre-requisites for running consent BB locally.
Alternatively, you can run the APIs from https://consent-bb-swagger.igrant.io/v2023.8.2/index.html. This requires the installation of a self-signed SSL certificate in the browser where you are running the APIs from. You can install the ca.pem from the consent bb cert repo.
The table below summarises key Administrator tasks performed as part of the consent/ agreement lifecycle from the provided admin dashboard page. The same actions can be performed using the config APIs (https://consent-bb-swagger.igrant.io/).
| Getting started | The Administrator can configure the organisation, including the images (logos, cover images, etc.) used during a data exchange or in end-user panels. |
| Data agreements | The Administrator can perform all CRUD operations. This includes viewing, updating, and downloading a data agreement as a JSON file and deleting a published data agreement. |
| Personal data | The Administrator can view all data processed in the organisation defined in the data agreement. This is read-only. |
| Manage consents | The Administrator can manage end-user consents. |
| Consent records | The Administrator can view consents and use filters, etc. |
| Subscription | The Administrator can onboard existing Individuals (subscribers) to the organisation. This is useful for legacy applications. |
| Privacy Dashboard | The Administrator can configure and deploy the privacy dashboard via this panel. |
| Account | The Administrator can manage their account in the Consent BB using this panel. |
| Manage admin | The Administrator can manage their user account, password, etc., via this panel. |
| Developer APIs | Organisations can view the endpoints, tokens, etc, here. |
| View logs | The Administrator can view all administrative logs via this panel. |
| Webhooks | Here, the Administrator can configure webhooks. |
| Number of nodes in the cluster | 2 |
| vCPU | 2 dedicated |
| RAM | 4GB |
| Disk size | 100 GB |
Step 1: Revise the configuration file to your local configurations as per the installation guideline. Step 2: Deploy the cluster with kubectl.
[1] GovStack: Consent BB - Software Design Specification, v1.1