How to verify consent in data source

Introduction §

An application registered on the dataspace can request consents from a user to access the data from data sources which require user consent. If the user grants the consent the application can request a consent token and include it in the X-Consent-Token header when making the request to the product gateway. The product gateway will forward the header to the productizer. This guide explains how the productizer should verify the token if it wants to ensure the user has given their consent.

The consent token is a JSON Web Token (JWT) that can be decoded and verified. This guide will explain in more detail the process of extracting, decoding and verifying it.

For more details on how to request a consent and obtaining a consent token, check out the Using Consent section of the Building an application guide.

Verifying the consent token in the productizer §

Get the X-Consent-Token header

The productizer or data source needs to first extract the consent token from the X-Consent-Token HTTP header of the request. Please note that the header is in many data source definitions optional, so take that into account.

Reading the consent token

The consent token is a JSON Web Token (JWT).

If you are unfamiliar with JWTs you might want to check out the JSON Web Token Introduction. The same site has a really good tool for decoding JWTs directly in the web browser at jwt.io, as well as a fairly good list of different JWT libraries for different programming languages.

You most likely want to use one of the libraries for your programming language rather than try to implement it according to the RFC 7519.

Let's have a look at a valid example token from one of the applications on the IOXIO Sandbox Dataspace and how to verify it.

Let's examine this token:

At the time you are reading this guide the token will, unfortunately, have expired, so some of the verifications we will perform here won't work. If you need a valid token, you can follow the steps in the Using Consent section of the Building an application guide to set up your own application and request a consent token following the cURL examples in that guide. If you're familiar with developer tools in your browser you can also go to the board page of one of the companies in the MyCompany Demo App and extract the consent token from the Local Storage of your browser.

This is what the content of the above token looks like:

Many JWT libraries also allow you to read the JWT without verifying it. In case your library for some reason does not do that, you can actually note that the token consists of three sections separated by a dot, like AAA.BBB.CCC. The first section (AAA) is the header, the second one (BBB) the body and the last one (CCC) the signature. The first two are actually just Base64 encoded JSON strings that can be easily decoded and read, without verifying the signature.

Find the JWKS URI §

The first step to find the key is to check the issuer of the token, which is found in the iss field in the body.

Please note that you should check that the iss is one you want to trust. In a typical IOXIO dataspace this would always be the address of the consent provider of the dataspace.

In this example the iss (Issuer) is https://consent.sandbox.ioxio-dataspace.com, which is the consent provider of the sandbox dataspace. The consent provider has a consent configuration in a well-known path (inspired by the OpenID Connect configuration). The configuration for a consent provider can be found in the path /.well-known/dataspace/consent-configuration.json relative to the iss. Thus in this case the consent provider configuration can be fetched from https://consent.sandbox.ioxio-dataspace.com/.well-known/dataspace/consent-configuration.json. At the time of writing this it returned this JSON content (formatted for readability):

The jwks_uri specify where we can find the keys of this consent provider.

For convenience the JWT token also contains the jku (JSON Web Key Set URL) header with the same value. This is what for example jwt.io uses to fetch the key to verify the signature of the token.

Please note that you should validate the iss or jku match what you expect to find on the dataspace you are working on before fetching keys to ensure they are indeed keys that should be trusted on the particular dataspace.

Find the key §

At the time of writing this, the jwks_uri https://consent.sandbox.ioxio-dataspace.com/.well-known/jwks.json returned this JSON content (formatted for readability):

Use the key entry with a kid (Key ID) and alg (Algorithm) matching the values in the consent token and has the use set to sig (signing). You can read more about JWKS in RFC 7517: JSON Web Key (JWK).

Some JWT libraries, like PyJWT has built in support for retrieving the keys from a JWKS endpoint, thus it's worth checking if the library you are using has support for that before implementing it yourself.

Caching §

Please note that for performance reasons you should use some level of caching. The address of the jwks_uri is for example not likely to change in practice. The keys are neither rotated frequently, so they could be cached for some time, but it's still important they get refreshed once in a while.

Verifying token signature §

Once you've found the matching key (unless your library does that for you), you will need to consult the documentation of your particular JWT library on how to use it to verify the token. This varies a bit by library. In some case you might even need to convert the key to some other format accepted by the library. Covering all these possibilities is however not possible in this guide, but that information can hopefully be found from other sources using the most popular search engines.

Verifying the fields §

After verifying the signature, you should do some basic verification of some of the typical fields. Many libraries by default verify the iat (Issued At) and exp (Expiration Time), but some do not automatically do it. In that case you should verify that iat <= current time <= exp. You might also want to check the iss (Issuer) matches what you expect (the consent provider of the dataspace), but this would be good to check already before fetching the keys.

Also verify the dsi field. It contains a Data Product Protocol link of the form dpp://<source>@<dataspace-domain>/<definition>, which means you will have to parse it and check it against the data source you are implementing. For example dpp://ioxio@sandbox.ioxio-dataspace.com/NSG/Agent/LegalEntity/NonListedCompany/SignatoryRights_v1.0 would match a data source with the group ioxio for the NSG/Agent/LegalEntity/NonListedCompany/SignatoryRights_v1.0 definition on the sandbox.ioxio-dataspace.com dataspace. Ensure all of these match with the data source you want to provide.

You should verify the sub (the subject from the id_token that granted the consent) and subiss (the issuer of the id_token that was used to give the consent, typically the login portal) as well as the acr (authentication context class reference), to ensure which user actually gave the consent.

If your data source also requires authorization, you should also Verify id_token in data source. Check the sub of both tokens match and ensure the app in the consent token matches the aud of the id_token and the subiss in the consent token matches the iss in the id_token.

Using the token §

Once you've done all the verifications you know which user (sub+subiss+ acr) gave the consent to request the data through which application (app+ appiss) and to which data source (dsi). Verify these match with what you want to provide and what the user has permission to request and return the requested data.

Verifying consent through API §

The consent portal also provides an API endpoint for verifying the consent token if you don't want to fetch the keys yourself. The endpoint is located at the path /Consent/Verify of the consent portal, so for example on the sandbox dataspace the URL is https://consent.sandbox.ioxio-dataspace.com/Consent/Verify. It's expecting a POST request with the Authorization: Bearer <token> and the X-Consent-Token <consent token> headers. The body is expected to be in JSON format (Content-Type: application/json) and contain a body of the form:

Make sure you replace the source with the name of your own data source (group + optional variant separated by a colon), specify the dataspace domain and the definition your datasource is using. Here is what the request would look like as a cURL command with the respective tokens shortened down for readability:

You will get back a response indicating if the tokens passed the verification or not, in case of a success:

And in case of failure:

If you want to know who the user is (in case the data you return is depending on the user, which is quite common) you will need to decode the consent token to extract the user details ( sub+subiss+acr) from it. But since the tokens have already been verified you can decode them without any verification.