How to map an LDAP user ID to a RACF user ID

Configure RACF® and a IBM® z/OS® Connect server to map an LDAP user ID to a RACF user ID.

zosConnect-2.0 Applies to zosConnect-2.0.

Perform this procedure if your IBM z/OS Connect server is configured to perform authorization using RACF, or the System of Record (SoR) requires a RACF user ID, but the client authenticates with an LDAP user ID as its identity. For example, the client might use a basic authentication (HTTP Authorization) header.

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

Before you begin

  • You must have configured the IBM z/OS Connect server to require authentication and to use basic authentication, by following the appropriate steps in the task How to configure basic authentication with an LDAP user registry.
  • You must have configured the IBM z/OS Connect server to access RACF, by completing the task How to activate and configure the SAF user registry. However, you do not need to specify the safRegistry element in the server.xml configuration file.
  • If you specify both safRegistry and ldapRegistry elements in the server.xml configuration file, then you should also configure a federatedRepository element, so that you can specify the primary realm name. This ensures that the primary realm name used by the IBM z/OS Connect server when it attempts to map the LDAP user ID to the RACF user ID, matches the REGISTRY NAME value you will specify on the RACMAP command. Only one security realm is supported. If you do not specify a primary realm name, the realm name from one of the existing user registries is used, but the same realm name might not be returned. For more information, see Federation of user registries in the WebSphere® Application Server for z/OS Liberty documentation.
  • You need to know the distinguished name (DN) of the LDAP user ID to be mapped.
  • You need to know the RACF user ID to which the LDAP user ID is to be mapped, and that RACF user ID must exist.
  • You must have write access to the server.xml configuration file.

About this task

This task makes the following assumptions:
  • The client is sending an LDAP user ID and password in the HTTP Authorization header of a request to a IBM z/OS Connect server, to authenticate using basic authentication.
  • RACF is being used as the security manager. If you are using an alternative External Security Manager, refer to the appropriate product documentation for the equivalent commands.

Procedure

  1. Activate the RACF IDIDMAP class
    Enter the following RACF command:
    SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)
  2. Create a mapping in RACF to associate the LDAP user ID to a RACF user ID.
    For example, enter the following RACF command:
    RACMAP MAP ID(EMPLOY1) USERDIDFILTER(NAME('cn=JeanLeclerc,ou=employees,o=ibm,c=fr')) REGISTRY(NAME('SampleLdapIDSRealm')) WITHLABEL('LDAP Mapping EMPLOY1')
    The command uses the following values:
    • EMPLOY1 is the RACF user ID to which the LDAP user ID is to be mapped.
    • cn=JeanLeclerc,ou=employees,o=ibm,c=fr is the distinguished name (DN) of the LDAP user ID to be mapped.
    • SampleLdapIDSRealm is the value specified as the realm attribute of the ldapRegistry element in the server.xml configuration file or, if federated registries are being used, the federatedRegistry element. Alternatively, replace SampleLdapIDSRealm with * (the asterisk character) to match to any registry realm name.
  3. Refresh the RACF IDIDMAP class.
    For the changes to take effect. issue the following RACF command:
    SETROPTS RACLIST(IDIDMAP) REFRESH
  4. Check that the RACF mapping has been created.
    Enter the following RACF command:
    RACMAP QUERY USERDIDFILTER(NAME('cn=JeanLeclerc,ou=employees,o=ibm,c=fr')) REGISTRY(NAME('SampleLdapIDSRealm'))
    The following screen capture shows the expected response:
    RACMAP QUERY result. RACF user ID: EMPLOY1
  5. Configure the server to call RACF to perform the mapping of the received LDAP user ID to the RACF user ID.
    Add the following element to the server.xml configuration file:
    <safCredentials mapDistributedIdentities="true"/>
    For more information about the safCredentials element, see Server configuration in the IBM WebSphere Application Server for z/OS Liberty documentation.
  6. Start, or restart the server if it was already running, to pick up the changes made to the RACF class profiles.
    If you have linked to this task from another task, you might wish to complete the steps in that task before restarting the server.

Results

The LDAP user ID is now mapped to a RACF user ID. When this LDAP user ID is sent as the identity in a request, the IBM z/OS Connect server will attempt to authenticate the user ID and map it to the RACF user ID, so that the RACF user ID can be used for authorization and when connecting to the System of Record (SoR).