JWT Authentication Use case and Workflow

Retrieving JWT Token

Retrieving JWT Token with Claim

JSON Web Token is a JSON-based open standard ( RFC 7519) means of representing a set of information to be securely transmitted between two parties. A set of information is the set of claims (claim set) represented by the JWT. A claim set consists of zero or more claims represented by the name-value pairs, where the names are strings and the values are arbitrary JSON values. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure, enabling the claims to be digitally signed. JWTs can be signed using a shared secret (with HMAC algorithm), or a public or private key pair using RSA.

API Gateway can generate a JWT token itself or validate the JWT token generated by a trusted third-party server. API Gateway uses the RSA-based JWT to provide stronger integrity protection to JWTs when API Gateway is the issuer of the token. The JSON-based access tokens contain one or more claims. A claim is any piece of information that serves as an unique identifier, and that the token issuer who generated the token has verified. API Gateway extracts the claims from the JWT, identifies the application and then authorizes access to the protected resource.

Note:
JWT authentication is supported for both REST and SOAP APIs. API Gateway does not support Base64 encoded JWT tokens.

Use case 1: JWT authentication with API Gateway as a JWT issuer

This describes the high level workflow for the scenario where API Gateway can generate the JSON Web Token itself.

1. Configure API Gateway as an internal authorization server.

For a complete procedure on configuring API Gateway as an internal authorization server, see Configuring the Internal Authorization Server.

2. Enforce the Identify and authorize application policy on the API.

Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

3. Associate an application with the API.

You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token. For a complete procedure on creating an application with a strategy, see Creating an Application.

4. Activate the API.

User on invoking the API uses the JWT identification method to access the protected resource.

5. You get the JWT in one of the following ways (with or without claims), which you can pass as a bearer token to invoke the API.

Retrieve JWT Token - For a complete procedure on retrieving a JWT token, see Retrieving JWT Token.

Retrieve JWT Token with Claims - For a complete procedure on retrieving a JWT token with claims, see Retrieving JWT Token with Claim.

Use case 2: API Gateway with an external JWT issuer

This describes the high level workflow for the scenario where API Gateway accepts JSON Web Token generated by a trusted third-party server.

1. Configure an external authorization server.

For a complete procedure on configuring an external authorization server, see Adding an External Authorization Server.

2. Enforce the Identify and authorize application policy on the API.

Ensure to select JWT. For details of the Identify and authorize application policy see, Identify and Authorize Application.

3. Associate an application with the API.

You can create a new application or use an existing one. Ensure that you add the required claims while creating the application, which you would use to validate the access token and the external authorization server that would be the JWT issuer. For a complete procedure on creating an application with a strategy, see Creating an Application. Refer the Authorizations for applications created from API Portal section for information on configuring authorization server for the applications created from API Portal.

4. Activate the API.

User on invoking the API uses the JWT identification method to access the protected resource.

5. Pass the JWT as a bearer token to invoke the API.

JWT Authorization Workflow

The flow of authorization requests and responses between the end user, client application, JWT issuer, and resource server is as depicted in the following figure.

The JWT authorization workflow is as follows:

1. The end user logs in, the client application sends an authentication request to API Gateway or to any third-party JWT issuer, to obtain a JWT token.

2. If API Gateway is the JWT issuer, then it validates the user or the application. If the user or application credentials are valid, API Gateway generates the JSON token using a private key that was specified in the JWT configuration, and sends the generated token to the client.

If the user credentials are invalid, API Gateway returns a specific error response.

3. Client sends the generated JSON token in the HTTP Authorization request header as a Bearer token to access the protected API in API Gateway.

4. API Gateway first identifies the application based on claims from the JWT, then validates the JWT using the public certificate of the issuer (the issuer can be API Gateway or a third-party issuer) and provides access to the protected resources.

If the validation fails, API Gateway returns a specific error response.

Note:
If API Gateway has generated the JSON token, it validates the signature using a public certificate that was specified in the JWT configuration. Else, if the HTTP request is sent from a third-party JWT issuer, API Gateway validates the token using a public certificate or the JWKS URI of the issuer.