How to configure basic authentication with an LDAP user registry z/OS Connect zosConnect-3.0

zosConnect-3.0 Applies to zosConnect-3.0.

Configure IBM® z/OS® Connect to perform basic authentication with a Lightweight Directory Access Protocol (LDAP) user registry.

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

Before you begin

  • You should be familiar with the information in API provider authentication and identification.
  • You need the following information about the LDAP server:
    • The type of LDAP server. For example, IBM Secure Directory Server or Microsoft Active Directory Server.
    • Connection details such as host, port and whether the connection to the LDAP server is secured with TLS.
    • For Microsoft Active Directory Server, the distinguished name (DN) for the application server, which is used to bind to the directory service and the bind password.
    • The base distinguished name (DN) which indicates the starting point for LDAP searches in the directory service.
    • The users and groups that are to be granted access to z/OS Connect.
  • You must have write access to the configuration file.

About this task

You configure z/OS Connect to perform basic authentication by using an LDAP user registry.

Note: Authentication is not enforced unless authorization roles are defined for the API operations. During authorization the LDAP groups that the authenticated LDAP user is a member of are compared against the required API operation roles.

Procedure

  1. Enable the appSecurity-2.0 Liberty feature in the configuration file.
    For example, 
    <featureManager> <feature>appSecurity-2.0</feature> </featureManager>

In the following steps, you configure a Lightweight Directory Access Protocol (LDAP) user registry that references an existing LDAP server, so that its users and groups can be used for authentication and authorization.

  1. Follow the instructions in Opens in new window. Configuring LDAP user registries in Liberty in the WebSphere Application Server Liberty documentation where references to Liberty refer to z/OS Connect.
    For more information about the ldapRegistry element and its attributes, see Opens in new window. LDAP User Registry (ldapRegistry) in the WebSphere Application Server Liberty documentation.
    The following example shows an LDAP registry for an IBM Secure Directory Server. Note that the ldapType element must be set to IBM Tivoli Directory Server rather than IBM Secure Directory Server.
    <ldapRegistry id="ldap" realm="SampleLdapIDSRealm"
    host="ourLDAP.ibm.com" port="389" ignoreCase="true"  
    baseDN="o=mop,c=fr"  
    ldapType="IBM Tivoli Directory Server"> 
    <idsFilters 
        userFilter="(&amp;(uid=%v)(objectclass=ePerson))"  
        groupFilter="(&amp;(CN=%v)
            (|(objectclass=groupOfNames) 
            (objectclass=groupOfUniqueNames) 
            (objectclass=groupOfURLs)))" 
        userIdMap="*:uid"  
        groupIdMap="*:CN"  
        groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember; 
            groupOfNames:member;groupOfUniqueNames:uniqueMember"> 
    </idsFilters>     
</ldapRegistry>
  2. After your configuration file is updated with the features and ldapRegistry elements, restart z/OS Connect.
    Check the messages.log file to ensure that the LDAP registry feature is installed and that there are no error messages from a misconfigured ldapRegistry entry. The following information messages in the messages.log file show that the ldapRegistry feature is installed.
    CWIMK0009I: The user  federation service is ready.
CWWKS0008I: The security service is ready.
CWWKF0012I: The server installed the following features: [... appSecurity-2.0 ... ldapRegistry-3.0 ...]
  3. Optional: Use an alternative LDAP group attribute as the authenticated user group name(s) in z/OS Connect.
    For example, if your LDAP server defines a group with a distinguished name (DN) and common name (CN), where both the DN and CN values are unique within your LDAP server, then you can also configure a federatedRepository element to include your ldapRegistry element and override the LDAP group attribute that is used to identify the group name(s) in the authenticated user subject. To use the LDAP group CN value to identify the group name(s) in the authenticated user subject, add the following federatedRepository element to the server configuration file.
    
<federatedRepository>
      <primaryRealm name="SampleLdapIDSRealm">
          <participatingBaseEntry name="o=mop,c=fr"/>
          <uniqueGroupIdMapping inputProperty="CN" outputProperty="CN"/>
      </primaryRealm> 
</federatedRepository>
    where:
    • The name attribute of the participatingBaseEntry subelement must match the baseDN attribute of the ldapRegistry element. For example: "o=mop,c=fr".
    • The outputProperty of the uniqueGroupIdMapping subelement specifies the LDAP group attribute to be used to identify the group in the authenticated user subject.

The following step is only applicable to z/OS Connect Servers deployed on z/OS.

  1. Optional: Map the LDAP user ID received in the basic authentication header to a SAF user ID.
    If you require a SAF user ID because z/OS Connect uses SAF for authorization, or the System of Record requires a SAF user ID, then you can map the authenticated LDAP user ID to a SAF user ID. For more information, see the task How to map an LDAP user ID to a RACF user ID for z/OS Connect zosConnect-3.0.

Results

Users and groups that match the filters that are defined in the ldapRegistry element can be used to authenticate with z/OS Connect.