JSON Web Token (JWT)

JSON Web Tokens (JWT) are an open standard, which is defined in JSON Web Token (JWT) Specification RFC 7519. They securely represent claims between two parties. Claims can be related to any business process but are typically used to represent an identity and its associations. For example, a user whose identity the JWT represents belongs to an administrator role or group.

For an introduction to JWT, see JWT (RFC 7519).

The claims in a JWT are encoded as a JSON object and are normally digitally signed with a Message Authentication Code (MAC). The most common scenario for using a JWT is authentication. When the user is logged in, each subsequent request includes the JWT, which allows the user to access services that are permitted by that token.

To see which CICS® access methods support JWT, see Which authentication method can I use with which access method?.

Why use JWT?

Advantages of using JWTs include the following:
  • They are lightweight and easy to use by client applications: for example, mobile applications.
  • They are self-contained, which means that the Liberty JVM server can consume the token directly and use a claim from the token as the identity for running the request.
  • They can be symmetrically signed by a shared secret by using the HMAC algorithm, or asymmetrically by using a private key.
  • They have a built-in expiry mechanism.
  • They can be extended to contain custom claims.
  • They are widely adopted by different Single Sign-On solutions and well-known standards, such as How it works: OpenID Connect.

Anatomy of a JWT

Figure 1 shows that a JWT consists of three parts: a header, payload, and signature.
Header
The header typically consists of two parts: the type of the token, which is JWT, and the algorithm that is used, such as HMAC SHA256 or RSA SHA256. It is Base64Url encoded to form the first part of the JWT.
Payload
The payload contains the claims. There is a set of registered claims, for example, iss (issuer), exp (expiration time), sub (subject), and aud (audience). These claims are not mandatory but recommended to provide a set of useful, interoperable claims. The payload can also include extra attributes that define custom claims, such as employee role. Typically, the subject claim is used to create the OpenID Connect user subject. However, the Liberty JVM server can be configured to use an alternative claim. The payload is Base64Url encoded to form the second part of the JWT.
Signature
To create the signature part, the encoded header and encoded payload are signed by using the signature algorithm from the header. The signature is used to verify that the issuer of the JWT is who it says it is and to ensure that the message wasn't changed along the way.
Figure 1. Anatomy of a JWT
Anatomy of a JWT
Figure 2 shows a typical JWT authentication flow.
  1. The user logs in using credentials.
  2. When the user is authenticated, a JWT is created and returned to the user.
  3. When the user wants to access a protected resource, the client application sends the JWT, typically in the HTTP Authorization header.
  4. The JWT is then used by the application server, such as CICS, to identify the user and allow access to the resource.
Figure 2. JWT authentication flow
JWT authentication flow

Support for JWT in CICS Liberty

A JWT can be used for identity propagation with CICS Liberty. If the subject claim contains a distributed identity, you can configure CICS Liberty to map the distributed identity to a RACF® user ID. You can configure JWT authentication with a Liberty JVM server in a number of different ways, the most common of which include:
  • OpenID Connect Client (OIDC) feature

    CICS Liberty supports OpenID Connect 1.0. You can use the openidConnectClient-1.0 feature to configure a Liberty JVM server to accept a JWT as an authentication token. For more information, see How it works: OpenID Connect.

  • JWT feature

    The Liberty jwt-1.0 feature provides a set of APIs that you can use to work with JWTs. You can use the feature to build or to consume a JWT.

  • Enterprise Java™ Security API

    The Enterprise Java Security API is an Enterprise Java standard service provider API that enables the implementation of authentication mechanisms and identity stores into Enterprise Java web applications. You can develop a custom HTTP authentication mechanism that authenticates a request that uses a JWT.

  • Java Authentication Service Provider Interface for Containers (JASPIC)

    JASPIC is an Enterprise Java standard service provider API that enables the implementation of authentication mechanisms into Enterprise Java web applications. You can develop a custom JASPIC authentication provider that authenticates a request that uses a JWT.

  • Trust Association Interceptor (TAI)

    A Trust Association Interceptor (TAI) is a WebSphere® proprietary service provider API that enables the integration of third-party security service. You can implement a TAI that inspects HTTP requests for a specific security token, for example, a JWT, and validates it. The CICS Liberty server needs to be configured to use the implemented TAI.

Recommended: When you use nonencrypted JWTs, it is highly recommended that you use HTTPS to transport requests that contain a JWT.

Support for JWT in CICS

CICS supports only JWTs created by RACF. With this capability, you can convert basic authentication credentials of a user to a JWT that is then used as a time-limited secure session token. You can validate this secure token on subsequent requests by using the CICS API command, VERIFY TOKEN. This support can also be used to convert an MFA token to a JWT to support the use of MFA tokens on stateless requests that cache credentials. Passwords, passphrases, MFA tokens, and PassTickets are all supported credentials.

If you require HTTPS or SOAP requests to accept a JWT created by RACF, you need to write custom headers.

The following diagram shows a scenario where basic authentication credentials are converted to a JWT for subsequent requests, where user is the user ID and pw is the password.

Figure 3. Converting basic authentication credentials to a JWT
This diagram shows a use case of JWT, where basic authentication credentials are used for the first request. On the subsequent requests, a JWT that is converted from the basic authentication credentials are used.