JWT Bearer grant
This section deals with the OAuth 2 JWT bearer grant - a flow designed for fine-grained authorisation in a user context.
User Sessions
A user session has a lifecycle during which multiple authorisation requests are made. While a user has a session, the user may be providing additional authentication assurance, or conversely, the risk context of the session may degrade over time. As such, a TrustBuilder session has a lifecycle and the session state changes over time.
During such a session lifecylce, the user may obtain fine-grained authorisation decisions from the PDP (Policy Decision Point, i.e.Note that while the Authentication Server is called upon when the user needs a session (wants to or is requested to logon), multiple authorisation decisions may be requested during a single session from the Authorization Server. This is done either in the form of a XACML3 policy decision request, or in the form of an OAuth2 access token request. This page describes the JWT Bearer grant to obtain access tokens to convey fine-grained authorisations.
OAuth2 JWT access tokens
Enter the OAuth 2 JWT bearer grant. TrustBuilder enables a user agent 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 agent, 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).
Access Token Request
The user agent requests a token by contacting the token endpoint directly with the JWT Bearer grant. The request parameters are typically:
{
"grant_type": "jwt_bearer",
"subject_token": "B68D43eyJzdWIiOiIxMjM...wIiwibmFtZSI6IkCva32",
"client_id": "<client_id of the user agent>",
"scope": "<intended API endpoint>"
}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.
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:
{
"iss": "https://<your domain>/",
"aud": "<your domain>",
"sub": "B67425562B52417FAB73",
"iat": 1590440782,
"exp": 1590450969,
"scope": "<API endpoint>",
"tenant": "<tenant-id>"
}Whenever possible, TrustBuilder adopts public claims that have been standardised for JWT tokens, referring for example to https://datatracker.ietf.org/doc/html/rfc7519, https://datatracker.ietf.org/doc/html/draft-bertocci-oauth-access-token-jwt-00#section-2.2.2 and https://datatracker.ietf.org/doc/html/rfc8176. TrustBuilder also added some private claims to reflect its policy model (e.g. persona). Customers can add custom, private claims to represent user profile attributes and derived attributes. By adopting widely supported standards, TrustBuilder ensures compatibility and straight-forward integration with a variety of Providers. Note that the access token is in principle anonymous and therefor does not need to contain any of the OIDC identity claims.
In this example, the claims have following meaning:
iss= issuer, identifying the tenant of the Authorisation Server [always present]aud= audience, i.e. the realm the access token is intended for and can be trusted [always present]sub= subject identifier, i.e. the unique user-id as known by the tenant of the Identity Management [always present]scope= scope for which authorisation has been granted in terms of CRUD of a Service Provider [always present]iat= time the access token was issued [always present]exp= time when the access token expires and must no longer be relied upon [always present]
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.
References
https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication