Table of contents:
1. Introduction
2. What is OpenID Connect?
3. Security scenario: secure an IMS API using OIDC
4. Security solution design
5. Security configuration
6. Testing the scenario
7. Summary

1. Introduction

In the article Using a JWT with z/OS Connect EE we showed how z/OS Connect EE can be used to authenticate REST API requests using a JSON Web Token. This article focuses on an end to end security scenario using OpenID Connect (OIDC).

OIDC is an identity protocol and open standard that is built on top of the OAuth 2.0 protocol. It enables client applications to rely on authentication that is performed by an OIDC Provider to verify claims like the identity of a user. With OAuth 2.0, the security token that is used to authorize a user to access a resource is known as an access token. This token type is ‘opaque’ to applications, that is, applications cannot directly consume the token. With OIDC, the security token used is a JSON Web Token (JWT) which can be consumed directly by applications.

In this article, we show how a user can authenticate with an Open ID Connect Provider and how a JSON Web Token (JWT) can be created and then used for authentication with z/OS Connect EE. We explain how this security model can be used for securing access to an IMS application.

Figure 1 shows an example scenario of exposing an IMS transaction through a REST API with z/OS Connect EE and securing the API using OIDC.

Figure 1 Using OpenID Connect with z/OS Connect EE

2. What is OpenID Connect?

Open ID Connect (OIDC) is an open standard built on top of OAuth 2.0, where the identity of the end user is transmitted to client applications. Before looking more closely at OIDC, let’s review the OAuth 2.0 protocol and how it can be used to authorize access to APIs.

2.1 Background on OAuth 2.0

OAuth 2.0 is an open standard that allows an end user to securely share access to information with a third party. It simplifies the user experience by avoiding the need of managing many different credentials for multiple web sites. The goal of OAuth 2.0 is to enable a web site to request user information from another site, whilst allowing the end user to control access to the information.

OAuth 2.0 achieves two goals:

1. It hides the end user credentials from the OAuth Client (web site you want to share information with). For example, if you allow Stack Overflow to pull information from your Google account, you don’t want Stack Overflow to see your Google user ID and password.
2. It protects the delivery of tokens to registered applications. Only registered applications (Stack Overflow for example) are authorized to obtain OAuth tokens from the OAuth Provider (Google in our example). The end user is not able to request tokens.

In an OAuth flow, there are three involved parties (see Figure 2):

Figure 2 Three legs of the OAuth 2.0 flow

The end user wants to access Stack Overflow using his Google account credentials so he goes to the Stack Overflow web page and selects the Google login method. He is redirected to a Google login page where he enters his Google credentials. Once authenticated, Google asks the end user what type of information he would like to share with Stack Overflow (we call them scopes). To be able to identify the end user and to create the profile in Stack Overflow, the end user needs to share two scopes: email & profile. The email scope will be used by Stack Overflow as the user ID of the end user on the StackOverflow web site.

Here we can see that Stack Overflow does not see the end user’s Google password, and Stack Overflow, not the end user, requests the OAuth access_token from the Google OAuth Provider. Using the access token, Stack Overflow can pull the email address and some basic profile information on behalf of the end user from the Google Resource Server as shown in Figure 3:


Figure 3 OAuth 2.0 servers

Note: The above example is one of the four different possible OAuth flows. It is known as the Authorization Code flow.

2.2 Securing APIs with OAuth 2.0

In the following example we show how OAuth can be used to secure access to an API. In this example, a mobile app is the OAuth Client, the OAuth Provider is a DataPower gateway and the resource is an API managed by an API Gateway.


Figure 4 Securing APIs with OAuth 2.0

Note: We refer to the API managed by the API Gateway as the ‘managed API’, and we refer to the API deployed in z/OS Connect EE as the ‘system API’.

1. The mobile app authenticates with the Authorization End Point of the OAuth Provider API. The mobile app sends a GET request to the Authorization End Point and receives a redirect URI to a login form to allow the end user to enter his credentials securely. The mobile app does not see what’s inside the login form, and only displays it in a web view or in the mobile’s browser. Once the credentials have been validated and optionally the type of information that the end user will share accepted, the Authorization End Point responds to the mobile app with a grant code.
2. The mobile app requests the Token End Point of the OAuth Provider for tokens, with the following information:
   • mobile app credentials
   • grant code

   The Token End Point validates the mobile app credentials and grant code, and sends back an access token and refresh token to the mobile app (see example 1):

   Example 1 Message returned by the Token End Point

   { "token_type": "bearer", "access_token": "AAEkOGFmMDMwMWEtNmMzYi00Y2M4LTg4YTUtNmE1YTkyMDlkOTMz7vov_8EkqITj-9Oe16flYrM23OMo9aXHftIiyzIkDqE3NR7awb3L5BobmKBTDJNsMFCe3Wddk6WB-PKP_X_GFA", "expires_in": 3600, "scope": "resource_A", "refresh_token": "AAGPlkKiWMZROes41plkQImCYAaLs7w3X2qOxSg8-pGIFuk6y7LJNO5yvkT_kX5lEN1iA7SiYDzr6Ywm138pCmGgBbmY0YJV6NMY_mcRpVT2fw" }
3. The mobile app now has the access token to put in the Authorization header to call the managed API in the API Gateway. The API gateway receives the request from the mobile app with the access token in the request. The API gateway then sends the token to the Introspection End Point of the OAuth Provider API which is able to validate the token, and return all the necessary information, such as the username (Jean Leclerc), scopes and validity (see example 2).

4. Example 2 Message returned from the Introspection End Point

   { "active": true, "token_type": "bearer", "client_id": "8af0301a-6c3b-4cc8-88a5-6a5a9209d933", "username": "JeanLeclerc", "sub": "JeanLeclerc", "exp": 1489671363, "expstr": "2017-03-16T13:36:03Z", "iat": 1489667763, "nbf": 1489667763, "nbfstr": "2017-03-16T12:36:03Z", "scope": "resource_A", "client_name": "mobile_app" }

If the access token is valid and if the scope matches with the API scope, the API gateway processes the request, otherwise it refuses the request. At this point, the API Gateway could be configured to forward the access token in the request to the system API deployed in z/OS Connect EE. However, z/OS Connect would need to call an Introspection Endpoint in order to validate the token. We will see in Securing APIs with OpenID Connect that an Introspection Endpoint is not required when we use OIDC.

A note about revocation.The refresh token allows an application to request a new access token when the original access token expires. If the refresh token is still valid and has not been revoked, this process avoids the end user having to re-authenticate. The expiry period of an access token can be several days or more. The expiry period of a refresh token should be longer than that of an access token. You can revoke an access token, so the next time the API gateway asks the Introspection End Point to validate the token, the API gateway will see that the access token has been revoked and will reject the request.

2.3 Securing APIS with OpenID Connect

When using OIDC the ID token is a JWT which contains a header, payload and signature. The payload contains the claims. Claims are statements about an entity (typically, the user) and additional metadata. There is a set of predefined claims, for example: iss (issuer), exp (expiration time), sub (subject) and aud (audience). For more information on using JWTs with z/OS Connect EE see the article Using a JWT with z/OS Connect EE.

In the following example we show how OIDC can be used to secure access to an API. In this example, a mobile app is the OIDC Client, the OIDC Provider is a DataPower gateway and the resource is an API managed by an API Gateway.

Figure 5 Securing APIS with OpenID Connect

The security flow is similar to an OAuth flow except in this case the mobile app retrieves a JWT from the OIDC Provider Token End Point and the JWT is then used to call the managed API managed in the API Gateway. The API Gateway no longer needs to call an Introspection End Point to validate the JWT, and the JWT can be forwarded as an authentication token to z/OS Connect EE. The use of OIDC and a JWT simplifies the end to end security flow. For a description of the exchanged messages and token formats see Testing the scenario.

A note about revocation. In the above scenario, the expiry period of the ID token (JWT) should be short because there is no call to an Introspection Point for each request to check if the user has been revoked. The mobile app uses a refresh token to generate a new ID Token.

3. Security scenario: secure an IMS API using OIDC
In our hypothetical scenario, the user is accessing phone numbers from a mobile app. The phone numbers are stored in an IMS database, and exposed to the mobile app as a phonebook REST API. An API Gateway acts as a proxy of the phonebook API which is deployed in z/OS Connect EE. This scenario is shown in Figure 6:


Figure 6 Security scenario

The security requirements are as follows:

• The user must login using a valid identity and password.
• The user’s credentials must be checked against an LDAP registry.
• The user must be authorized to invoke the API.
• The mobile app must be authorized to invoke the API.
• The user must be authorized to run the IMS transaction.
• Transmitted messages must be secure (private and protected from tampering).
• Open standards must be used to align against the enterprise wide security policy.

4. Security solution design

The security design uses an open security model based on OIDC.

• Authentication will be performed by an OIDC Provider.
• User authorization can be done at one or many enforcement points. However, in order to authorize in the backend system (IMS in our scenario) it will be necessary to map the credentials used for user authentication against the LDAP registry to a user in the RACF registry.
• Application authorization of the mobile app will be done using an API key that is shared through the API Connect Developer Portal with the client application developer.
• System API calls will be authorized in z/OS Connect EE using the Authorization interceptor.
• Confidentiality and integrity will be implemented using TLS (Transport Layer Security).

Figure 7 shows the following set of security controls that are implemented in our security design:

1. The mobile app acts as an OIDC client and obtains security tokens from the OIDC Provider.
2. DataPower is used as the OIDC Provider.
3. An LDAP is used as the user registry for distributed users and groups.
4. The API Connect Gateway performs a number of security functions:
   • Checks the mobile app client ID
   • Validates the JWT:
     • Signature
     • Issuer
     • Audience
     • Expiration
5. z/OS Connect EE performs a number of security functions:
   • Validates the JWT and extracts the distributed identity
   • Calls RACF to map the distributed ID to a RACF user ID
   • Calls RACF to check that the user is authorized to invoke the API
   • Propagates the mapped RACF user ID to IMS
6. RACF is used for the mainframe user registry, mapping distributed IDs to RACF user IDs and for authorizing API calls
7. IMS performs further authorization checks to make sure that the mapped RACF user ID is authorized to access IMS resources

In the remainder of this article we describe an implementation of this security design that uses the capabilities of IBM DataPower, IBM API Connect, z/OS Connect EE, z/OS, IMS Connect and IMS. And then in Testing the scenario we show the different OIDC message flows for a case where an authorized user successfully invokes the API.

5. Security configuration

In this section we show how security controls are configured for each of the components in the solution.

5.1 Mobile app

The mobile developer connects to the API Connect Developer Portal and registers the mobile app to get a client ID, and subscribes to a plan that contains the phonebook API.

Figure 8 shows the security definitions for the phonebook API.


Figure 8 API Connect Developer Portal – phonebook API

The phonebook API is protected with two security definitions:

1. An OIDC Provider – the client needs to send a JWT.
2. An API key – the client needs to send a client ID.

5.2 DataPower – OIDC Provider

DataPower appliances support the OAuth 2.0 protocol. Refer to Introducing OAuth 2.0 support in DataPower for detailed instructions on configuring OAuth 2.0 support with DataPower (part 6 details how to configure the Authorization Code grant type).

One of the objects created when configuring support of the OAuth 2.0 authorization code grant type in DataPower is the OAuth Client Profile. Figure 9 shows an example OAuth Client Profile.


Figure 9 OAuth Client Profile object in DataPower

In figure 9, in the Supported Type element, we have checked OpenID Connect. When enabled, this type provides extended OIDC support to allow an ID token to be generated. This action enables us to create a JWT generator in the Authorization and Token Endpoints section of the OAuth Client profile (figure 10):

Figure 10 JWT generator

Figure 10 shows the definition we selected for the JWT generator.

• We specify idg for the issuer claim value.
• We specify 300 seconds (5 minutes) for the JWT expiry period.
• We specify RS256 for the Signing algorith.
• We specify the name of the Crypto key object that is used to sign the JWT.
• And in the Advanced section, we check Issued At claim.

5.3 LDAP

Figure 11 shows the LDAP registry used in our scenario. The registry contains different groups for employees, customers and partners. The full Distinguished Name of the sample user is UID=JeanLeclerc,OU=employees,O=mop,C=fr.


Figure 11 LDAP registry

5.4 API Connect – API Gateway

For an example of defining and securing an API in API Connect see the article Securing an API end to end: an example scenario.

In API Connect, assembly flows are used to manipulate requests and responses, and to define security options and other settings. Figure 12 shows the assembly flow for the managed phonebook API.


Figure 12 API Assembly Flow

In figure 12, we include a Validate JWT policy in the assembly flow. Figure 13 shows the customization of the Validate JWT policy.

Figure 13 Validate JWT Policy

• We specify request.headers.authorization for the API Connect context variable that contains the JWT.
• We specify decoded.claims for the API Connect runtime variable to which the full set of claims that are contained in the JWT is assigned.
• We specify the regular expression ^idg.* for the issuer claim value. This means that, in order to validate the JWT, the issuer claim must be a value that begins with idg. This matches the issuer claim defined in the DataPower OAuth Client Profile.
• We specify the regular expression .* to validate the audience claim. This means that any value for audience is allowed.
• We specify mplicc-zceehttpsmutualauth-1 for the Crypto Object that contains the public key used to validate the JWT signature.

5.5 z/OS Connect EE

z/OS Connect EE is configured to validate a JWT, map the user identity to a RACF user ID, authorize the user to the phonebook system API and flow the RACF user ID to IMS. The configuration for JWT validation, user ID mapping and API authorization is documented here Using JWT with z/OS Connect EE.

In this article, we focus on how the mapped user ID is flowed to IMS.

We use RACF to map the distributed identity for user Jean Leclerc to the RACF user ID EMPLOY1 (see RACF). Having mapped the distributed user ID to a RACF user ID, we then have the possibility of flowing the RACF user ID to IMS. Figure 14 shows how the RACF user ID can be flowed from z/OS Connect EE to IMS.


Figure 14 Flowing RACF user ID to IMS

Identity propagation with the z/OS Connect EE IMS Service Provider is controlled by the definition of an IMS connection profile. If no user name is specified in the connection profile, the user ID is extracted from the request subject. z/OS Connect EE must be configured with SAF registry authentication and the subject must be 8 bytes or less in order for the IMS service provider to retrieve the user ID from the request subject.

Figure 15 shows the configuration of the IMS connection profile IMC1TOCM. The user ID and password are not specified, which means that z/OS Connect EE will use the mapped RACF user ID EMPLOY1.


Figure 15 IMS Connection Profile

5.6 RACF

We use RACF to implement the z/OS Identity Propagation feature of z/OS. Example 3 shows how the distributed user ID for user Jean Leclerc is mapped to the RACF user ID EMPLOY1.

Example 3 Identity mapping in RACF

Note: Example 3 shows a one-to-one mapping. z/OS Identity Propagation also supports many-to-one mappings. We use a many-to-one mapping to map all identities associated to a specific partner to the same RACF user ID.

5.7 IMS

You can enable RACF security checking in IMS Connect either by specifying RACF=Y in the HWS configuration statement or by issuing an online IMS Connect command.

In our scenario, the request from z/OS Connect EE does not contain a password, but only the user ID EMPLOY1 which means that IMS Connect is not able to authenticate the user ID.

When IMS Connect is configured to call RACF directly, you can use a user message exit to treat specific messages as trusted users. When a message is classified as a trusted user, IMS Connect does not call RACF to check security for that message, but instead passes the specified user ID to OTMA without authentication.

We use a message exit to check that the message arrives from z/OS Connect EE. This can be achieved in different ways:

• Validation of the IP address of the z/OS Connect EE server
• Validation of the DN of the certificate of the request when using TLS mutual authentication between z/OS Connect EE and IMS Connect.

For more information on trusted user support with IMS Connect refer to Trusted-user support for IMS Connect messages.

After the user ID EMPLOY1 is passed from IMS Connect to IMS TM through the OTMA connection, IMS TM checks that the user ID is authorized to access the IMS transaction IVTNOM to retrieve information from the PHIDAM phonebook database hosted in IMS DB.

6. Testing the scenario

In this section we show a test of the mobile app using OIDC to securely access the phonebook API.

In order to access the API, the mobile app must first obtain a JWT. It does this by launching a browser on the device and sending an authentication request to the Authorization Endpoint of the OIDC Provider.
Note: The mobile app starts a browser so that the app itself does not have access to the end user’s credentials.

Example 4 shows the authentication request that the mobile browser sends to the OIDC Provider Authorization End Point.
Example 4 Authentication request to OIDC Provider Authorization End Point

• The URI https://10.7.1.8/mplicc/sb/oidc-provider-api/oidc/authorize is the Authorization URL specified in the phonebook mobile app.
• The client_id has been retrieved by the mobile developer when registering the mobile app in the developer portal.
• The redirect_uri is the redirection URI to which the response will be sent. We specify the name of the mobile app phonebook.
• The response_type is the authorization processing flow to be used. When using the Authorization Code Flow, this value is code.
• The scope is the list of scopes the phonebook mobile app wants to access on behalf of the end user. OIDC requests must contain the openid scope value.

The OIDC Provider returns an HTML form that is displayed in the mobile browser for the end user to enter his credentials as shown in Figure 16:


Figure 16  HTML form returned by the OIDC Provider

Once the credentials are validated, the OIDC Provider redirects the browser back to the phonebook mobile app with a grant code as shown in Example 5:
Example 5 Redirect URI with grant code returned to mobile browser

This link is used by the mobile browser to forward the grant code to the mobile app. And the grant code is then sent in the request from the mobile app to the OIDC Provider Token End Point to be exchanged for an ID token (Example 6).

Example 6 Exchange grant code for ID token

Example 7 shows the response from the OIDC Provider Token End Point which contains the access token, refresh token and ID tokens (in the form of a JWT).
Example 7 Response from the OIDC Provider Token End Point

Note: The expiry period of the id_token is 300 seconds (expires_in).

Example 8 shows the clear form of the JWT returned by the OIDC Provider Token End Point, with the subject claim for user JeanLeclerc.
Example 8 JWT

With the JWT, the phonebook mobile app can now call the phonebook API to retrieve the list of contacts as shown in Example 9.
Example 9 HTTP request from the mobile app to API gateway

Example 10 shows an example JSON response message from the phonebook API.
Example 10 Response from phonebook API

This information is displayed on the mobile device as shown in Figure 17.

Example 11 shows a trace of the IMS IVTNOM transaction where EMPLOY1 is the user ID mapped from JeanLeclerc extracted from the JWT.
Example 11 IMS log in IMS Problem Investigator

If the mobile app requests the phonebook API in the API Gateway without a valid JWT, the API Gateway rejects the request (Example 12).
Example 12 Invalid JWT response from API Gateway

7. Summary

This example scenario shows how OIDC can be used to secure mainframe APIs, how a JWT can be mapped to a user ID in the local RACF registry and how the mapped RACF user ID can be used to authorize access to an IMS transaction.

This article is one of a number of articles on z/OS Connect EE security written by the IBM Montpellier Client Center team, Aymeric Affouard, Eric Phan and Nigel Williams.

More information on configuring security with z/OS Connect EE can be found in the Knowledge Center.