How to configure JWT authentication

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

This task is applicable when using IBM 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 will be 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 IBM z/OS Connect server to perform JWT authentication and use the identity in the JWT to authorize access to IBM 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 IBM 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 IBM 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 IBM 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 IBM 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 IBM z/OS Connect, so you assign RACF user registry users to the zosConnectAccess role.

An example 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 IBM 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 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:
  1. If a JWT contains a jti (JWT ID) that is identical to a JWT previously used for authentication with a IBM z/OS Connect server, the request is considered to be a replay attack. A jti is an optional claim.
  2. If the JWT has been issued by a JWT provider which supports JWK (JSON Web Key) or has been signed 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.
  3. Only JWS type tokens are supported, not tokens of type JWE.

Procedure

  1. 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>
  2. 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 IBM z/OS Connect to use the received JWT as an authentication token.
    • signatureAlgorithm specifies the algorithm to be used to verify the JWT signature. IBM 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 IBM 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 for z/OS Liberty documentation.
  3. 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 IBM z/OS Connect server’s stored in the IBM 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 specified on the trustStoreRef attribute of the openidConnectClient element. The keyStore can be a Java™ KeyStore (JKS) or a RACF key ring.
      For example, to reference a JKS truststore:
      <keyStore id="JWTTrustStore"
    location="${server.config.dir}/resources/security/myTrustStore.jks"
    password="mypassword"
    readOnly="true"
    type="JKS" />
      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 IBM WebSphere Application Server for z/OS Liberty documentation.
    2. Add the X.509 certificate that contains the public key 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.
  4. Add an SSL configuration element.
    To use the openIdConnectClient element for JWT inbound propagation from IBM z/OS Connect V3.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 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.
  5. Optional: If JWT authentication is required only for a subset of requests to the IBM 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 will be authenticated using that configuration. If authentication filters are defined, then only requests which meet the condition defined in the authentication filter will be authenticated using that element. For example, if JWT authentication is required for all requests except those using the IBM 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 for z/OS 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.

  6. Optional: If the identity in the JWT is not a RACF user ID, it can be mapped to a different identity in the IBM 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.
  7. 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 Configuration elements in the Reference section.
  8. Assign the authenticated user ID associated with the JWT to the zosConnectAccess role to authorize it to access IBM z/OS Connect.
    Follow the steps in task How to configure the zosConnectAccess role with a SAF user registry.

Results

A JWT is used to authenticate an API request to a IBM 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 which 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

  1. If the public key is retrieved from a JWK endpoint, you specify the JWK endpoint URL on the jwkEndpointUrl attribute.
  2. 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.