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.
- 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.
- The header contains an
alg
(algorithm) with the valueRS256
, 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 usesidg
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. Theaud
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.
- 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.
- 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.
- Only JWS type tokens are supported, not tokens of type JWE.
Procedure
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
Alternative configuration when using JWK or the HS256 algorithm
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.