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.
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.
Enabling the z/OS User Authentication feature for IBM AD Connect for Mainframe
IAYLSTNR
in the
SIAYSAMP
distribution library of IBM AD Connect for Mainframe.
Grant user ID access to necessary mainframe resources
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.