Configuring JWT authentication

Use the OpenID Connect Client feature to configure a Liberty JVM server to accept a JSON Web Tokens (JWT) as an authentication token for a specific web application. You can then run the CICS task with a RACF user ID mapped from a claim in the JWT.

Before you begin

You must be familiar with the information in Third-party authentication.

You must complete several other tasks:

Enable the CICS Liberty security feature (cicsts:security-1.0).
Complete the task Configuring and starting the Liberty angel process.
Complete the task Connecting a Liberty JVM server to the angel process.
Complete the task Configuring RACF for identity propagation.

You need to know the claims that are present in the JWT.

You must have:

An X.509 certificate that contains the public key for JWT signature validation. Consult the security administrator of the JWT issuer for how to obtain a suitable X.509 certificate.
Write access to the server.xml configuration file.

About this task

In this task, you configure a Liberty JVM server to perform JWT authentication and then use the identity in the JWT for running the CICS task.

This task assumes:

The JWT is sent to CICS in an HTTP Authorization request header field.
The RS256 public/private algorithm is used to sign the JWT.
The identity in the JWT subject claim is a distributed identity.
RACF is used for the user registry, storing certificates and for authorizing access to the CICS transaction.
The application is deployed as a CICS bundle so all authenticated users are automatically authorized to run the application in Liberty. For more information, see Deploying a Enterprise Java application in a CICS bundle to a Liberty JVM server.

Figure 1 shows an example JWT that is used for authentication.

Figure 1. Example JWT used for authentication

The header contains the algorithm that is used, such as HMAC SHA256 or RSA SHA256, and is Base64Url encoded to form the first part of the JWT.

The payload contains the claims. The payload contains a set of predefined 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 additional attributes that define custom claims such as employee role. Typically, the sub claim is used to create the OpenID Connect user subject.

In the previous example:

The iss (issuer) claim idg identifies the principal that issued the JWT.
The sub (subject) claim is the identity cn=JeanLeclerc,ou=employees,o=ibm,c=fr.

The aud (audience) claim urn:myEntity identifies the recipient that the JWT is intended for.

Important: The aud claim is optional. It can be used to identify a target application, a commercial entity, or any other entity defined by business processes.

The exp (expiration time) claim identifies the expiration time on or after which the JWT must not be accepted for processing.
The iat (issued at) claim identifies the time at which the JWT was issued.

The payload is Base64Url encoded to form the second part of the JWT.

To create the signature part the encoded header and 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.

Important: If the JWT is issued by a JWT provider that supports JWK (JSON Web Key) or is signed by using the HMAC-SHA256 algorithm, then some steps in this procedure must be modified. For more information, see Alternative configuration when you use a JWK or the HS256 algorithm.

Procedure

Configure a RACF key ring as a truststore that is used to validate the JWT signature. In this example, a private key is used to sign the JWT so the X.509 certificate that contains the public key must be stored in the Liberty JVM server truststore.
Add the X.509 certificate that contains the public key that is needed to validate the JWT signature into a RACF key ring as a trusted certificate. Connect the X.509 certificate with a usage of CERTAUTH.
Enter the following command:
```
RACDCERT ID(CICS1) CONNECT(RING(myKeyRing) LABEL('jwtValidate') CERTAUTH)
```
The command uses the following values:
- CICS1 is the CICS region user ID.
- myKeyRing is the name of the key ring.
- jwtValidate is the label or alias of the certificate to be connected to the key ring.
  - Add a keyStore element to the server.xml configuration file for the truststore.
The id attribute value of the trustStore element must match the value that is specified on the trustStoreRef attribute of the openidConnectClient element, for example:
```
<keyStore id="JWTTrustStore" fileBased="false"    location="safkeyring://CICS1/myKeyRing"
        password="myPassword"     readOnly="true"
        type="JCERACFKS" />
```
If you are running Java 11, the location must be location="safkeyringjce://CICS1/myKeyring". For more information about keystore, see Keystores in the IBM WebSphere Application Server for z/OS Liberty documentation.
Add the openidConnectClient-1.0 Liberty feature to the server.xml file.
Configure the <openidConnectClient> element in the server.xml to use JWT authentication, for example:
```
<openidConnectClient id="RS"
        clientId="RS-JWT-CICS" inboundPropagation="required"
          signatureAlgorithm="RS256" trustStoreRef="JWTTrustStore"
          trustAliasName="JWTTrustCert" userIdentifier="sub"
          mapIdentityToRegistryUser="false" issuerIdentifier="idg"
          audiences=”urn:myEntity”/>
```
In this example:
- id and clientId are element identifiers.
- inboundPropagation is set to required to allow Liberty JVM server to use the received JWT as an authentication token.
- signatureAlgorithm specifies the algorithm to be used to verify the JWT signature.
CICS Liberty supports the RS256 (asymmetric algorithm) and HS256 (symmetric algorithm).
- trustStoreRef specifies the name (in the id attribute) of the keystore element that defines the location of the validating certificate.
- trustAliasName gives the alias or label of the certificate to be used for signature validation.
- userIdentifier indicates the claim to use to create the user subject. The default claim to use for the user subject is the sub claim.
- mapIdentityToRegistryUser indicates whether to map the retrieved identity to the registry user. You set mapIdentityToRegistryUser as false because the identity in the sub claim is not a RACF user ID.
- issuerIdentifier defines the expected issuer.
- audiences defines a comma-separated list of target audiences (the audience in the JWT must match one of the defined audiences)
For more information about other openidConnectClient attributes, see the WebSphere Application Server for z/OS Liberty IBM Documentation topic OpenID Connect Client (openidConnectClient).
Important: If JWT authentication is needed only for a subset of requests to the Liberty JVM server, the openidConnectClient element can include an authFilter attribute that represents conditions that are matched against the HTTP request.

For more information about authentication filters, see Authentication Filter (authFilter).
Set the attribute mapDistributedIdentities="true" on the safCredentials element in the server.xml configuration file.
For example,
```
<safCredentials mapDistributedIdentities="true" suppressAuthFailureMessages="false"/>
```
Activate the RACF IDIDMAP class. Enter the following RACF command:
```
SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)
```
Define a distributed identity filter in RACF to map the distributed user ID from the JWT subject claim to a RACF user ID.
For example, enter the following command:
```
RACMAP ID(EMPLOY1) MAP USERDIDFILTER(NAME('cn=JeanLeclerc,ou=employees,o=ibm,c=fr')) REGISTRY(NAME('*')) WITHLABEL('Mapping Jean Leclerc')
```
In this example, the following values are used:
- cn=JeanLeclerc,ou=employees,o=ibm,c=fr is the distributed user ID from the JWT subject claim.
- EMPLOY1 is the RACF user ID to which the distributed user ID is to be mapped.
- REGISTRY(NAME('*')) matches any registry realm name. Alternatively, to match a specific realm, replace the * with the value that is specified on the realmName attribute of the openidConnectClient element.
Important: This example shows a one-to-one mapping. z/OS Identity Propagation also supports many-to-one mappings. For example, you might use a many-to-one mapping to map all employees to the same RACF user ID.

For more information about the RACMAP command, see RACMAP (Create, delete, list, or query a distributed identity filter) in the z/OS Security Server RACF Command Language Reference.
Refresh the RACF IDIDMAP class.
For the changes to take effect, enter the following RACF command:
```
SETROPTS RACLIST(IDIDMAP) REFRESH
```

For more information about configuring the OpenID Connect Client feature with Liberty z/OS, see Configuring JSON Web Token authentication for OpenID Connect.

Results

A JWT is used for authenticating a request to a Liberty JVM server. The distributed identity in the JWT is mapped to a RACF user ID, and the RACF user ID is then used for running the CICS task.

You can use the CICS® security request recording (SRR) feature from within CICS Explorer® to validate this example. With the Regions view in focus, you select the Add Security Request Recording pop-up menu option. On that window, select the JVM Server tab and set the Transaction ID field to the transaction ID defined by the URIMAP that matches the request (or CJSA by default). For more information, see Checking that a CICS security configuration example is working by using the SRR.

Alternative configuration when you use a JWK or the HS256 algorithm

If the JWT is issued by a JWT provider that supports JWK (JSON Web Key) or is signed by using the HMAC-SHA256 secret key algorithm, then a truststore is not necessary. However, you must specify different attributes on the openidConnectClient element.

Alternate process

If the public key is retrieved from a JWK endpoint, you specify the JWK endpoint URL on the jwkEndpointUrl attribute.
If the JWT is signed by using a shared secret key with the HMAC-SHA256 algorithm, you define the shared secret key on the sharedKey or clientSecret attributes.

For information about these alternative openidConnectClient attributes, see the WebSphere Application Server for z/OS Liberty IBM Documentation topic OpenID Connect Client (openidConnectClient).