Configuring distributed identity filters in z/OS security

Distributed identity filters must be configured when the mapDistributedIdentities attribute in the safCredentials configurations element is set to true.

About this task

Before you map distributed identities to System Authorization Facility (SAF) users, you must first configure distributed identity filters in z/OS security.

The distributed identity filter in the SAF class RACMAP consists of the distributed user name and the realm name of the distributed user name. You can configure the filters to map many distributed identities to one SAF user or you can have a one-to-one mapping.

The following example illustrates the syntax for creating a distributed identity filter that uses the RACMAP command:

RACMAP ID(<SAFUser>) MAP USERDIDFILTER(NAME('<distributedUserId>'))
REGISTRY(NAME('<distributedRealmName>'))
    WITHLABEL('<someLabel>')

In the example:

The SAFUser element is the SAF user in z/OS security.
The distributedUserID element is the distributed identity.
The distributedRealmName element is the realm name of the distributed identity.
The someLabel element is a field that describes this distributed identity filter.

When you use LDAP and Basic or SAF registries, the user registries are automatically federated. In Liberty, only one realm is supported. If you do not specify a federated repository with a primary realm identified, one of the realm names from one of the defined user registries is used.

When you use multiple registries and are taking actions based on the realm name of the user, define the federatedRepository with a primaryRealm attribute defined.

Procedure

Activate the IDIDMAP class.
This command needs to be run only once at the beginning. SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)
After you edit the RACMAP profiles, you must use the following command for the changes to take effect:
SETROPTS RACLIST(IDIDMAP) REFRESH

Example

In Liberty z/OS, the distributedRealmNamedoes not have the format on an LDAP URL. Instead, the value that you must set on the RACMAP profile for distributedRealmName comes from the primaryRealm name of the federatedRepository element. If the federatedRepository element is not coded, Liberty determines the distributedRealmName from the realm attribute that is set for the elements during each user registry.

The following example illustrates the LDAP user (LDAPUser1) mapped to the SAF user (USER1) for a Liberty z/OS server when the realm name is 'FEDREALM'.

      RACMAP    ID(USER1)  MAP
                USERDIDFILTER(NAME('CN=LDAPUser1,o=ibm,c=us')) 
                REGISTRY(NAME('FEDREALM')) WITHLABEL('Mapping LDAP
                LDAPUser1 to USER1')

The following example shows a federatedRepository element which may be used together with the example RACMAP profile.

<federatedRepository>        
        <primaryRealm name="FEDREALM">
        </primaryRealm>    
        </federatedRepository>

Avoid trouble:

If you choose to use distributed identity filters in Liberty z/OS with a federated repository that includes an SAF user registry, it is best to specify distributedRealmName on the primaryRealm name attribute of the federatedRepository element.

If distributedRealmName is not specified by using the primaryRealm name attribute of the federatedRepository element, the distributedRealmName that Liberty z/OS uses might not be what you would expect.

If it is not specified using primaryRealm, the distributedRealmName for RACMAP checking can be derived from a number of difference sources, depending on how each user registry is configured in your server.xml file.

To avoid confusion, specify the distributedRealmName by using the primaryRealm attribute.