API provider authentication and identification

Learn how requests sent to IBM® z/OS® Connect are authenticated.

zosConnect-3.0 Applies to zosConnect-3.0.

Warning: Authentication is not enforced unless authorization roles are defined for API operations.

Before you study this topic, you should be familiar with the information in Overview of IBM z/OS Connect zosConnect-3.0 security.

Consider the following requirements to implement authentication for clients that need to access z/OS Connect APIs:

Authentication options.
User registries.
Caching authentication credentials.

z/OS Connect supports various user authentication methods. Successful authentication results in an authenticated user ID being associated with a request. However, authentication is only enforced if authorization roles are defined for the API operation being invoked. A generic role can be used to allow all authenticated users access to APIs. If authorization roles are not defined, unauthenticated users are able to invoke the APIs, as shown in Table 1.

Table 1. Access to API operations
User Authenticated	Role(s) defined for API operation	User has a required role	User can invoke API operation
Yes	Yes	Yes	Yes
Yes	No	-	Yes
No	No	-	Yes
No	Yes	-	No
Yes	Yes	No	No

Three methods are provided for authentication between clients and z/OS Connect:

Basic authentication: When basic authentication is used, the REST client sends, or is prompted for, a user ID and password on the request to z/OS Connect. The credentials are authenticated by z/OS Connect based on information in the user registry.
Client certificate authentication: With client certificate authentication, the REST client is prompted by z/OS Connect to supply a certificate that z/OS Connect then validates and associates with a user ID in the user registry. The identity in the certificate must be mapped to a user ID in the user registry.
Third-party authentication: Third-party authentication means that the REST client authenticates with a third-party authentication server. This server generates an authentication token. The REST client might access the third-party authentication server through an intermediate server, typically an API gateway, such as IBM API Connect®. The authentication token is then sent to z/OS Connect. The token is validated by z/OS Connect and the identity in the token is optionally mapped to a user ID in the user registry.

User registries

User registries store information about users and groups that can be used in the processes of authentication and authorization. z/OS Connect supports the following types of user registry.

Basic user registry: A simple file-based registry, where users and groups are defined in the configuration file. It is typically used in development environments.
Lightweight Directory Access Protocol (LDAP) user registry: Used to store distributed user identities.
System Authorization Facility (SAF) registry: Used to store SAF user IDs and policies on z/OS.

Using multiple user registries in the same z/OS Connect instance is referred to as federated user registries. This configuration is useful when, for example, the user information is in two different LDAP servers, in two subtrees of the same LDAP server, or in both an LDAP server and a SAF registry. For more information, see A launch icon to indicate a link opens a new tab or window. Federated user registry in the WebSphere Application Server Liberty documentation.

Basic authentication

Basic authentication is a simple authentication scheme that is built into the HTTP protocol. It requires the client to provide a user ID and password in the request. The user ID and password are encoded in base64 and sent in the HTTP Authorization header of the request. z/OS Connect validates the user ID and password against a configured user registry. The user ID is set as the authenticated user.

The following types of user ID and password are supported for basic authentication when z/OS Connect acts as an API provider:

A user ID and password that is defined in a basic user registry.
An LDAP distinguished name (or uid) and password that is defined in an LDAP user registry.
A SAF user ID and password that is defined in the SAF registry on the same LPAR as z/OS Connect.

When basic authentication is used, the credentials are encoded, but are not encrypted. Therefore, it is typically used with HTTPS (TLS) to provide confidentiality.

For more information about configuring basic authentication, see API provider basic authentication for z/OS Connect zosConnect-3.0.

Client certificate authentication

Choose certificate-based client authentication to use information that is provided in the client's TLS certificate to map to an associated user ID. It also provides all of the normal benefits that are associated with a secure TLS connection. For more information about TLS, see API provider confidentiality and integrity for zosConnect-3.0.

When TLS client authentication is configured, the client must provide its certificate to z/OS Connect for each HTTPS connection. z/OS Connect validates the chain of trust by checking that the client certificate issuer is in the truststore. This process is standard TLS behavior and if the client certificate is successfully validated, the connection can be established to z/OS Connect.

To authenticate to z/OS Connect, the client certificate must also be mapped to a user ID in the user registry. If the client certificate is successfully mapped to a user ID, then that user ID is set as the authenticated user.

For the basic registry, the user identity is the common name (CN) from the distinguished name (DN) of the certificate. For more information about using client authentication with a basic registry, see Basic certificate map mode in the WebSphere Application Server Liberty documentation.
For an LDAP registry, the DN from the client certificate must be in the LDAP registry. For more information about using client authentication with LDAP, see LDAP certificate map mode in the WebSphere Application Server Liberty documentation.
For a SAF registry, a DIGTCERT profile is generated from the information in the certificate, such as the certificate's serial number and the issuer's distinguished name. The profile must be associated with a SAF user ID.
Client certificates can be associated with a RACF® user ID in two ways:
1. Use the RACDCERT MAP command to define a certificate name filter, which is also called a user ID mapping. This command maps the certificate subject's distinguished name (DN) to a RACF user ID. Certificate name filtering supports generic filters that allow multiple certificates to be associated with a single RACF user ID.
2. Use the RACDCERT ADD command to add the certificate into RACF and specify the user ID it is to be associated with. This command is typically used only when REST clients connect to z/OS Connect via an intermediate server, such as an API Gateway, where there are only a few such servers and certificates to store and maintain in RACF.
For more information, see RACDCERT ADD (Add certificate) (add certificate) and RACDCERT MAP (Create mapping) (create mapping) in the z/OS documentation.

z/OS Connect is configured for client certificate authentication, and additionally requires an SSL configuration. The SSL client authentication can be configured as required, or configured as supported.

If TLS client authentication is required, then the client must provide a certificate that is trusted by the server for the handshake to succeed.
If TLS client authentication is supported and the client provides a certificate, then that certificate must be trusted by the server. However, if the client does not provide a certificate, the TLS handshake continues by using TLS server authentication only.

For certificate-based client authentication, client authentication should be configured as required, rather than supported.

If required, you can configure multiple ports that have different SSL configurations.

Note: IBM z/OS Communications Server Application Transparent Transport Layer Scrutiny (AT-TLS) is not supported for client authentication between a client and the z/OS Connect Server when z/OS Connect is acting as an API provider.

Third-party authentication

When third-party authentication is used, the REST client authenticates with a third-party authentication server. This server generates an authentication token. The REST client might access the third-party authentication server through an intermediate server, typically an API gateway, for example, IBM API Connect, as shown in Figure 3. The authentication token is then sent to z/OS Connect. The token is validated by z/OS Connect and the identity in the token is optionally mapped to a user ID in the user registry.

Trust between the third party and z/OS Connect can be established in different ways, including the use of a digital signature. Third-party authentication tokens can be used as part of a Single Sign-On (SSO) solution.

TLS client authentication can also be used in this model so that the client certificate of the intermediate server is used to establish the connection to z/OS Connect. However, the user identity in the token rather than the client certificate distinguished name is used to determine the authenticated identity for the request.

One of the advantages of using third-party authentication is that z/OS Connect does not see the client's password.

For more information about third-party authentication, see API provider third-party authentication.

Caching authentication credentials

An authentication cache is provided to store a subject after successful authentication of a user to reduce the potential performance impact of creation of a subject. For more information, see A launch icon to indicate a link opens a new tab or window. Configuring the authentication cache in Liberty in the WebSphere Application Server Liberty documentation.