Refresh Token grant

This section deals with the OAuth 2 refresh token grant - a flow designed to refresh a previously obtained access token.

OAuth 2 JWT access tokens

Enter the OAuth 2 client credentials grant. TrustBuilder enables a client app to obtain an access token and take it along when calling a protected API, the so-called Relying Party. Before issuing the access token to the client app, however, TrustBuilder checks the policy whether it should indeed issue the token with the requested privileges. The flows is as follows:

The ‘TB.io AS’ is the OAuth Authorization Server of the TrustBuilder platform. The ‘RP’ is the OAuth Relying Party, i.e. the intended API endpoint referred to by <audience> & <scope>. As long as the access token has not expired, and, the API endpoint is the same (read: <audience> & <scope> are the same), the access token can be reused (hence the loop in the diagram).

Configuration

First, ensure your client app can be authenticated. Please refer to the Client Credentials grant and the JWT Bearer grant and apply the same method.

Access Token Request

The client app requests a token by contacting the token endpoint directly with the Client Credentials grant. The request parameters are typically:

CODE

{
  "grant_type": "refresh_token",
  "client_id": "<client_id of the client app>",
  "client_secret": "<shared client_secret>",
  "refresh_token": "<a refresh token>"
}

Token Response

The token endpoint response returns the requested access token and may add specific claims to the access token. These claims may indicate certain fine-grained attributes of the client app, such as its persona or tenant in the TrustBuilder context. Note that there is no id token, given that the grant doesn’t entail user identity in any capacity.

Important note: the mechanism should be used in an efficient way taking advantage of the fact that an access token can be reused until it expires. Once a client app requests and obtains an access token, it should keep it around in a safe place for the duration of its useful lifetime and re-use it whenever it needs to call the same API. Requesting a new access token from TrustBuilder every time again and again can be a costly anti-pattern, possibly draining performance and availability.

A TrustBuilder bearer access token is encrypted (e.g. VCJ943eyJzdWIiOiIxMjM...wIiwibmFtZSI6IkpvaG4). A decoded access token may look like:

CODE

{
  "iss": "https://<your domain>/",
  "aud": "<your domain>",
  "client_id": "<client_id of the client app>",
  "iat": 1590440782,
  "exp": 1590450969,
  "scope": "<intended API endpoint>",
  "tenant": "<tenant-id>"
}

The scope claim will only contain the scopes that (1) have been requested and (2) that can be granted to the user after evaluating the policy for the requested API endpoint. This means that less scopes may be returned in case the user does not qualify for all scopes given the user profile and the user session.

Calling the API

The call to the API occurs as usual with the access token in the authorization header:

CODE

authorization: Bearer VCJ943eyJzdWIiOiIxMjM...wIiwibmFtZSI6IkpvaG4

The call happens without any dependency on how the client obtained the access token.

The API Gateway can first check whether the JWT access token is issued by TrustBuilder (by verifying its signature) and is issued for the client app that is doing the call.

The API Gateway can then orchestrate the call to the correct API given the aud and scope and can verify whether the scope corresponds to the API endpoint.

If the connection between the API Gateway and the API is sufficiently trusted (e.g. within the same environment), the API itself can then blindly accept the call. Optionally, it can further exercise fine-grained authorisation using the claims that TrustBuilder has added to the access token, such as persona.

References

https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication