JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens

4 min readOct 31, 2021

Last year I did an analysis on the draft specification of the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens. In this month, the RFC for the specification(rfc9068) is officially released. Therefore let me share some interesting facts that I have identified, based on the authorization servers perspective in the newly released JWT Profile for OAuth 2.0 Access Tokens specification.

Why do we need this specification…

Eventhough the specification(rfc7519) of OAuth 2.0 Authorization Framework does not mandate any specific format for access tokens, in-market use, many commercial OAuth 2.0 implementations issue access tokens using a format that can be validated by resource servers directly, without the authorization server involvement.

This specification targets to standardize the JWT access token layouts going forward. The following areas have been mainly focused through this specification.

Define a set of mandatory and optional claims, the profile provides
How authorization request parameters determine the content of the issued JWT access token.
How an authorization server can publish metadata relevant to the JWT access tokens it issues
How a resource server should validate incoming JWT access tokens.
Provides security and privacy considerations to avoid common mistakes.

How JWT Access Token should be…

JWT Access token header

JWT access tokens must be signed using any algorithm where the specification recommends to use asymmetric cryptography. Moreover using “none” for the signing algorithm must not do according to the specification.
The JWT access tokens must include media type in the “typ” header parameter to explicitly declare that the JWT represents an access token complying with this profile. this specification registers the “application/at+jwt” media type, which is to indicate that the content is a JWT access token. The “typ” value used should be “at+jwt” as it is recommended that the “application/” prefix be omitted.

Data Structure

According to the specification expected JWT access token structure can be summarized as follows.

As shown in the above iss, exp, aud, sub, client_id, iat, jti claims are required.

Having authentication information claims of auth_time, acr, amr are optional according to the specification

In the context of authorization grants involving the resource owner, commercial authorization servers will often include resource owner attributes directly in access tokens so that resource servers can consume them directly for authorization or other purposes without any further round trips to introspection or UserInfo endpoints.

Most importantly, If an authorization request includes a scope parameter, the corresponding issued JWT access token should include a “scope” claim.

Let’s request a JWT Access Token

Sample authorization request with resource and scope Parameters

GET /as/authorization.oauth2?response_type=code
           &client_id=s6BhdRkqt3&
           state=laeb
           &scope=openid%20profile%20reademail
           &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
           &resource=https%3A%2F%2Frs.example.com%2F HTTP/1.1
        Host: authorization-server.example.com

The JWT access token that can be obtained from above request would be as follows:

Header  
   {  
        "typ":"at+JWT",
        "alg":"RS256",
        "kid":"RjEwOwOA"
   }JWT Claim Set
   {
        "iss": "https://authorization-server.example.com/",
        "sub": "5ba552d67",
        "aud":   "https://rs.example.com/",
        "exp": 1639528912,
        "iat": 1618354090,
        "jti" : "dbe39bf3a3ba4238a513f51d6e1691c4",
        "client_id": "s6BhdRkqt3",
        "scope": "openid profile reademail"
   }

Validating JWT Access Tokens

As mentioned it is recommended, authorization servers to sign JWT access tokens with an asymmetric algorithm. Authorization servers should use OAuth 2.0 Authorization Server to advertise to resource servers their signing keys via “jwks_uri” and what “iss” claim value to expect via the “issuer” metadata value. If an authorization server supports both OAuth 2.0 Authorization Server Metadata and OpenID Connect discovery, the values provided must be consistent across the two methods.

An authorization server may elect to use different keys to sign
OpenID Connect ID Tokens and JWT access tokens.

This specification does not provide a mechanism for identifying a specific signing key as the one used to sign JWT access tokens. An authorization server can sign JWT access tokens with any of the keys advertised via authorization server (AS) metadata or OpenID Connect discovery.

In case of any failure in the validation checks, the authorization server response must include the error code “invalid_token”.

Highlights of Security and Privacy Considerations

Authorization servers should prevent scenarios where clients can affect the value of the “sub” claim in ways that could confuse resource servers.
To preventing cross-JWT confusion, authorization servers MUST use a distinct identifier as “aud” claim value to uniquely identify access tokens issued by the same issuer for distinct resources.
Authorization servers should not rely on the use of different keys for signing OpenID Connect ID Tokens and JWT tokens as a method to safeguard against the consequences of leaking specific keys.

These are some of the highlights that I have identified by going through the newly released JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens specification(rfc9068). Moreover I have analyzed the WSO2 Identity server’s impementation of JWT token issuer and that is pretty much compliant to the newly released specification and required some minor changes to fully compliant with the spec which has been already tracked here by the WSO2 Identity Server team. From here, you can refer the JWT token Issuer, which has been implemented for WSO2 identity Server.

Happy Reading!!!