Configuring distributed identity propagation

Follow these steps to configure the propagation of distributed identities over IPIC connections to CICS® for user authorization.

Before you begin

  1. Configure an IPCONN definition in CICS with USERAUTH=IDENTIFY. For more information, see Configuring an IPIC connection in CICS.
  2. Configure a zosconnect_cicsIpicConnection element in server.xml. For more information, see Configuring an IPIC connection in IBM z/OS Connect.

About this task

The server.xml file is updated to define an LDAP user registry. As CICS retrieves the mapped SAF user IDs from distributed identities for user authorization, there is no need to map the distributed identity to a SAF user ID in IBM z/OS Connect. No change to the zosconnect_cicsIpicConnection element is required.

Procedure

  1. Configure an LDAP user registry.
    For example, add the following elements to server.xml:
    
    <featureManager>
        ...
        ...
        <feature>ldapRegistry-3.0</feature>
    </featureManager> 
    <ldapRegistry id="LDAP"
        realm="SampleLdapIDSRealm" host="myserver" port="123"
        ignoreCase="true"         
        baseDN="o=myco,c=us"       
        userFilter="(&amp;(uid=%v)(objectclass=ePerson))"       
        groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
        userIdMap="*:uid"
        groupIdMap="*:cn"       
        groupMemberIdMap="myco-allGroups:member"
        ldapType="IBM
        Tivoli Directory Server"       
        searchTimeout="8m">   
    </ldapRegistry>
  2. Define users in the LDAP registry and give them the required access to the IBM z/OS Connect server in the authorization-roles element in the server.xml file.
  3. Set requireAuth="true" on the zosconnect_zosConnectManager element or on the zosconnect_services element for the individual CICS services.
    This setting ensures that API and service requests fail with a 401 HTTP response if invalid credentials are supplied, and no attempt is made to process the request without valid credentials. If requireAuth="false" is defined, the request is rejected by the CICS server and failsCICS with a 500 HTTP response.
  4. Map each distributed identity to a SAF user ID in the security manager that is used by CICS. More than one distributed identity can be mapped to the same SAF user ID.
    Note: You only need to set <safCredentials mapDistributedIdentities="true"/> if you are using SAF authorization in IBM z/OS Connect. The distributed identity is always mapped to a SAF identity in CICS.

Results

You can view the distinguished name and realm for a distributed identity in the association data of the CICS task, by using the command CEMT INQUIRE ASSOCIATION(taskid), or in the Task Associations view in CICS Explorer.

The distinguished name and realm information can also be recorded to SMF in type 110, subtype 01 records. For more information, see Identity class data. The identity monitoring data values of interest are MNI_ID_USERID, which contains the mapped SAF user ID, and the MNI_ENTRY_FIELD, which contains the distinguished name and realm. These fields are described in Identity class data: Listing of data fields and MNI - Transaction identity monitoring data. CICS Transaction Server provides a sample program to print monitoring data, called DFH$MOLS. For more information, see Sample monitoring data print program (DFH$MOLS).