Overview of IBM z/OS Connect security

Security principles

Confidentiality

Confidentiality ensures that an unauthorized party cannot obtain the meaning of the transferred or stored data. Typically confidentiality is achieved by encrypting the data.

Integrity

Integrity ensures that transmitted or stored information was not altered in an unauthorized or accidental manner. Typically it is a mechanism to verify that what is received over a network is the same as what was sent.

Authentication

Authentication is the process of validating the identity that is claimed by the accessing entity. Authentication is performed by verifying authentication information that is provided with the claimed identity. The authentication information is generally referred to as the accessor's credentials. A credential can be the accessor's name and password. It can also be a token that is provided by a trusted party, such as a JSON Web Token (JWT) or an X.509 certificate.

Authentication is usually one of the earliest steps in a request workflow. When authenticated, an identity can be asserted to the downstream process steps, meaning that these steps trust that the identity was successfully authenticated by the upstream steps.

Identification

Identification is the ability to assign an identity to the entity that is attempting to access the system. Typically the identity is used to control access to resources. Depending on the security model in which the identification is performed, the identity might come from the authentication credentials or it might be asserted from another server.

Authorization

Authorization is the process of checking whether an authenticated identity is permitted access to the resource that it is requesting. A typical implementation of authorization is to pass to the access control mechanism a security context that contains the authenticated identity.

Auditing

Auditing provides you with the ability to capture and record events such as an API request so that you can analyze them later, perhaps if your security was breached.

API provider security

The following diagram indicates where the security principles apply in an end to end flow when IBM z/OS Connect acts as an API provider.

The flow includes the following security steps that can be performed by IBM z/OS Connect.

1. The credentials are provided by the client. These can be a user ID and password, a JWT, or a TLS certificate.
2. The credentials, including the identity, are passed on the connection between the client and IBM z/OS Connect. The identity is typically a distributed ID, such as an X.509 distinguished name and associated LDAP realm that originates from a remote system. Alternatively the identity might be a SAF user ID. The data that is sent on the connection can be encrypted using TLS.
3. The client is authenticated. This can be within IBM z/OS Connect or by requesting verification from a third-party server.
4. The authenticated identity can be mapped to a user ID in the IBM z/OS Connect user registry.
5. The user is authorized to invoke the API operation if they have the required role.
6. The API request is audited by using the Liberty Audit feature.
7. The authenticated user identity can be propagated to the System of Record (SoR) when the SoR supports this capability. Alternatively, the SoR connection can be configured to use a functional identity.

Security options for the API provider

Authentication and Identification

IBM z/OS Connect supports the following authentication methods:

• Basic authentication that uses credentials in the form of a user ID and password that are verified by System Authorization Facility (SAF), Lightweight Directory Access Protocol (LDAP) or a basic user registry.
• Client authentication that uses a TLS client certificate to identify the client.
• Third-party authentication that uses a JSON Web Token (JWT).

Optionally, the authenticated identity can be mapped to a user ID in the configured user registry. For example, a distributed identity from a JWT can be mapped to a SAF user ID when running on z/OS. The authorization role check is then made by using the mapped user ID.

For more information, see API provider authentication and identification.

Authorization

IBM z/OS Connect supports role-based authorization.

Roles are defined in the OpenAPI definition during API development or later in a DevOps pipeline. Roles specify the authorization that is required to invoke the API operations. If roles are defined, a user must be authenticated and have the required role to successfully invoke an API operation. Roles are the names of LDAP registry groups or SAF policies, or the values of a configured JWT claim. IBM z/OS Connect also supports the ability to define a role to allow all authenticated users access to API operations.

Confidentiality and Integrity

IBM z/OS Connect supports TLS to ensure confidentiality and integrity of the request over TCP/IP connections. TLS support is provided by Java™™ Secure Socket Extension (JSSE). In addition, when running on z/OS, Application Transparent Transport Layer Security (AT-TLS) and hardware cryptography can be used for TLS connections.

For more information, see API provider confidentiality and integrity.

Auditing

Requests into IBM z/OS Connect are automatically audited when running a z/OS Connect container, by using the Liberty Audit 1.0 feature. This feature can optionally be enabled when running a IBM z/OS Connect server natively. For more information, see Auditing Liberty events in the WebSphere® Application Server for z/OS Liberty documentation.

System of Record security

The security options available when calling a transaction or program in a System of Record (SoR) from IBM z/OS Connect vary depending on the z/OS asset that is used and the SoR. These options include:

• Whether the connection is secured with TLS.
• Whether any credentials are required to establish the connection to the SoR.
• Whether the program or transaction in the SoR is required to run under the IBM z/OS Connect authenticated user identity or a IBM z/OS Connect functional identity.

API requester security

The following diagram indicates where the security principles apply in an end to end flow with IBM z/OS Connect acting as an API requester.

The API requester flow includes the following security steps that can be performed by IBM z/OS Connect.

1. Credentials, such as a user ID and password or a client ID and client secret, can be provided by the z/OS application and can be used for different purposes.
   • A user ID and password can be used for basic authentication to the IBM z/OS Connect server. For all z/OS applications, these credentials can be specified as parameters on the Host API BAQINIT call. For CICS® they can alternatively be specified by using a CICS user exit.
   • Other credentials can be used to obtain a token from an authorization server to use on the request to the API endpoint. These credentials are specified as parameters in the data structure to pass to the Host API for communication with the IBM z/OS Connect server. Alternatively, IBM z/OS Connect can be configured to locally generate a JWT.
   • The credentials that are required depend on the specific configuration of the IBM z/OS Connect server.
2. The connection between the z/OS application and the IBM z/OS Connect server can be secured with data that is sent over the connection encrypted using TLS or AT-TLS.
3. IBM z/OS Connect authenticates the z/OS application.
4. The authenticated user ID is checked for authorization to invoke the IBM z/OS Connect API requester.
5. The API requester request is audited.
6. Credentials are passed to an authorization server to obtain a security token. Alternatively, a JWT can be generated locally.
7. The connection to the external API endpoint can be secure, with security credentials such as a security token provided to invoke the API.
8. The API runs in the external API endpoint

Security options for the API requester

Confidentiality and Integrity

IBM z/OS Connect supports TLS or AT-TLS to ensure confidentiality and integrity of the request.

• To provide secure connections between the z/OS application and the IBM z/OS Connect server:
  • For CICS, either CICS native TLS support or Application Transparent Transport Layer Security (AT-TLS) can be used.
  • For z/OS applications, AT-TLS can be used.
• IBM z/OS Connect can use Java Secure Socket Extension (JSSE) or AT-TLS for secure connections between the IBM z/OS Connect server and the API endpoint.

For more information, see API requester confidentiality and integrity.

Authentication and Identification

IBM z/OS Connect supports the following authentication methods:

• Basic authentication by using credentials in the form of a user ID and password, sent from the z/OS application, and verified by using System Authorization Facility (SAF), Lightweight Directory Access Protocol (LDAP) or a basic user registry.
• Client authentication by using a TLS client certificate to identify the z/OS application.
  • For CICS, either CICS native TLS support or Application Transparent Transport Layer Security (AT-TLS) can be used.
  • For z/OS applications, Application Transparent Transport Layer Security (AT-TLS) can be used.

For more information, see API requester authentication and identification.

Authorization

IBM z/OS Connect supports authorization for an authenticated user to permit access to the invoke role for API requesters.

For more information, see API requester authorization.

When you develop a z/OS application to call an API that is protected by OAuth 2.0, you can include the information for the OAuth parameters in the request. For more information, see OAuth 2.0 parameters

Auditing

Requests into IBM z/OS Connect are automatically audited when running a z/OS Connect container, by using the Liberty Audit 1.0 feature. This feature can optionally be enabled when running a IBM z/OS Connect server natively. For more information, see Auditing Liberty events in the WebSphere Application Server for z/OS Liberty documentation.

API endpoint security

Each API endpoint might have different security requirements, as defined in their OpenAPI definition. IBM z/OS Connect supports the following methods for authenticating with APIs:

• Basic authentication by using credentials in the form of a user ID and password.
• Client authentication by using a TLS client certificate to identify the IBM z/OS Connect server.
• OAuth 2.0 by configuring the IBM z/OS Connect server to send credentials to an authorization server to request an OAuth 2.0 access token. This token is then sent on the request to the API.
• API keys by specifying the API key values in the z/OS application, which can then be sent on the request to the API.
• JSON Web Token (JWT) by configuring the IBM z/OS Connect server to send a user ID and password to an authentication server to request a JWT or by configuring the IBM z/OS Connect server to generate a JWT locally. This JWT is then sent on the request to the RESTful API.

For more information, see API requester authentication and identification.