Calling an API secured with an OAuth 2.0 token and a JWT

IBM® z/OS® Connect API requester provides the capability that allows a CICS®, IMS or z/OS application to call a RESTful API that is secured by using multiple access tokens.

In this example scenario, IBM z/OS Connect requests both a JWT from an external authentication server and an OAuth 2.0 access token from an authorization server. Both tokens are passed on the request to the RESTful API.

Figure 1 shows an API requester flow where the API endpoint is secured by two access tokens.

Diagram shows an API requester flow where the API endpoint is secured by two access tokens.

Figure 1. Illustration of how multiple access tokens are obtained in an API requester flow

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 OAuth 2.0 authorization server.
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.

Configuration steps

To configure obtaining a token from an OAuth 2.0 authorization server and a JWT authentication server, 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 an access token.
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 implementing OAuth 2.0, see Calling an OAuth 2.0 authorization server.

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 Using API requester to call an API secured with multiple authentication and authorization methods.