Accessing data using JWT Token Exchange#

Data sources protected by Feide are normally configured in the customer portal. The customer portal is used to configure policies for access to data sources and access levels. The data are accessed using JSON Web Tokens (JWTs). The data consumer obtains an OpenID Connect (OIDC) access token. It exchanges it for another token tailored for the data source, carrying all information the source needs to determine what information the consumer may access. This token is a JWT. It is short lived and digitally signed, allowing the data source to verify that it was issued by Feide, intended for the source, and still valid. The exchange conforms to RFC 8693 - OAuth2.0 token exchange.

In order to access a data source, you need a Feide service registered in the customer portal. It may be a service that users log in to, or a headless service with no associated user. It needs an OpenID Connect configuration with rights to access the data source and the appropriate access levels within it.

The data owner must approve access to the data, unless they have chosen to make the data source public.

Access starts with an OIDC access token. This could be the token the service receives when the user logs in, or a token which a headless service obtains with the client credentials flow.

Next, the service presents the access token to Feide and, if successful, receives back a JWT token for the data source. The request to Feide is a token exchange request to the token endpoint. For this request, grant type urn:ietf:params:oauth:grant-type:token-exchange is used. The response from the token endpoint is a token exchange response, which, unless the request fails, includes a JWT access token.

With each request to a data source endpoint, the service includes the JWT as a bearer token in the Authorization header. The data source verifies the signature of the token and checks that it is still valid, issued by Feide and intended for the data source. Finally, it checks which access levels the token authorizes, and responds appropriately.

Token exchange request from service#

Note

This is for the case when a client wants a JWT to pass to a data source. See Token exchange request from data source for the case when a data source wants a regular access token to pass to Feide.

A token exchange request includes audience and scope parameters. The audience must be the data source UUID registered in the customer portal, prefixed by https://n.feide.no/datasources/. Example: https://n.feide.no/datasources/02d0f79b-7fbc-422b-bb31-a4d22121f040. The valid values for scopes are the identifiers of the access levels which are registered in the customer portal for the data source.

A token exchange request is made to the token endpoint using the HTTP “POST” method. Parameters are included in the HTTP request entity-body using the application/x-www-form-urlencoded format. The parameters are:

audience

The UUID of the data source the JWT is intended for, prefixed by https://n.feide.no/datasources/.

client_id

The ID of the application making the exchange request.

client_secret

The client secret of the application.

grant_type

The value urn:ietf:params:oauth:grant-type:token-exchange selects OAuth2 token exchange.

scope

A space separated list of identifiers of desired access levels. It is up to the data source how to interpret them.

subject_token

An access token obtained from Feide. It should give the application access to the access levels given as scope in the data source given as audience.

subject_token_type

Must be urn:ietf:params:oauth:token-type:access_token.

Here is an example:

POST https://auth.dataporten.no/oauth/token
content-type: application/x-www-form-urlencoded

audience=https://n.feide.no/datasources/02d0f79b-7fbc-422b-bb31-a4d22121f040
&client_id=208335d4-e8c1-4910-8928-05b2e5b14127
&client_secret=5df85658-d0c1-4348-890a-a204b24eca2e
&grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&scope=read append
&subject_token=96c5a3aa-1af8-45bd-a4f8-4b7fb07d393f
&subject_token_type=urn:ietf:params:oauth:token-type:access_token

Successful response#

A successful response has status 200 and an application/json body with the following attributes:

token_type

The type is Bearer.

issued_token_type

The type is urn:ietf:params:oauth:token-type:jwt.

access_token

The JWT that was issued.

expires_in

Number of seconds until JWT expires.

scope

The scopes that were granted.

Here is an example:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI...",
    "token_type": "Bearer",
    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "expires_in": 299,
    "scope": "read append"
}

For details on the JWT access token itself see the reference documentation.

Token lifetimes#

A JWT cannot be reliably revoked. Therefore, the lifetime is only 5 minutes. If the application needs access after the token has expired, it must obtain a new one.