API provider authentication and identification

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

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

Consider the following requirements to implement authentication for clients that need to connect to a IBM z/OS Connect server:

Authentication options.
User registries.
Caching authentication credentials.

By default, IBM z/OS Connect requires that all requests are authenticated. Successful authentication that uses any of the supported authentication methods results in an authenticated user ID being associated with the request. The authenticated user ID is also checked to ensure that it is authorized to access IBM z/OS Connect.

Authentication is governed by the requireAuth attribute of the zosconnect_zosConnectManager element in the server.xml configuration file. If this attribute is set to true, all requests to a IBM z/OS Connect server are authenticated. You can override this global setting by specifying the requireAuth attribute on individual entries, such as for a particular API or service.

Note: If requireAuth="true" is configured for a service, then authentication is checked only if that service is invoked directly by an HTTP or HTTPS request. It does not take effect if that service is invoked by an API.

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

The three methods of authentication are basic authentication, authentication with a client certificate, and authentication with a third-party token. — Figure 1. The three methods of authentication.

Basic authentication: When basic authentication is used, the REST client sends, or is prompted for, a user ID and password on the request to the IBM z/OS Connect server. The server authenticates the credentials based on information in the user registry.
Client certificate authentication: With client certificate authentication, the REST client is prompted by the IBM z/OS Connect server to supply a certificate that the server 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, for example, IBM API Connect®, as shown in Figure 1. The authentication token is then sent to the IBM z/OS Connect server. IBM z/OS Connect validates the token 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 for authentication and authorization. IBM 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 server.xml configuration file. It is typically used in development environments.
Lightweight Directory Access Protocol (LDAP) user registry: Typically used in an environment where LDAP already stores the user IDs.
System Authorization Facility (SAF) registry: Typically used to store SAF user IDs on z/OS.

Using multiple user registries in the same IBM z/OS Connect server 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 Federation of user registries in the WebSphere® Application Server for z/OS Liberty documentation.

For more information about configuring the user registries, see User registries.

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. The IBM z/OS Connect server 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 IBM z/OS Connect acts as an API provider:

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

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

By default, IBM z/OS Connect uses client certificate authentication. You can use one of the following methods to implement basic authentication:

Configure IBM z/OS Connect to fail over to use basic authentication when the client certificate authentication does not succeed. For example, when the client does not send a certificate or when the client sends a certificate but the certificate is not mapped to a user ID in the user registry.
To configure fail over to basic authentication, add the following element to the server.xml configuration file:
```
<webAppSecurity allowFailOverToBasicAuth="true"/>
```
Configure IBM z/OS Connect to override the client certificate authentication default. However, this configuration applies globally, so this option is not suitable when any requests to the same IBM z/OS Connect server require client certificate authentication. This option also provides improved performance. For more information, see Performance Guidance.
To configure IBM z/OS Connect to override the client certificate authentication default with basic authentication, add the following element to the server.xml configuration file:
```
<webAppSecurity overrideHttpAuthMethod="BASIC"/>
```

For more information about configuring basic authentication, see API provider basic authentication.

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.

When TLS client authentication is configured, the client must provide its certificate to IBM z/OS Connect for each HTTPS connection. IBM 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 the IBM z/OS Connect server.

To authenticate to the IBM z/OS Connect server, 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 for z/OS 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 for z/OS 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 a IBM z/OS Connect server 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) and RACDCERT MAP (create mapping) in the z/OS Security Server RACF Command Language Reference.

IBM z/OS Connect is configured for client certificate authentication with 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 the client certificate is not mapped to a user ID in the user registry, then you can configure failover to basic authentication.

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

Note: AT-TLS is not supported for client authentication between a client and the IBM z/OS Connect server when IBM 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 4. The authentication token is then sent to the IBM z/OS Connect server. IBM z/OS Connect validates the token and the identity in the token is optionally mapped to a user ID in the user registry.

Trust between the third party and IBM 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.

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 the IBM z/OS Connect server. 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 the IBM z/OS Connect server 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 Configuring the authentication cache in Liberty in the WebSphere Application Server for z/OS Liberty.

Using a Trust Authentication Interceptor (TAI) to allow selected unauthenticated requests

Where IBM z/OS Connect is configured for basic authentication, but selected requests do not present the required credential, a Trust Authentication Interceptor (TAI) can be developed, configured, and deployed with a IBM z/OS Connect server to allow selected unauthenticated requests to be processed.

For more information about creating a TAI, see Developing a custom TAI for Liberty and Web Container Application Security (webAppSecurity) in the WebSphere Application Server for z/OS Liberty documentation.