Home > Features > OAuth > Grant flows > JWT bearer grant type

Using JWT Profile for OAuth 2.0 authorization grants

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

JSON Web Tokens

To learn about JSON Web Tokens, their structure, and encoding, or to get familiar with some examples, see JSON Web token article.

About using JWTs for authorization

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.

Mandatory claims

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

Claim Full name Description
iss issuer A unique identifier of the entity that issued the JWT, for example, an IDP.
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.
aud audience It contains information that identifies a given authorization server as an intended audience that is supposed to receive this particular JWT.
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.

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.

JWT Bearer flow

[mermaid-begin]
sequenceDiagram autonumber participant app as Client Application participant idp as Token Service (IDP) participant acp as Authorization server (Cloudentity) app->>idp: Request JWT idp->>idp: Encode and issue the JWT idp->>app: JWT app->>app: Verify JWT app->>acp: GET /token note over app, acp: The request contains the JWT the application got from the token service acp->>acp: Verify JWT acp->>app: Access token

  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 estabilish 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 Cloudentity 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.