JWT Authentication Use case and Workflow
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.
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.
2. Enforce the Identify and authorize application policy on the API.
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.
The following internal APIs are used for user and application authentication.
getJsonWebtoken
Used for user authentication without custom claims
User authentication happens using the basic auth credentials of any valid IS user.
Method : GET
URL: http://host:port/rest/pub/apigateway/jwt/getJsonWebToken
This endpoint can be used to create a JWT without custom claims
Used for application authentication with custom claims.
If you want to add the custom claims in the JWT then you can use this URL with the payload specifying the custom claims.
The application is authenticated using the application identifiers supplied in the request, such as, APIKey or Username or Host name, and then a token is generated with application id as a subject.
Method: POST
URL: http://host:port/gateway/security/getJsonWebToken
This endpoint can be used to create a JWT with custom claims
Payload
{
"claimsSet": {
"customclaim1": "name",
"customclaim2":"company name"
}
}
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.
2. Enforce the Identify and authorize application policy on the API.
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.
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.
