JWT Authentication use case and workflow

Edit online

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.

webMethods API Gateway can generate a JWT token itself or validate the JWT token generated by a trusted third-party server. webMethods API Gateway uses the RSA-based JWT to provide stronger integrity protection to JWTs when webMethods 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. webMethods 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 webMethods API Gateway as a JWT issuer

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

  1. Configure webMethods API Gateway as an internal authorization server. For a complete procedure on configuring webMethods API Gateway as an internal authorization server, see Configuring an 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 .
  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 . For information on configuring authorization server for the applications created from Developer Portal, see Authorizations for applications created from Developer Portal .
  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://hostname/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://hostname/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: webMethods API Gateway with an external JWT issuer

This describes the high level workflow for the scenario where webMethods 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 .
  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 JWT authorization workflow is as follows:

  1. The end user logs in, the client application sends an authentication request to webMethods API Gateway or to any third-party JWT issuer, to obtain a JWT token.
  2. If webMethods API Gateway is the JWT issuer, then it validates the user or the application. If the user or application credentials are valid, webMethods 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, webMethods 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 webMethods API Gateway.
  4. webMethods 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 webMethods API Gateway or a third-party issuer) and provides access to the protected resources. If the validation fails, webMethods API Gateway returns a specific error response.
    Note:
    • If webMethods 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, webMethods API Gateway validates the token using a public certificate or the JWKS URI of the issuer.
    • When a Policy violation event is logged in case of expired JWT tokens, the application is associated as the identified application since the identification happens before the expiry is checked.