Skip to main content

Using JWT Profile for OAuth 2.0 Authorization Flows

Learn how JSON Web Tokens (JWTs) can be utilized to enable sharing identity and security information between independent security domains.

What JWT Bearer Flow Is

JSON Web Token (JWTs) is a JSON-based security token encoding that enables sharing of identity and security data between independent security domains. Such security tokens are usually issued by identity providers and consumed by authorization servers (also referred to as relying parties). The JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC7523) specification defines how JWT bearer tokens can be used to request access tokens from the authorization server while utilizing an already existing trust relationship between a client application (for example, IDP) and an authorization server. Because of the trust relationship between those two entities, authorization server does not require a direct user-approval (consent) step.

JWTs that are not digitally signed or are not valid in all other aspects of a JSON Web Token as defined in the RFC7523 specification are rejected by the authorization server.

How JWT Bearer Flow Works

JWT_Bearer_Flow.svg

  1. Client application requests a JWT from a token service.

    A token service is usually an identity provider. The token service must be registered with the authorization server to establish the trust relationship.

  2. The token service encrypts the JWT using JSON Web Encryption and issues it to the client application.

  3. Client application receives the JWT in the response from the token service.

  4. Client application verifies the JSON Web token.

  5. Client application sends a request to authorization server's /token endpoint.

    The value of the mandatory grant_type parameter must be set to urn:ietf:params:oauth:grant-type:jwt-bearer.

    The value of the assertion parameter must contain a single JWT.

    For reference of all other request parameters of the OAuth 2.0 token endpoint, you can visit SecureAuth API reference.

  6. The authorization server decrypts and verifies the JWT.

  7. The authorization server issues an access token and returns it to the client application.

    Result: From now on, the client application can make request to the APIs protected by the authorization server. The access token the application got in the 7th step is used as a mean to authenticate the client application.

Mandatory Claims for JWT in JWT Bearer Flow

In order to issue access tokens, authorization servers require the following claims to be present in the JWT:

Claim

Full name

Description

Example

iss

issuer

A unique identifier of the entity that issued the JWT, for example, an IDP.

https://{tid}.authz.cloudentity.io/{tid}/{aid} - typical for a SecureAuth issued token

sub

subject

Identifies the principal that is the subject of the JWT. For the authorization grant, it typically identifies an authorized accessor for which the access token is being requested.

your-client-application

aud

audience

It contains information that identifies a given authorization server as an intended audience that is supposed to receive this particular JWT.

https://{tid}.authz.cloudentity.io/{tid}/{aid}/oauth2/token for SecureAuth

exp

expiration time

Used to limit the time window of when the JWT can be used. In other words, it is JWT time to live. In SecureAuth, it's a Unix Timestamp (time in seconds since January 01 1970).

1656316677

iat

issued at

Identifies the time at which the JWT is issued. In SecureAuth, it's a Unix Timestamp (time in seconds since January 01 1970).

1656316677

jti

JWT ID

Unique identifier for the JSON Web Token. Given JWT ID can be used only once.

a9s812jdDq53

JWTs may contain other claims besides the ones that are mandatory. You can either use custom claims, or limit yourself to the ones defined in the RFC7523 specification.

In this section: