API provider third-party authentication

Authenticating with a JSON Web Token

JSON Web Tokens are an open industry standard for securely representing claims between two parties. Claims are statements about an entity. For example, what identity was used by a user login, or any other type of claims as required by business processes, such as, the user is an administrator.

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

Anatomy of a JWT

A JWT consists of three parts: a header, payload, and signature, as shown in Figure 2.

The header typically consists of two parts: the type of token, which is JWT, and the hashing algorithm that is used to sign the JWT, such as HMAC SHA256 or RSA SHA256. The header is Base64Url encoded to form the first part of the JWT.

The payload contains the claims. A set of predefined claims is provided. For example, iss (issuer), sub (subject), aud (audience), and exp (expiration time). These claims are not mandatory but should be included to provide a set of useful, interoperable claims. The payload can also include other attributes that define custom claims such as employee role. Typically, the subject claim is used to create the OpenID Connect user subject. However, IBM z/OS Connect can be configured to use an alternative claim, if required. The payload is Base64Url encoded to form the second part of the JWT.

To create the signature, the encoded header, encoded payload, and a secret are signed by using the signature algorithm that is specified in the header alg parameter. The signature is used to verify the issuer of the JWT and to ensure the integrity of the message.

IBM z/OS Connect does not support JSON Web Encryption (JWE), but you can use HTTPS to encrypt the complete message (including the JWT).

OpenID Connect

You can enable open secure APIs by using standards such as OAuth, an open standard for authorization, and OpenID Connect, an identity protocol that is built on the OAuth 2.0 protocol. OpenID Connect enables client applications to rely on authentication that is performed by an OpenID Connect Provider. The client application retrieves an ID token in the form of a JWT from the OpenID Connect Provider. The token is used to access a resource on behalf of the user. See Figure 3

The diagram in Figure 3 shows the following steps:

1. The user makes a request to the client application.
2. The client application redirects the request to the OpenID Provider (OP).
3. The OP sends an authentication and authorization request to the user.
4. The user authenticates and authorizes the client application to access the resource.
5. The OP sends a grant code to the client application.
6. The client application sends a request to the OP to exchange the grant code for an ID token in the form of a JWT, access token, and refresh token.
7. The OP sends the ID token (JWT), access token and refresh token to the client application.
8. The client application makes the request to the Resource Server with the JWT, which is used for authenticating the user and authorizing access to the resource.
9. The response is sent from the Resource Server to the client application.
10. The response is sent from the client application to the user.

IBM z/OS Connect supports OpenID Connect 1.0 as a Resource server that can accept a JWT as an authentication token.

Liberty z/OS supports OpenID Connect 1.0 and can play a role as an OpenID Connect Client, Provider, or Resource Server. For more information about configuring support for OpenID Connect with Liberty, see Using OpenID Connect in the WebSphere Application Server for z/OS Liberty documentation.

JWT authentication methods

Using the OpenID Connect Client feature

To configure a IBM z/OS Connect server to accept a JWT as an authentication token, enable the openidConnectClient-1.0 feature and set the inboundPropagation attribute of the openidConnectClient element to required. You can also specify additional JWT configurations, such as authentication filters and claim-to-subject mapping.

Any trusted party in possession of a JWT can use that token to get access to the APIs hosted by IBM z/OS Connect. The IBM z/OS Connect server validates the JWT and creates the authenticated subject from the token. To be accepted as an authentication token, the JWT must contain iss, sub, and exp claims and be signed with the RS256 or HS256 algorithm.

You can configure IBM z/OS Connect to accept a JWT as an authentication token either as part of an OpenID Connect flow, or from any intermediate server, such as an API Gateway.

A JWT might contain privacy-sensitive information, so take precautions to prevent disclosure of this information to unintended parties. For example, use Transport Layer Security (TLS) when transporting the token. Extra trust can be established by accepting a JWT only as an authentication token across a TLS mutually authenticated connection.

For more information, see How to configure JWT authentication.

Authentication filters

If JWT authentication is required only for a subset of requests to the IBM z/OS Connect server, then authentication filters can be used to restrict which requests the JWT authentication applies to. Authentication filters specify conditions that are matched against the HTTP request and are configured by using an authFilter element in the server.xml configuration file. This authFilter element can be configured as a subelement of the openidConnectClient element, or specified as a separate element referenced by the authFilterRef attribute of the openidConnectClient element.

By using authentication filters, you can have different security policies for different requests. For example, you can put a filter on the requestUrl so that the openidConnectClient element applies only to requests that match that URL. Another example is to put a filter on the remoteAddress element so that different certificates can validate the signature of the JWT depending on the server that sends the request.

<authFilter id="JwtAuthFilter">
    <requestHeader id="authHeader" name="Authorization" value="Bearer" matchType="contains"/>
</authFilter>

To ensure that any requests containing a Basic token can fail over to use basic authentication, configure the following element:

<webAppSecurity allowFailOverToBasicAuth="true"/>

For more information, see Authentication Filter (authFilter) and Authentication Filters in the WebSphere Application Server for z/OS Liberty documentation.