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.
- 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
Authorizationheader. 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
- Implement JWT for the API request. The following excerpt from the
server.xml file shows an example configuration for requesting a
<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_authTokenelement must be specified with a name other than
Authorizationbecause the HTTP
Authorizationheader 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
For more information about implement OAuth 2.0, see Calling an API secured with OAuth 2.0.
<zosconnect_oAuthConfig id="myoAuthConfig" grantType="password" authServerRef="myAuthServer" />
- Reference both the JWT and OAuth configuration on the endpoint connection, for
<zosconnect_endpointConnection id="conn" host="https://api.server.com" port="8000" authenticationConfigRef="myoAuthConfig,myJWTConfig" />