How to configure basic authentication with an LDAP user registry

Configure a z/OS® Connect server to perform basic authentication with a Lightweight Directory Access Protocol (LDAP) user registry.

zosConnect-2.0 Applies to zosConnect-2.0.

This task is applicable when z/OS Connect is used as an API provider.

Before you begin

You should be familiar with the information in API provider authentication and identification.
You must complete the task How to configure an LDAP user registry.
You must have write access to the server.xml configuration file.

About this task

You configure the z/OS Connect server to require authentication, by setting the attribute requireAuth="true". This task then configures the server to use basic authentication.

This task does not include information on how to configure the IBM z/OS Connect server to use TLS. If the attribute requireSecure is set to true (the default), you must configure a TLS connection between the client and the z/OS Connect server, for example, by completing the task How to configure TLS with RACF key rings.

Procedure

For more information about configuration elements, see zosConnect-2.0 Configuration elements in the Reference section.

Ensure that the server is configured to require authentication for the request.
This configuration can be set at different scopes:
- To require authentication globally for the server, set requireAuth="true" on the zosconnect_zosConnectManager element in the server.xml configuration file. For example,
```
<zosconnect_zosConnectManager requireAuth="true" ... />
```
- To require authentication for a specific API, which takes precedence over the global server setting, set requireAuth="true" on the zosConnectAPI element in the server.xml configuration file. For example,
```
<zosconnect_zosConnectAPIs>
    <zosConnectAPI name="Api1" requireAuth="true"/>
</zosconnect_zosConnectAPIs>
```
- To require authentication for a specific service, which takes precedence over the global server setting, set requireAuth="true" on the service element in the server.xml configuration file. For example,
```
<zosconnect_services>
    <service name="Service1" requireAuth="true"/>
</zosconnect_services>
```
Configure the server to use basic authentication.
IBM z/OS Connect attempts to use a TLS client certificate for authentication, unless an alternative authentication mechanism is configured. Use one of the following methods to configure basic authentication:
- Configure fail-over to basic authentication, by adding the following element to the server.xml configuration file:
```
<webAppSecurity allowFailOverToBasicAuth="true"/>
```
- Configure basic authentication to override the client certificate authentication default, by adding the following element to the server.xml configuration file:
```
<webAppSecurity overrideHttpAuthMethod="BASIC"/>
```
Optional: Map the LDAP user ID received in the basic authentication header to a SAF user ID.
If you require a SAF user ID because the IBM z/OS Connect server uses SAF for authentication, or the System of Record requires a SAF user ID, then you can map the authenticated LDAP user ID to a SAF user ID. For more information, see the task How to map an LDAP user ID to a RACF user ID.
Assign users and groups to the zosConnectAccess role.
If you mapped the LDAP user ID to a SAF user ID, as described in step 3, follow the instructions in task How to configure the zosConnectAccess role with a SAF user registry. Otherwise, follow the instructions in task How to configure the zosConnectAccess role with an LDAP user registry.

Results

Users and groups that match the filters defined in the ldapRegistry element can be used to authenticate with the z/OS Connect server. Additionally, the LDAP users and groups that are assigned to the zosConnectAccess role now have authorization to access IBM z/OS Connect.