How to configure JWT authentication

Configure a z/OS® Connect Server to perform authentication by using a JSON Web Token (JWT).

zosConnect-2.0 Applies to zosConnect-2.0.

This task is applicable when using z/OS Connect as an API provider.

Before you begin

You should be familiar with the information in API provider third-party authentication.
You must have an X.509 certificate that contains the public key of the private key that signed the JWT. This key is used to validate the JWT signature. Consult the security administrator of the JWT issuer for how to obtain a suitable X.509 certificate.
You need to know the claims that are present in the JWT.
You must have completed the task How to activate and configure the SAF user registry to configure the IBM® z/OS Connect Server to use z/OS authorized services and a SAF user registry.
You must have write access to the server.xml configuration file.

About this task

Configure a z/OS Connect Server to perform JWT authentication and use the identity in the JWT to authorize access to z/OS Connect. This configuration uses the OpenID Connect Client feature of WebSphere® Application Server Liberty Profile to accept the JWT as an authentication token.

This task makes the following assumptions:

The JWT is sent to z/OS Connect in an HTTP Authorization request header field as a Bearer token.
The RS256 algorithm is used to sign the JWT.
RACF® is used for authorizing access to z/OS Connect. The identity in the JWT claims may be a RACF user ID, or may be an LDAP user ID that has been mapped to a RACF user ID.
Note: If the identity in the JWT is not a RACF user ID, it can be mapped to a different identity in the z/OS Connect Server's SAF RACF user registry by using a distributed identity filter. To configure this filter, follow the instructions in optional step 6.

Configure the z/OS Connect Server to require authentication by setting the attribute requireAuth="true". This setting also enables the authorization check to ensure that the authenticated user has authority to access z/OS Connect, so you assign RACF user registry users to the zosConnectAccess role.

An example of JWT is shown in Figure 1. For a full description of a JWT, see Anatomy of a JWT.

Figure 1. A sample JWT, showing the header, payload, and signature

{ "alg": "RS256" }.
{ "iss": "idg",
  "sub": "EMPLOY1",
  "aud": "myentity",
  "exp": 1496230040,
  "iat": 1496229740 }.
RSASHA256signature....

The following values are used:

The header contains an alg (algorithm) with the value RS256, which is the hashing algorithm that was used to sign the JWT. RS256 is RSA Signature with SHA-256.
The iss (issuer) claim idg identifies the principal that issued the JWT. In this example, the JWT was issued by IBM DataPower®, which uses idg as its default issuer value.
The sub (subject) claim EMPLOY1 is an identity. If the identity is a RACF user ID, it can be used directly for authorization control. If the sub claim does not contain a RACF user ID, it is possible to map the identity to a RACF user ID and then use the mapped user ID for authorization control.
The aud (audience) claim myentity identifies the intended recipient of the JWT. The aud claim is optional. It can be used to identify a specific z/OS Connect Server, 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. This is expressed as a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds.
The iat (issued at) claim identifies the time at which the JWT was issued. This is expressed as a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds.
The signature (not shown) is calculated by using the header and the payload. The signature certifies that only the party holding the private key is the one that created and signed the JWT, and it also verifies that the claims have not been tampered with.

Note:

If a JWT contains a jti (JWT ID) that is identical to a JWT previously used for authentication with a z/OS Connect Server, the request is considered to be a replay attack. A jti is an optional claim.
If the JWT has been issued by a JWT provider that supports JWK (JSON Web Key) or has been signed by using the HMAC-SHA256 algorithm, then some steps in this procedure must be modified. For more information, see Alternative configuration when using JWK or the HS256 algorithm.
Only JWS type tokens are supported, not tokens of type JWE.

Procedure

Add the openidConnectClient-1.0 Liberty feature to the featureManager element in the server.xml configuration file.
For example,
```
<featureManager>
    ...
    <feature>openidConnectClient-1.0</feature>
</featureManager>
```
Configure the server to use JWT authentication.
Add the openidConnectClient element to the server.xml configuration file. For example:
```
<openidConnectClient 
    id="RS"
    clientId="RS-JWT-ZCEE"
    inboundPropagation="required"
    signatureAlgorithm="RS256" 
    trustStoreRef="JWTTrustStore"
    trustAliasName="JWTTrustCert" 
    userIdentifier="sub"
    mapIdentityToRegistryUser="true"
    issuerIdentifier="idg"
    disableLtpaCookie="true"
    audiences="myentity"
/>
```
This element uses the following values:
- id and clientId are element identifiers.
- inboundPropagation is set to required to allow z/OS Connect to use the received JWT as an authentication token.
- signatureAlgorithm specifies the algorithm to be used to verify the JWT signature. z/OS Connect supports 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 is the label or alias of the certificate to be used for signature validation.
- userIdentifier indicates the claim to use to create the user subject. This identity is then used as the authenticated user ID. The default claim to use for the user subject is the sub claim.
- mapIdentityToRegistryUser indicates whether to map the retrieved identity to a user ID in the user registry. The retrieved identity is the value of the claim that is specified on the userIdentifier attribute. This example sets mapIdentityToRegistryUser="true" to lookup the RACF user ID, EMPLOY1, from the sub claim in the RACF user registry.
- issuerIdentifier defines the expected issuer (iss). This must match the issuer claim value in the JWT. If the z/OS Connect Server receives JWTs with different iss claim values, this value can be a comma-separated list of expected iss values.
- disableLtpaCookie indicates whether an LTPA token should be created. We do not want an LTPA token to be created so we set disableLtpaCookie="true".
- audiences defines a comma-separated list of target audiences. The aud (audience) claim in the JWT must match one of the defined audiences.
For more information about other openidConnectClient attributes, see OpenID Connect Client (openidConnectClient) in the WebSphere Application Server Liberty documentation.
Configure 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 containing the public key must be stored in the z/OS Connect Server’s store in the z/OS Connect Server's truststore.
1. Add a keyStore element to the server.xml configuration file for the truststore.
  The id attribute value of the keyStore element must match the value that is specified on the trustStoreRef attribute of the openidConnectClient element. The keyStore can be a PKCS12 keystore or a RACF key ring.
  For example, to reference a PKCS12 truststore:
```
<keyStore id="JWTTrustStore"
    location="${server.config.dir}/resources/security/myTrustStore.p12"
    password="mypassword"
    readOnly="true"
    type="PKCS12" />
```
  Or, to reference a RACF truststore:
```
<keyStore id="JWTTrustStore"
    fileBased="false"
    location="safkeyring:///myKeyRing"
    password="mypassword"
    readOnly="true"
    type="JCERACFKS" />
```
  For more information about the keyStore element see Server configuration in the WebSphere Application Server Liberty documentation.
2. Add the X.509 certificate that contains the public key that is required to validate the JWT signature into the truststore as a trusted certificate.
  If you use a RACF key ring, connect the X.509 certificate that contains the public key to the RACF key ring with a usage of CERTAUTH.
Add an SSL configuration element.
To use the openIdConnectClient element for JWT inbound propagation from z/OS Connect 3.0.53, the server.xml file must contain a valid SSL configuration. If the server.xml configuration file already contains a valid SSL repertoire element you can skip this step. Otherwise, configure an SSL repertoire element and associate it with the truststore that is configured in the step 3.
Create an SSL repertoire element in the server.xml configuration file, to reference the truststore.
For example,
```
<ssl id="JWTSSLConfig"
        keyStoreRef="JWTTrustStore"/>
        trustStoreRef="JWTTrustStore"/>
```
where both the keyStoreRef and trustStoreRef attributes reference the truststore. A separate keystore is not required to authenticate the JWT, but the keyStoreRef attribute is mandatory and must reference a valid keyStore element.
Optional: If JWT authentication is required only for a subset of requests to the z/OS Connect Server, the openidConnectClient element can include an authFilter subelement that represents conditions that are matched against the HTTP request.
If an openidConnectClient element is configured, then by default, all requests are authenticated by using that configuration. If authentication filters are defined, then only requests that meet the condition that is defined in the authentication filter will be authenticated by using that element. For example, if JWT authentication is required for all requests except those using the z/OS Connect RESTful administration interface, the following authentication filter can be configured as a subelement of the openidConnectClient element used:
```
<authFilter><requestUrl matchType="notContain" urlPattern="/zosConnect/"/></authFilter>
```
For more information about authentication filters, see Authentication Filter (authFilter) in the WebSphere Application Server Liberty documentation.
For more information about configuring the OpenID Connect Client feature with Liberty z/OS, see Configuring JSON Web Token authentication for OpenID Connect in the WebSphere Application Server Liberty documentation.
Optional: If the identity in the JWT is not a RACF user ID, it can be mapped to a different identity in the z/OS Connect Server's SAF RACF user registry by using a distributed identity filter. Follow the steps in Mapping a distributed identity claim to a SAF user ID to create a filter.
Ensure that the server is configured to require authentication for the request.
This configuration can be set at various scopes:
- To require authentication globally for the server, set requireAuth="true" on the zosconnect_zosConnectManager element in the server.xml configuration file. For example:
```
<zosconnect_zosConnectManager
    requireAuth="true" ... />
```
- To require authentication for a specific API, which takes precedence over the global server setting, set requireAuth="true" on the zosConnectAPI element in the server.xml configuration file. For example:
```
<zosconnect_zosConnectAPIs>
    <zosConnectAPI name="Api1" requireAuth="true"/>
</zosconnect_zosConnectAPIs>
```
- To require authentication for a specific service, which takes precedence over the global server setting, set requireAuth="true" on the service element in the server.xml configuration file. For example:
```
<zosconnect_services>    
    <service name="Service1" requireAuth="true"/>
</zosconnect_services>
```
For more information about these elements, see zosConnect-2.0 Configuration elements in the Reference section.
Assign the authenticated user ID associated with the JWT to the zosConnectAccess role to authorize it to access z/OS Connect.
Follow the steps in the task How to configure the zosConnectAccess role with a SAF user registry.

Results

A JWT is used to authenticate an API request to a z/OS Connect Server. The identity in the JWT is used for authorization control.

What to do next

You might be interested in configuring more specific authorization. See the task How to configure authorization levels with a SAF user registry.

Alternative configuration when using JWK or the HS256 algorithm

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

Procedure

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, define the shared secret key on the clientSecret attribute.