Distributed identity filters configuration in z/OS security

Before you can map distributed identities to System Authorization Facility (SAF) users, you must first configure distributed identity filters in the z/OS® security product for WebSphere® Application Server.

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 syntax for creating a distributed identity filter using the RACMAP command exists:

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

The <SAFUser> element is the SAF user in the z/OS security product, <distributedUserId> is the distributed identity, <distributedRealmName> is the realm name of the distributed identity and <someLabel> is a text field that describes this distributed identity filter.

Use the following command to activate the IDIDMAP class. This command only needs to be run once at the beginning:

SETROPTS CLASSACT(IDIDMAP) RACLIST(IDIDMAP)

Use the following command after any changes are made to RACMAP profiles for the changes to take effect:

SETROPTS RACLIST(IDIDMAP) REFRESH

Note: In some cases, changes to the RACMAP filters do not take effect immediately on the WebSphere server. See the section Activating RACMAP filter changes for an authenticated user for more details.

Mapping distributed users to SAF users:

If you have configured a non-local OS registry, you can map a distributed user, such as a Lightweight Directory Access Protocol (LDAP) user, to an SAF user. The distributed user name that WebSphere Application Server uses when mapping to an SAF user is the value returned by the WSCredential.getUniqueSecurityName() API. This method returns the unique user name as it applies to the configured user registry. For LDAP, this would be the full distinguished name (DN). For a custom configuration, this is whatever the getUniqueUserId() API in the custom registry returns. For federated repositories, this is the uniqueName property in virtual member manager.

The distributed realm name used by WebSphere Application Server is determined by the WSCredential.getRealmName() API. The realm name that is returned depends on the user registry that is being configured. For LDAP, the realm name is the ldapHostName:ldapPortNumber. For custom user registry, it is whatever you have configured the getRealm() method to return in your implementation. For federated repositories, the realm name is the realm you specified on the realm name field of the federated repositories panel.

In the following example, the LDAP user, LDAPUser1, is mapped to the SAF user, USER1:

RACMAP ID(USER1)  MAP USERDIDFILTER(NAME('CN=LDAPUser1,o=ibm,c=us'))  
REGISTRY(NAME('ccwin12.austin.ibm.com:389')) 
WITHLABEL('Mapping LDAP LDAPUser1 to USER1')

In this example, the custom user registry user, CustomUser3, is mapped to the SAF user, USER3:

RACMAP ID(USER3)  MAP USERDIDFILTER(NAME('CustomUser3'))  
REGISTRY(NAME('customRealm')) WITHLABEL('Mapping custom CustomUser3 to USER3')

In this example, the federated repositories user, wimUser5, is mapped to the SAF user, USER5:

RACMAP ID(USER5)  MAP USERDIDFILTER(NAME('uid=wimUser5,o=defaultWIMFileBasedRealm
'))  REGISTRY(NAME('defaultWIMFileBasedRealm')) WITHLABEL('Mapping custom wimUser5 to USER5')

Mapping Kerberos principals to SAF users:

If you have a local OS registry configured on z/OS operating systems with the Kerberos authentication mechanism, you might want to map a Kerberos user to a SAF user. In this case, the distributed identity is the Kerberos principal name. The distributed realm name is the Kerberos realm name of the KDC.

The following example maps a Kerberos user to a SAF user:

kerberosUser@KRB390.IBM.COM to the SAF user  WSADMIN:
RACMAP ID(WSADMIN)  MAP USERDIDFILTER(NAME('kerberosUser'))  
REGISTRY(NAME('KRB390.IBM.COM')) WITHLABEL('Mapping Kerberos kerberosUser to WSADMIN')

Mapping multiple distributed identities to one SAF user:

You can use the wildcard (*) to create a filter that maps multiple distributed identities to one SAF user. you can specify the wildcard (*) for the distributed identity name and realm name. For example, if you want each user from your LDAP server, accountingUnit.acme.ibm.com, to be mapped to the SAF user ACCT, you can define a filter as in the following example:

RACMAP ID(ACCT) MAP USERDIDFILTER(NAME('*'))  
REGISTRY(NAME('accountingUnit.acme.ibm.com:389')) 
WITHLABEL('Mapping accounting users to ACCT')

If the distributed identity name is a distinguished name, you can omit attributes of the DN value when creating the filter, starting with the most specific attributes. For example, you can create a filter that maps all LDAP users that have the attributes O=ibm,C=us to the SAF user, ACCT2, as in the following example:

RACMAP ID(ACCT2) MAP USERDIDFILTER(NAME('O=ibm,C=us'))  
REGISTRY(NAME('accountingUnit.acme.ibm.com:389')) 
WITHLABEL('Mapping US accounting users to ACCT2')

Mapping certificates and distinguished names to SAF users

The distributed identity is the distinguished name or attributes of the distinguished name. The distributed realm name is the current realm. For example:

RACMAP ID(ACCT3) MAP USERDIDFILTER(NAME('O=ibm,C=us'))  
REGISTRY(NAME('localOSRealm'))
WITHLABEL('Mapping certificate or distinguished names to ACCT3')

Creating a default distributed identity filter:

You might want to define a default filter that maps any distributed identity that is not found in any of the other filters to a SAF user with the RESTRICTED attribute.

The following example demonstrates how to create a default filter:

RACMAP ID(WSGUEST) MAP USERDIDFILTER(NAME('*'))  
REGISTRY(NAME('*')) WITHLABEL('The default filter')

Activating RACMAP filter changes for an authenticated user:

When a user authenticates with the registry, the user is also added to the authentication cache. Any changes to the RACMAP filters in the z/OS security product do not take effect until this user is removed from the authentication cache.

If you want these changes to take effect immediately, call the SecurityAdmin Mbean on the server that you want to update. You can either invoke the purgeUserFromAuthCache operation to remove one specific user, or the clearAuthCache operation to remove all users from the authentication cache. The authentication cache is also cleared once the server is restarted.

Refer to the SecurityAdmin MBean Definition Table for details on the Mbean and its operations.

For example, a distributed identity, LDAPUser1, is not mapped to an SAF user, and attempts to log in to a servlet protected by a role. Since the user ID and password are valid, the user is authenticated and added to the authentication cache. However, since LDAPUser1 is not mapped to an SAF user, a default unauthenticated ID, WSGUEST, is used for authorization.

LDAPUser1 is unable to access the servlet since WSGUEST is not authorized to the servlet role. The z/OS security administrator then defines a RACMAP filter to map LDAPUser1 to the SAF user, USER1. LDAPUser1 still cannot access the servlet until this ID is removed from the authentication cache.

For more information about the RACMAP command, refer to the z/OS Security Server RACF® Command Language Reference.