Authorization Basics

4 mins read

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.

Want to Try JWT Bearer Flow?

Cloudentity comes with multi-tenant authorization server as a service that supports the JWT Bearer flow.

Launch OAuth Server
Learn More

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

[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 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 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.

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

Updated: Sep 8, 2023