GDPR, the European Union’s General Data Protection Regulation, came into effect in March of 2018. This new regulation sets the privacy and security expectations for handling user data, and applies to every actor evenly tangentially related to the European market.

As an API practitioner, it’s absolutely essential that you understand how to build products that comply with GDPR. Who better to walk you through the essentials than Curity CEO and Founder of Nordic APIs, Travis Spencer?

According to Travis, these three implementations — including the use of interactive user consent, pairwise pseudonymous identifiers, and phantom tokens — are essential not only for those pushing to meet regulation, but also those who are not necessarily subject to GDPR and yet still value building secure and private APIs.

Interactive User Consent

In short, user consent is getting the user’s approval to share data with some third-party application. This is that oh-so-crucial step when an application has requested access to certain data, the user has logged in, and it’s now time for the user to directly consent to share data — in OAuth, this is known as authorization, Travis calls it delegation, but what’s really important is that it’s there.

This might be the single most important step in GDPR compliance, since regulation states that not only should users how their data is being used or transmitted, but they should also have the option to opt in and out of sharing certain data or reject doing so altogether.

The Anatomy of a Consent Form

There’s some must-have information to include on every consent form, which is a good place to start with building your own. This includes:

• The name of the client application with whom the user consents to share their data, and, preferably, the relationship of that client to the organization (is it a first- or third-party application?)
• Some sort of logo or image representing the client, to add a graphical representation of the client with whom the user consents to share their data
• A description of the application, so that the user can understand — in layman’s’ terms — the purpose of the application with which they consent to share their data
• Any other relevant client or user information (for example, the user’s name or ID, to ensure they logged in with the account from which they consent to share their data)

Consent to Claims Not Scopes

Claims are individual client attributes, whereas scopes are groups of claims modeled around the needs of client applications. On your consent forms, make sure that you refer directly to the data claims which the user is consenting to share; this way, it’s abundantly clear (in normal English) what data is being shared.

Allow Claim Deselection

Once you’ve laid out all of the data which the client application is asking for, you should give users the option to deselect individual claims — those representing data which they do not consent to share.

In some cases, you might find that certain claims are necessary in the core functionality of the application — so the user’s not consenting to these claims might create an all-or-nothing situation where the user is unable to use the application altogether. In these cases, you should label required claims as such; from a technical standpoint, you can do so with the claims request parameter in OpenID Connect.

As an example from the OpenID Connect website, the code "auth_time": {"essential": true} indicates that the auth_time value is essential.

Show More Claims On-demand

If a client application requests access to a large number of claims, there’s no need to be pettily compliant: instead of bombarding the user with dozens of claims on a single consent screen (and thus sacrificing a certain amount of user experience), just present the most important claims and give users the to open a collapsible list for the rest.

An alternative solution is to simply ask for consent for the very basic claims up front, and — as more claims are needed through the application’s lifecycle — reauthorize and ask for additional consent later.

Add Support For Languages

As part of GDPR, it’s essential that users can make an informed decision on whether to give consent, based on the data they’re sharing. With that said, you should localize claim names and descriptions to ensure that users can read these items the languages most comfortable to them.

One way to do this is by using the UI locales query string parameter in OpenID Connect, which allows the application to directly communicate language data to OpenID for seamless user experience. Other ideas include storing a locale cookie on the OpenID server or the browser settings or including a drop-down language selection box on the consent page.

Let Users Cancel

A quick but very important feature to include in any consent form is the option to cancel the process. This is there in case the user decides they don’t like the look of the client or the claims they’re asking access to. From a user experience perspective, you should probably mute or somehow deemphasize this option — just make sure it’s there.

Force Consent and Reconsent

In some cases, you might need to force the user to give consent, or to re-give consent, to use or continue using a client’s application. A great example of when this would come in handy is if you or the client who built the application decide to make a change to relevant privacy policy; here, you would want to force users to re-consent. You can achieve this with OpenID Connect by adding the prompt=consent parameter to an authorization request.

Special Treatment for Dynamic Clients

Clients who register in a dynamic fashion, which is to say they register directly with the OpenID Connect server first, pose a larger security risk and thus require special treatment. In the registration process, it’s essential to validate URLs, privacy policies, terms of service, and more; validating URLs, for example, prevents the client from impersonating another individual or organization on the consent screen. Speaking of consent screens, you can show the heightened security risk to users in this way. As an example, Travis suggests using a yellow icon on the form instead of a green one,

Pairwise Pseudonymous Identifiers

Travis’ second suggestion for improving the security and privacy of your API — and in doing so complying with GDPR — is to create privacy-aware implementations of identity by means of pairwise pseudonymous identifiers.

Pairwise pseudonymous identifiers, also known as PPIDs, are unguessable user IDs that are randomly generated. PPIDs have no link to users’ given IDs, which prevent clients from tracking users and potentially building a larger profile of the client.

Sometimes, multiple applications might need access to the same user’s data. If so, it’s possible to group clients into sectors in which they receive the same PPID.

It’s important to prevent dynamic clients from accessing other sectors which they’re trying to attack or otherwise gain private information from. During the validation of these clients, you can look at a complete list of their URIs to determine if the sector they had chosen is applicable.

Phantom Tokens

The final suggestion for meeting GDPR is to use phantom tokens. Phantom tokens are a privacy-preserving pattern for access token issuance and usage. The basic premise for this is that an API proxy or gateway will switch a client’s access token to a separate token that acts in the internal network.

Using phantom tokens leaves you with a smaller space subject to users’ personal information, which means less regulation to worry about. Also, it prevents clients from getting data they shouldn’t, no matter how hard they try — unlike with encrypted tokens.

The Takeaways for API GDPR Compliance

And so you have it: three simple precautions to ensure your API complies with the personal information rules set out in the European Union’s GDPR. As Travis mentions, even for those not affected by the new regulation, these three implementations are still fantastic privacy and security measures for your API.

To recap, you should:

• Ask users for explicit consent to share their data, explaining who’ll use it and how (and giving them the option to opt out),
• Hide user IDs with pairwise pseudonymous identifiers (PPIDs), and,
• Use so-called phantom tokens on your internal network.