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.

If the authentication is successful, 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). 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.

Once the z/OS mainframe instance is configured with TLS, declared in the zOS-Data.ini configuration file, and the z/OS username and password credentials are added by using the User and password action button, IBM Application Discovery Build Configuration and IBM Application Discovery Build Client will perform all GUI and CLI mainframe related features as expected.

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 IBM AD Build 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 and IBM AD Connect for Mainframe.

Important: Starting with IBM AD V6.1.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

Once the z/OS mainframe instance is configured with TLS, declared in the zOS-Data.ini configuration file, and the z/OS username and password credentials are added by using the User and password action button, IBM Application Discovery Build Configuration and IBM Application Discovery Build Client will perform all GUI and CLI mainframe related features as expected.
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.