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 accessors credentials. A credential can be the accessors 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 z/OS Connect acts as an API provider.

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

1. The credentials are provided by the client. These can be a user ID and password, a third-party token, or a TLS certificate.
2. The credentials, including the identity, are passed on the connection between the client and the z/OS Connect server. The identity is typically a distributed ID, such as an X.500 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 the z/OS Connect Server or by requesting verification from a third-party server.
4. The authenticated identity is mapped to a user ID in the z/OS Connect user registry.
5. The authenticated user ID is authorized to connect to z/OS Connect and to perform specific actions on z/OS Connect APIs or services.
6. The API or service request is audited.
7. Using a secure connection to the System of Record (SoR), the identity is asserted to be used to invoke the program or transaction in the SoR.
8. The program or transaction runs in the SoR using the asserted identity.

Security options for the API provider

Authentication and Identification

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 token such as a JSON Web Token (JWT), Security Assertion Markup Language (SAML) token, or Lightweight Third-Party Authentication (LTPA) token. Alternatively, you can use custom authentication, such as an IBM WebSphere® Trust Association Interceptor (TAI).

Optionally, the authenticated identity might be mapped to a different user ID in the user registry, for example, a distributed identity to be mapped to a SAF user ID. z/OS Connect can then authorize the mapped user ID by using a SAF registry and pass it to a SoR.

For more information, see API provider authentication and identification.

Authorization

z/OS Connect supports authorization for an authenticated user to:

• Grant third-party access to an API by using the OAuth 2.0 protocol.
• Control access to z/OS Connect, by using the zosConnectAccess role.
• Perform specific actions on a z/OS Connect API or service. z/OS Connect groups users into one of four authorization levels: Admin, Operations, Invoke, and Reader. This is implemented by the IBM z/OS Connect authorization interceptor. You can enable the authorization interceptor globally in the z/OS Connect Server or for individual APIs or services.

For more information, see API provider authorization.

Confidentiality and Integrity

z/OS Connect supports TLS to ensure confidentiality and integrity of the request. z/OS Connect supports TLS through use of Java™ Secure Socket Extension (JSSE), Application Transparent Transport Layer Security (AT-TLS), and hardware cryptography to provide secure TCP/IP connections to and from a z/OS Connect Server.

For more information, see API provider confidentiality and integrity for zosConnect-2.0.

Auditing

z/OS Connect provides an audit interceptor. The z/OS Connect audit interceptor records information about API and service requests to SMF data sets on the z/OS operating system. SMF type 123, subtype 1 records are generated. These include the user name and, if present, the mapped user name, which is associated with the request. You can enable the audit interceptor globally in the z/OS Connect Server or for individual APIs or services.

For more information, see Monitoring with z/OS Connect and Configuring the audit interceptor

System of Record security

The security options available when calling a transaction or program in a System of Record (SoR) from a z/OS Connect Server, vary depending on the service provider 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 a user identity is asserted. For example, when using identity propagation or identity assertion, to the SoR to run the program or transaction.

For more information, see Configuring security for an IPIC connection, IMS service security process flow, and Configuring security for a REST client connection.

API requester security

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

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

1. Two credentials, each consisting of a user ID and password, can be provided by the CICS, IMS or z/OS application and can be used for different purposes.
   • One user ID and password can be used for basic authentication by the z/OS Connect Server. These credentials are specified in different places by the application. For example, in CEEOPTS environment variables for IMS and z/OS applications or in a CICS user exit for CICS.
   • The other user ID and password can be used to obtain a token from an authorization server to use on the request to the RESTful API. These credentials are specified as parameters in the data structure to pass to the communication stub for communication with the z/OS Connect Server. Alternatively, a locally generated JWT can be configured.
   • Depending on the security configuration, either both or neither of these credentials might be required.
2. The connection between the CICS, IMS, or z/OS application and the z/OS Connect Server can be secure with data that is sent on the connection encrypted using TLS.
3. z/OS Connect authenticates the CICS, IMS, or z/OS application.
4. The authenticated user ID is authorized to connect to z/OS Connect and to perform specific actions on z/OS Connect API requesters.
5. The API requester request is audited.
6. The user ID and password credentials are passed to an authorization server to obtain a security token. Alternatively, a locally generated JWT can be configured.
7. The connection to the external API provider can be secure, with security credentials such as a security token provided to invoke the RESTful API.
8. The RESTful API runs in the external API provider.

Security options for the API requester

Confidentiality and Integrity

z/OS Connect supports TLS to ensure confidentiality and integrity of the request.

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

For more information, see API requester confidentiality and integrity for zosConnect-2.0.

Authentication and Identification

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 CICS, IMS, or 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 CICS, IMS, or z/OS application.
  • For CICS, either CICS native TLS support or Application Transparent Transport Layer Security (AT-TLS) can be used.
  • For IMS or z/OS applications, Application Transparent Transport Layer Security (AT-TLS) can be used.

z/OS Connect supports identity assertion, which allows you to invoke an API requester from a z/OS application with an identity that is provided in the application context.

For more information, see API requester authentication and identification.

Authorization

z/OS Connect supports authorization for an authenticated user to:

• Control access to z/OS Connect using the zosConnectAccess role.
• Perform specific actions on a z/OS Connect API requester. z/OS Connect groups users into one of four authorization levels: Admin, Operations, Invoke, and Reader. This is implemented by the z/OS Connect authorization interceptor. You can enable the authorization interceptor globally in the z/OS Connect Server or for individual API requesters.

For more information, see API requester authorization.

When you develop a CICS, IMS, or 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 zosconnect_oAuthConfig access token-related parameters.

Auditing

IBM z/OS Connect provides an audit interceptor that records information about API requester requests to SMF datasets on the z/OS operating system. SMF type 123, subtype 1 records are generated and include the user name that is associated with the request. You can enable the audit interceptor globally in the z/OS Connect Server or for individual API requesters.

For more information, see Monitoring with z/OS Connect and Configuring the audit interceptor.

RESTful API security

Each RESTful API may have different security requirements, as defined in their Swagger documents. z/OS Connect supports the following methods for authenticating with a RESTful API:

• 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 z/OS Connect Server.
• OAuth 2.0 by configuring the z/OS Connect Server to send a user ID and password to an authorization server to request an OAuth 2.0 access token. This token is then sent on the request to the RESTful API.
• API keys by specifying the API key values in the CICS, IMS, or z/OS application, which can then be sent on the request to the RESTful API.
• JSON Web Token (JWT) by configuring the z/OS Connect Server to send a user ID and password to an authentication server to request a JWT or by configuring the 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.