API requester basic authentication to IBM z/OS Connect

Basic authentication can be used between the CICS®, IMS, or a z/OS application and the IBM z/OS Connect server.

zosConnect-2.0 Applies to zosConnect-2.0.

Basic authentication is a simple authentication scheme that is built into the HTTP protocol. It requires the CICS, IMS, or a z/OS application to provide a user ID and password in the request.
  • For IMS or a z/OS application, a user ID and password must be sent by specifying the values for the BAQUSERNAME and BAQPASSWORD environment variables in the CEEOPTS DD statement.
  • For CICS, a user ID and password must be sent by using the CICS XWBAUTH user exit.
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 diagram shows basic authentication between CICS, IMS or a z/OS application, and a IBM z/OS Connect server.

Diagram shows how a z/OS application passes credentials to IBM z/OS Connect for identification.

Typically a SAF user ID and password are provided by the CICS, IMS, or the z/OS application for basic authentication when IBM z/OS Connect acts as an API requester. Alternatively an LDAP distinguished name (or uid) and password, or a basic user registry user ID and password can be used.

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"/>