Calling an API secured with OAuth 2.0 and a JWT

IBM® z/OS® Connect API requester provides the capability that allows a CICS® to call a RESTful API that is secured by using both JWT and OAuth 2.0, where JWT is used to authenticate a client, and OAuth 2.0 is used to authorize the client to access the API.

In a IBM z/OS Connect API requester scenario, IBM z/OS Connect acts as the client to request both a JWT (from an external authentication server) and an access token and access the RESTful API with the two kinds of tokens on behalf of the CICS application.

Figure 1 shows how a JWT and an access token are obtained and used to access an API when a user wants to call an API from the z/OS application.

Diagram showing how a JWT and an OAuth access token are used by IBM z/OS Connect for the API request authentication and authorization.

Figure 1. Illustration of how JWT and OAuth 2.0 are applied to API requester

Note: You can also use the same server to provide multiple token types.

The communication stub transfers an API request that contains credentials from the z/OS application to the IBM z/OS Connect server.
- For JWT authentication, the credentials include a user name and password.
- For OAuth authorization, the type of information that is included in the credentials depends on the grant type that is used. For example, if the Resource Owner Password Credential grant type is used, the credentials must contain a user name and password and a client ID and client secret. For more information about the OAuth grant types that are supported by the API requester, see Calling an API secured with OAuth 2.0.
The IBM z/OS Connect server sends an HTTPS request for a JWT to the authentication server. The HTTPS request contains the user credentials.
The authentication server authenticates the user and returns a JWT to the IBM z/OS Connect server.
The IBM z/OS Connect server sends an HTTPS request that contains the credentials to the authorization server.
The authorization server validates the credentials, verifies the grant scope, and returns an access token to the IBM z/OS Connect server.
The IBM z/OS Connect server sends an HTTP (or HTTPS) request for the API to the request endpoint with the JWT and the access token. The OAuth access token is passed in the HTTP Authorization header. The JWT is passed in a bespoke header that is specified in server.xml.
The request endpoint returns an HTTP (or HTTPS) response.

Steps for implementing JWT and OAuth 2.0 with API requester

To call an API that is secured with both OAuth 2.0 and a JWT from your z/OS application, take the following steps:

Implement JWT for the API request. The following excerpt from the server.xml file shows an example configuration for requesting a JWT.
```
<zosconnect_authToken  id="myJWTConfig"
      authServerRef="myJWTserver" 
      header="JWT-header-name" >
      <tokenRequest credentialLocation="header" 
            header="JWTReqAuthorization" 
            requestMethod="GET" />
      <tokenResponse tokenLocation="header"
            header="JWTResAuthorization" />
</zosconnect_authToken> 
```
The header attribute on the zosconnect_authToken element must be specified with a name other than Authorization because the HTTP Authorization header is used to pass the OAuth access token by default.

For more information about how to implement JWT, see How to enable a z/OS application to call an API secured with a JWT.
Implement OAuth for the API request. The following excerpt from the server.xml file shows an example configuration for requesting an OAuth access token.
```
<zosconnect_oAuthConfig id="myoAuthConfig"
      grantType="password"
      authServerRef="myAuthServer" />
```
For more information about implement OAuth 2.0, see Calling an API secured with OAuth 2.0.

Reference both the JWT and OAuth configuration on the endpoint connection, for example:


<zosconnect_endpointConnection id="conn"       
        host="https://api.server.com"              
        port="8000"     
        authenticationConfigRef="myoAuthConfig,myJWTConfig" />

Important: The authenticationConfigRef attribute can reference one or more elements. Apart from referencing both a zosconnect_authToken and a zosconnect_oAuthConfig element to call an API that is secured with a JWT and OAuth 2.0, IBM z/OS Connect supports other combinations of multiple authentication or authorization methods. For more information, see Calling an API secured with multiple authentication and authorization methods.