(zos)

Distributed identity mapping using SAF

The distributed identity mapping feature using System Authorization Facility (SAF) for z/OS provides some major benefits, and is new in this version of WAS.

This release of WAS enables you to use z/OS System Authorization Facility (SAF) security to associate a SAF user ID with a distributed identity. When you use this feature, we can maintain the original identity information of a user for audit purposes and have less to configure in WebSphere Application Server.

Your z/OS security product must be at the appropriate version that supports the distributed identity mapping. The correct SAF version is 7760 or later. For Resource Access Control Facility (RACF ), you must be at z/OS version 1.11 or later.

Some advantages in using this feature include:

• For a non-Local OS registry, such as LDAP, and are using either SAF authorization, z/OS thread identity synchronization (SyncToThread) or the connection manager RunAs thread identity option, we can directly map the LDAP user to a SAF user in the z/OS security product with the RACMAP SAF profiles. No mapping modules are required; therefore do not configure these modules in WebSphere Application Server. SMF audit records contain both the LDAP user name and the mapped SAF user ID.

• If we are using Local OS registry, and are using Kerberos or Simple and Protected GSS-API Negotiation (SPNEGO), we can directly map the Kerberos principal to an SAF user in the z/OS security product. No mapping modules are required; therefore do not configure these modules in WebSphere Application Server. SMF audit records contain both the Kerberos principal and the mapped SAF user ID.

The SAF distributed identity mapping feature is not supported in a mixed-version cell (nodes prior to WebSphere Application Server Version 8.0).

Benefits when using distributed identity mapping

Distributed identity mapping in SAF provides two major benefits:

• When a user is audited on the z/OS operating system using SMF, the audit record contains both the distributed identity and the mapped SAF user ID. This improves cross-platform interoperability and provides value for both host centric and heterogeneous application environments.

• The mapping of distributed identities is handled by the z/OS security administrator. There is no need to configure mapping modules in the WAS configuration.

When to use distributed identity mapping

The following scenarios describe how we can use the new distributed identity mapping feature in SAF.

• Scenario 1: When we have a non-Local OS registry configured with either SAF authorization, z/OS thread identity synchronization (SyncToThread) or the connection manager RunAs thread identity option, we can use this feature to map your registry user to an SAF user. In previous releases, this process had to be done with JAAS login modules that were configured in WebSphere Application Server.

  The advantages of using distributed identity mapping are that the SMF audit records will contain both the distributed user and the SAF user, and that the mapping is controlled by the z/OS Security administrator.

  When mapping a non-Local OS registry user, the distributed user name is the value returned by the WAS WSCredential.getUniqueSecurityName() API. The realm name is determined by the WAS WSCredential.getRealmName() API.

  To enable distributed identity mapping for this scenario, no further changes are needed in the security configuration.

  For scenario 1, if you are using the Federated Repositories registry configured with the UserRegistry bridge, we can still take advantage of the SAF distributed identity mapping feature. If we log in with a SAF user, it is not mapped. However, if you log in with a distributed user, it is mapped to a SAF user.

• Scenario 2: When we have a Local OS registry configured on the z/OS platform with Kerberos or SPNEGO enabled, we can map the Kerberos principal name to a SAF user using the distributed identity mapping feature. In previous releases, you could use either a JAAS mapping login module that was configured in WebSphere Application Server or the KERB segment of the SAF user in the z/OS security product.

  The advantage of using distributed identity mapping is that the SMF records will contain both the Kerberos user and the mapped SAF user.

  When mapping a Kerberos user, the distributed user name is the Kerberos principal name. The realm name is the Kerberos realm name of the Kerberos Key Distribution Center (KDC). For more information on creating distributed identity filters in the z/OS security product, read the Distributed identity filters configuration in z/OS security topic.

  To enable distributed identity mapping for this scenario:

  • Navigate to Security > Global security > Kerberos configuration.

  • Select the radial button for Use the RACMAP profiles in the SAF product for distributed identity mapping.

  To make this change with wsadmin scripting, set the security custom property com.ibm.websphere.security.krb.useRACMAPMappingToSAF=true.

• Scenario 3: When we have a Local OS registry configured, we can map an asserted certificate or an asserted distinguished name to a SAF user.

  In previous releases, the first attribute of the asserted DN name was mapped to a SAF user. The advantage of using the distributed identity mapping for an asserted DN is the added flexibility for mapping users, the mapping is controlled by the z/OS security administrator, and the SMF audit records will contain both the asserted DN name and the mapped SAF user ID. In previous releases, an asserted certificate was mapped to a SAF user using the RACDCERT MAP function in SAF. The advantage of using the distributed identity mapping is that the SMF audit records will contain both the certificate DN name and the mapped SAF user ID. Additionally, the SAF database saves space by not having to store the digital certificates.

  When mapping an asserted certificate or DN name in SAF, the distributed user is the DN name and the realm name is the current SAF realm.

  When mapping an asserted certificate or DN name in SAF, the distributed user is the DN name and the realm name is the current SAF realm.

  To enable distributed identity mapping for this scenario:

  • Navigate to Security > Global security > CSIv2 Inbound communications.

  • For Attribute later settings, select Map certificate and DN using SAF distributed identity mapping.

  To make this change with wsadmin scripting, set the security custom property com.ibm.websphere.security.certdn.useRACMAPMappingToSAF=true

• (zos) Scenario 4: When we have a Local OS registry configured, we can map a certificate received in the CSIv2 transport layer to a SAF user.

  In previous releases, a certificate was mapped to a SAF user using the RACDCERT MAP function in SAF. The advantage of using the distributed identity mapping is that the SMF audit records will contain both the certificate DN name and the mapped SAF user ID.

  (zos) When mapping a certificate received in the CSIv2 transport layer, the distributed user is the DN name and the realm name is the current SAF realm..Additionally, the SAF database saves space by not having to store the digital certificates.

  To enable distributed identity mapping for this scenario:

  • Navigate to Security > Global security > CSIv2 Inbound communications.

  • For Transport layer settings, select Map certificate using SAF distributed identity mapping.

  To make this change with wsadmin scripting, set the security custom property com.ibm.websphere.security.certificate.useRACMAPMappingToSAF=true.

  If wer DN name has a blank space between the attributes, then you should apply the RACF APAR OA34258, or PTF UA59873, and the SAF APAR OA34259, or PTF UA59871, to correctly parse the blanks.

identity mapping scenarios. The following table summarizes

Scenario	SAF version	User registry	SAF authorization=true or SyncToThread=true or runAs=true?	JAAS mapping module configured?	Kerberos or SPNEGO enabled
Scenario 1	7760 or later (z/OS 1.11 or later for RACF)	non-Local OS	yes	no	n/a
Scenario 2	7760 or later (z/OS 1.11 or later for RACF	Local OS	yes	no	yes
Scenario 3	7760 or later (z/OS 1.11 or later for RACF	Local OS	yes	no	n/a
(zos) Scenario 4	7760 or later (z/OS 1.11 or later for RACF	Local OS	yes	no	n/a

Considerations when configuring distributed identity mapping

When you configure distributed identity mapping, you must complete the following actions:

• Determine the SAF version. We must first ensure that the z/OS security version is at SAF version 7760 or later. If we are using RACF, you must be at z/OS version 1.11 or later. A new AdminTask, isSAFVersionValidForIdentityMapping(), is provided to help determine this. Additionally, the informational message, SECJ6233I, is printed in the server job log, which indicates the current SAF version.

• Remove unnecessary JAAS login modules. We must ensure that we do not have the com.ibm.ws.security.common.auth.module.MapPlatformSubject login JAAS module configured in the WebSphere configuration. In previous releases of WAS, this is how mapping a distributed user to a SAF user was completed. As long as we have this login module configured, the security configuration continues to use the previous method for mapping a distributed user to a SAF user. If we are configuring a new WebSphere Application Server Version 8.0 cell, this JAAS login module is not configured by default; therefore, no further action is necessary. However, if we have migrated your cell to WebSphere Application Server Version 8.0 , the JAAS login module likely exists and should be removed. We can use the console or wsadmin scripting to remove this login module. We can also use the provided Jython script, removeMapPlatformSubject.py, which searches for and removes this login module from the appropriate login entries. For more information on how to use this script, read the removeMapPlatformSubject script topic.

  To delete the JAAS login module on the console...

  1. Click Security > Global security > Java Authentication and Authorization Service > System logins.

  2. Click DEFAULT.

  3. Select the checkbox for com.ibm.ws.security.common.auth.module.MapPlatformSubject login JAAS module, then click Delete.

  4. Click OK.

  5. Repeat for steps 2-4 for the System logins of WEB_INBOUND, RMI_INBOUND and SWAM_ZOSMAPPING.

• Map SAF users in the z/OS security product. Use the RACMAP command in the z/OS security product to configure a distributed identity filter. Use this filter to map multiple distributed users to one SAF user, or we can have a one-to-one mapping. The distributed identity filter consists of two parts: the distributed user name and the realm name of the registry where the distributed user exists.

  In some cases, changes to the RACMAP filters do not take effect immediately on the WebSphere server. Read "Activating RACMAP filter changes for an authenticated user" in the Distributed identity filters configuration in z/OS security topic for more details.

  When configuring the SAF distributed identity mapping feature at the security domain level, note the realm name for that domain. We can choose to provide a realm name or to use the system-generated realm name. Regardless of which option you choose, this is the realm name that use when defining the mappings in the SAF registry.

• Make the necessary changes to the security configuration. Read scenarios 1-4 to determine additional changes we might need to make to the security configuration.

Distributed identity filters configuration in z/OS security

removeMapPlatformSubject script

SecurityConfigurationCommands (AdminTask)

Related information:

Interface WSCredential