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

Introduction

Starting with IBM® ADDI V6.1.1, IBM ADDI Build Client, IBM ADDI Build Configuration and IBM ADDI 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 ADDI Build Client will then include these credentials in all subsequent requests that are sent to the mainframe. IBM ADDI 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 ADDI 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 ADDI 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 ADDI Build Configuration and IBM ADDI Build Client will perform all GUI and CLI mainframe related features as expected.

Compatibility with earlier versions of IBM ADDI

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

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

Note: If you want to use IBM ADDI V6.1.1, make sure that you have installed and configured the latest version of IBM ADDI Build Client and IBM ADDI 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 ADDI Connect for Mainframe is completed and the TLS connection between IBM ADDI Build Client and IBM ADDI Connect for Mainframe is enabled. IBM ADDI 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 ADDI Build and Enabling TLS Connection between IBM ADDI Build Client and IBM ADDI Connect for Mainframe.

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

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

Important: Starting with IBM ADDI 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 ADDI Connect for Mainframe

The tenth positional parameter in the IBM ADDI 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 ADDI 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 ADDI 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 ADDI 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 ADDI Build Client retrieves project information from the mainframe, it will request IBM ADDI 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 ADDI Connect for Mainframe task. It is not expected that the z/OS user ID of a typical ADDI 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 ADDI 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 ADDI Connect for Mainframe is started.
Figure 3. IAYMF0051I message

As previously stated, ensure that IBM ADDI Build Client is also configured to match the authentication setting (Y/N) used on IBM ADDI 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 ADDI Build Configuration and IBM ADDI Build Configuration 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 ADDI 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 ADDI 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 ADDI 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 ADDI 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 ADDI projects.
For more detailed information, you can enable debug trace on IBM ADDI 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 ADDI 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 ADDI Connect for Mainframe Messages.