The distributed identity mapping feature using System Authorization
Facility (SAF) for z/OS® provides
some major benefits, and is new in this version of WebSphere® Application Server.
This release of WebSphere Application
Server 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, you 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:
- If you are using a non-Local OS registry, such as Lightweight
Directory Access Protocol (LDAP), and are using either SAF authorization, z/OS thread identity synchronization
(SyncToThread) or the connection manager RunAs thread identity option,
you 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 you are using Local OS registry, and are using Kerberos or
Simple and Protected GSS-API Negotiation (SPNEGO), you 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.
Note: 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 WebSphere Application Server configuration.
When to use distributed identity mapping
The
following scenarios describe how you can use the new distributed identity
mapping feature in SAF.
- Scenario 1: When you 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, you can use this feature to map your
registry user to an SAF user. In previous releases, this process had
to be done with Java Authentication
and Authorization Service (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 WebSphere Application
Server WSCredential.getUniqueSecurityName() API. The realm name is
determined by the WebSphere Application
Server WSCredential.getRealmName() API.
To enable distributed
identity mapping for this scenario, no further changes are needed
in the security configuration.
Note: For scenario 1, if you
are using the Federated Repositories registry configured with the
UserRegistry bridge, you can still take advantage of the SAF distributed
identity mapping feature. If you 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 you have a Local OS registry configured
on the z/OS platform with Kerberos
or SPNEGO enabled, you 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 you have a Local OS registry configured,
you 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 by 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
Scenario 4: When you have
a Local OS registry configured, you 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 by 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.
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.
Note: If
your 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.
Table 1. Distributed
identity mapping scenarios. The following table summarizes
the configuration for each of the distributed identity mapping scenarios.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 |
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. You must first ensure that your z/OS security version is at SAF
version 7760 or later. If you 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. You must ensure
that you do not have the com.ibm.ws.security.common.auth.module.MapPlatformSubject
login JAAS module configured in your WebSphere configuration. In previous releases
of WebSphere Application
Server, this is how mapping a distributed user to a SAF user was completed.
As long as you have this login module configured, the security configuration
continues to use the previous method for mapping a distributed user
to a SAF user. If you 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 you have migrated your
cell to WebSphere Application
Server Version 8.0 , the JAAS login module likely exists and should
be removed. You can use the administrative console or wsadmin scripting
to remove this login module. You 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 administrative console,
complete the following steps:
- Click Security > Global security > Java Authentication and Authorization Service
> System logins.
- Click DEFAULT.
- Select the checkbox for com.ibm.ws.security.common.auth.module.MapPlatformSubject
login JAAS module, then click Delete.
- Click OK.
- 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 you 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.
Note: 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. You 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
you must use when defining the mappings in the SAF registry.
- Make the necessary changes to the security configuration.
Read scenarios 1-4 listed above to determine additional changes you
might need to make to the security configuration.