Enabling the z/OS User Authentication feature for IBM AD Connect for Mainframe

Introduction

Starting with IBM® AD V6.1.1, IBM AD Build Client, IBM AD Build Configuration and IBM Connect for Mainframe can be configured to require a user to provide a valid z/OS® user ID and password or password phrase before you access the project resources on the mainframe.

When configured for user authentication, IBM AD Build Client will prompt the user to provide a valid z/OS user ID and password or password phrase. IBM AD Build Client will then include these credentials in all subsequent requests that are sent to the mainframe. IBM AD Connect for Mainframe will extract these credentials and perform authentication by using the installed z/OS security product (RACF®, ACF2, or others).

If the authentication is successful, the user’s requests will be serviced by a subtask running under the security context of the authenticated z/OS user ID. The authenticated user ID must have the appropriate access privileges in place to retrieve the requested resources.

If the authentication fails, an error message is sent back to the IBM AD Build Client user. No attempt will be made to access the requested resources.

In the previous releases, all mainframe requests were serviced by using the STC ID of the AD Connect for Mainframe started task.

Current limitations

Starting with IBM AD V6.1.1, both RACF passwords up to 8 characters and RACF password phrases up to 100 characters are supported. For specific details about password and password phrase requirements, see Passwords and password phrases in the z/OS Security Server RACF Security Administrator's Guide.

The user ID and password can only be input through the IBM AD Build Client and IBM AD Build Configuration User Interfaces (GUI). Setting these fields in the command-line interface (CLI) is not currently supported.

Compatibility with earlier versions of IBM AD

Due to the expansion of message headers to support RACF password phrases, IBM AD Build Client version 6.1.1 is not compatible with earlier versions of IBM AD Connect for Mainframe.

Due to the same reason, IBM AD Connect for Mainframe version 6.1.1 is also not compatible with earlier versions of IBM AD Build Client.

Note: If you want to use IBM AD V6.1.1, make sure that you have installed and configured the latest version of IBM AD Build Client and IBM AD Connect for Mainframe.

Recommendations for the z/OS User Authentication feature

Before enabling the z/OS User Authentication feature, you need to make sure that the AT-TLS setup for IBM AD Connect for Mainframe is completed and the TLS connection between IBM AD Build Client and IBM AD Connect for Mainframe is enabled. IBM AD Build Client will not send the z/OS user credentials over an unencrypted TCP/IP connection. For more information, see Enabling TLS Connection to IBM AD Build and Enabling TLS Connection between IBM AD Build Client and IBM AD Connect for Mainframe.

If you want to use the z/OS User Authentication feature, it must be enabled on both IBM AD Build Client and IBM AD Build Configuration as well as for IBM AD Connect for Mainframe on z/OS. For more information, see Enabling the z/OS User Authentication feature for IBM AD Build Client and Enabling the z/OS User Authentication feature for IBM AD Build Configuration.

If you do not want to use the z/OS User Authentication feature, it must be disabled on IBM AD Build Client, IBM AD Build Configuration, and IBM AD Connect for Mainframe.

Important: After the installation and configuration of IBM AD V6.0.1 the z/OS User Authentication feature is disabled by default. There are no actions to be performed in case that this is the desired configuration.

Enabling the z/OS User Authentication feature for IBM AD Connect for Mainframe

The tenth positional parameter in the IBM AD Connect for Mainframe started task procedure PARM list is the switch that enables or disables the z/OS User Authentication feature. The default value is N (authentication disabled) and you must set it to Y (authentication enabled) to enable the z/OS User authentication feature.

Note: When the value of this PARM is changed, the IBM AD Connect for Mainframe started task must be restarted to read in the new value.

The following sample is available in member IAYLSTNR in the SIAYSAMP distribution library of IBM AD Connect for Mainframe.

This image shows the IAYLSTNR member. — Figure 1. IAYLSTNR member

Grant user ID access to necessary mainframe resources

After a successful login to IBM AD Connect for Mainframe, all access to mainframe resources will be made under the security context of the logged in user. Therefore, you must ensure that this user ID has the necessary read level access to all mainframe resources that will be retrieved for the corresponding AD project.

Attention:

There is one exception. First time when IBM AD Build Client retrieves project information from the mainframe, it will request IBM AD Connect for Mainframe to issue two MVS™ commands.

DISPLAY M=CPU 
DISPLAY SYMBOLS

These commands will run under the started task user ID of the IBM AD Connect for Mainframe task. It is not expected that the z/OS user ID of a typical AD Project administrator will have (or even should have) authority to issue MVS system commands, although they are DISPLAY commands only.

Verifying the z/OS User Authentication feature configuration

If the z/OS User Authentication feature is enabled, you will see the IAYMF0050I message in the CPEOUT file when IBM AD Connect for Mainframe is started.
Figure 2. IAYMF0050I message
If the z/OS User Authentication feature is disabled, you will see the IAYMF0051I message in the CPEOUT file when IBM AD Connect for Mainframe is started.
Figure 3. IAYMF0051I message

As previously stated, ensure that IBM AD Build Client is also configured to match the authentication setting (Y/N) used on IBM AD Connect for Mainframe.

Using the z/OS User Authentication feature

After starting IBM AD Build Client or IBM AD Build Configuration with authentication enabled, the first operation you attempt and requires a mainframe connection will cause IBM AD Build Client or IBM AD Build Configuration to prompt you for your z/OS user credentials.
The credentials that you enter will persist for the duration of this instance of IBM AD Build Client or IBM AD Build Configuration. They will be used for all subsequent communication with IBM AD Connect for Mainframe until you stop the instance of IBM AD Build Client or IBM AD Build Configuration. After you restart IBM AD Build Client or IBM AD Build Configuration, you will be prompted again for your credentials. For more information, see Using the z/OS User Authentication feature in IBM AD Build Configuration and Using the z/OS User Authentication feature in IBM AD Build Client.
On the z/OS side, the only explicit indication of a successful login is the following message displayed in the JESMSGLG of the IBM AD Connect for Mainframe started task. It is also simultaneously displayed in the z/OS system log. This message is only displayed on systems running RACF as the z/OS security product. Some systems are configured to display this message only once per day at most.
Example of a RACF message that is not part of the IBM AD product release.
```
ICH70001I USERX  LAST ACCESS AT 09:16:31 ON SUNDAY, JUNE 6, 2021
```
For security products other than RACF, they will generate their own unique messages following a successful user authentication. For more information, contact your site’s security team.

Troubleshooting the z/OS User Authentication Configuration

Make sure that both IBM AD Build Client and IBM AD Connect for Mainframe Configuration are configured to require user ID and password.
Make sure that TLS is enabled on the z/OS Connection definition on IBM AD Build Client Configuration.
Confirm with your z/OS security team that the user ID and password combination used as input are valid.
Ensure that the user ID used to authenticate has read access to all the mainframe resources necessary for your IBM AD projects.
For more detailed information, you can enable debug trace on IBM AD Connect for Mainframe by issuing the z/OS Modify command.
```
F STC_NAME,DEBUGON
```
Where STC_NAME is the started task name for the running instance of IBM AD Connect for Mainframe. The debug records are written to the STC IAYOUT file. You can search for error messages with a prefix of IAYMF that are generated at the time of your test. For more information, see IBM AD Connect for Mainframe Messages.