Introduction

Our Privacy Services APIs help solve GDPR compliance by providing several ways to configure and administrate privacy related functionality. This includes configuration for processing purposes, data objects those purposes are connected to, 3rd party sharing of data, retention, how consent dialogues are triggered and functionality related to a data subject’s rights in privacy management interactions in our identity portal (Ü).

The privacy services APIs are centered around the concept of Projects, where a project is defined as a collection of API clients that can access our APIs on behalf of your service. A project needs to define some basic privacy related metadata, such as data controller information, policies and jurisdiction that applies for the service integrating with our identity solution. API clients are segmented by type (web, iOS, Android, backend) and have access to users and data connected to the same project.

As an example, your service might be provided in 2 channels, as a web and iOS application. Organising those API clients within the same project allows you to be able to login users and ask for consent across both applications for the same service.

Defining data processing purposes

In order to become GDPR compliant there are some core data protection principles that must be followed.

  • Purpose Specification
  • Storage Limitation
  • Data Minimisation
  • Security
  • Accuracy
  • Transparency

Our privacy configuration is created to help you define your purposes for data processing and be transparent about what you are doing. GDPR defines that the following information must be made available to the data subject (the individual the data is about) when personal identifiable information is collected:

  • The identity and the contact details of the controller and the data protection officer
  • The purposes of the processing for which the personal data are intended
  • The legal ground of the processing
  • Where applicable the legitimate interests pursued by the controller or by a third party
  • Where applicable, the recipients or categories of recipients of the personal data
  • Where applicable, that the controller intends to transfer personal data internationally
  • The period for which the personal data will be stored, or if this is not possible, the criteria used to determine this period

Additional information if the data has not been obtained directly from the data subject – perhaps using a 3rd party list:

  • From which source the personal data originated from
  • The existence of any profiling and meaningful information about the logic involved, as well as the significance and the envisaged consequences of such processing for the data subject

In order to provide the user with all that information required by GDPR we have provided you with the possibility to define your metadata (contact information), your data processing purposes, the data used in the processing and the potential third parties you share the personal data with. If you edit your purposes after the user have consented then that may require a new consent, so we also support versioning where you decide if the change requires a new consent or not.

There are 4 different legal grounds for personal data processing activities:

  • legal requirement
  • performance of a contract
  • legitimate interests
  • individual’s consent

Processing of personal data must rely at least on one of the above mentioned legal grounds during the whole information life-cycle – from collection of the data to the final and complete erasure or anonymization.

From a legal point of view, there is no hierarchy between different legal grounds, unless the law explicitly requires consent in a specific case to be used as the legal ground. However, we’ve established a order of priority between different legal grounds as detailed below:

illstration

For example, consent is just one of several legal grounds to process personal data, rather than the main ground. When correctly used, consent is a tool giving the data subject control over the processing of his or her data. If incorrectly used, the data subject’s control becomes illusory and consent constitutes an inappropriate basis for processing.

Mandatory consent is used for all processing activities, where applicable law explicitly requires a consent (e.g. processing of special categories of data).

The "legal requirement" and "performance of contract" legal grounds are used for "core" processing activities (when consent is not mandatory). The "core" processing constitutes the minimum and prerequisite level of processing, both in relation to processing purposes and processed data categories, for enabling e.g. your company to provide its products and services as well as fulfill legal requirements. For processing activities, which fall outside the above mentioned "core" area of processing and do not require individual’s consent under law, the usage of "legitimate interests" as legal ground, can be applicable.

Consent is used as the legal ground for the processing if the processing goes beyond:

  • what is required by law, and
  • what is necessary for fulfilling a contract, and
  • your company’s "legitimate interests"

illstration

Getting started

Get started with the Privacy APIs in only three steps:

  • Get your OAuth 2.0 credentials
  • Get an access token
  • Call the API

Get your OAuth 2.0 credentials

Go to Telia SelfService to create an account and register your application(s). Create a client that you will use to authenticate against our APIs. It is recommended to have one client per application (web, Android, iOS, backend) due to separation of concerns. Add your client(s) to a project that will be the umbrella for all your privacy configuration.

Remember to make a note of your clientId and clientSecret.

Your client secret is confidential

While the clientId is considered public information, the clientSecret must be kept confidential. If anyone can access your clientSecret they can issue tokens and access resources they shouldn't.

Get an access token

Before you can access our APIs you’ll need to obtain an access token.

With Client Credentials Grant (defined in RFC 6749, section 4.4) a server client (a CLI, a daemon, or a service running on your backend), can directly ask our authorization server for an access_token, by using its Client Credentials (Client Id and Client Secret) to authenticate. In this case the token represents the server client, instead of an end user.illstration

  • The application authenticates with our authorization server using its clientId and clientSecret.
  • The authorization server validates this information and returns an access_token.
  • The application can use the access_token to call the API on behalf of itself.

Curl

curl -s -X POST \
-d 'grant_type=client_credentials' \
-d 'client_id=<clientId>' \
-d 'client_secret=<clientSecret>' \
'https://sandbox.login.telia.io/realms/telia/protocol/openid-connect/token'

Javascript

var request = require("request");

var options = { method: 'POST',
  url: 'https://sandbox.login.telia.io/realms/telia/protocol/openid-connect/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { grant_type: 'client_credentials',
     client_id: '<clientId>',
     client_secret: '<clientSecret>'
   }
 };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Where:

  • grant_type: This must be client_credentials.
  • client_id: Your application's clientId. You can find your clientId in SelfService.
  • client_secret: Your application's clientSecret. You get the secret when you create your application in SelfService. You may regenerate your secret, but be aware that integrations that use the old secret will stop working.

The response contains a signed JSON Web Token, the token's type (which is Bearer), and how long it is until it expires in seconds.

{
  "access_token": "eyJhbGciOi....44FJrQPA",
  "expires_in": 60,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGci....17OqD7ZA",
  "token_type": "bearer",
  "id_token": "eyJhbGc....JnchX09ReQ",
  "not-before-policy": 0,
  "session_state": "d718bef2-062e-4998-bdf1-7fcb9529c534"
}

If you decode the access_token you will see that it contains among others the following claims:

{
  "iss": "https://sandbox.login.telia.io/realms/telia",
  "sub": "YOUR_USER_ID",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1489715431, // unix timestamp of the token's expiration date,
  "iat": 1489679431, // unix timestamp of the token's creation date
}

Call the API

Use the access_token you received in the previous step to authenticate against the Privacy APIs.

Curl

curl --request GET \
  --url 'https://sandbox.api.telia.io/privacy/v1/configurations' \
  --header 'authorization: Bearer <access_token>' \
  --header 'content-type: application/json'

Javascript

var request = require("request");

var options = { method: 'GET',
  url: 'https://sandbox.api.telia.io/privacy/v1/configurations',
  headers:
   { authorization: 'Bearer <access_token>,
     'content-type': 'application/json' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

results matching ""

    No results matching ""