(ZOS) Install and configure a custom System Authorization Facility mapping module for WAS

Use this task to add a custom System Authorization Facility (SAF) mapping module to one of the system login modules using the administrative console.

To use a pluggable login module to perform Java EE identity to Resource Access Control Facility (RACF ) user mapping, configure a pluggable mapping module, followed by configuring the WebSphere Application Server for z/OS-supplied module, com.ibm.ws.security.common.auth.module.MapPlatformSubject, in the appropriate JAAS system login configurations. When SAF Authorization or Synch to OS Thread is configured, this approach enables an installation to configure the active WAS registry as either a standalone LDAP registry or a standalone custom registry.

WAS does not support a local operating system registry on any platform under the federated repository functionality. Thus, a SAF-managed RACF registry is not supported under the federated repository functionality.

Update: A SAF-managed RACF registry is supported under the federated repository functionality. In previous releases, it was not supported. To configure the SAF mapping module to use federated repositories with a SAF user registry adapter for SAF authorization, see Configuring a custom System Authorization Facility mapping module for federated repositories.

Before proceeding, make sure you know how to write a mapping module to get a SAF identity. For more information, refer to Writing a custom System Authorization Facility (SAF) mapping module with non-local operating system. If we use anything other than the sample, we must build the relevant classes and install them into the <WAS_HOME>/classes directory for each node in the cell, including the deployment manager node in a cell. If Java 2 security is enabled, ensure that the server.policy file is updated to provide appropriate permissions.

If we are using the SAF distributed identity mapping feature, we do not need to configure a mapping module.

The custom SAF mapping module (either com.ibm.websphere.security.SampleSAFMappingModule or a customer-written mapping module) must be added to each of the following system login module entries and must be changed manually to the second-to-last position in the order for the system login modules as indicated:

• For Simple WebSphere Authentication echanism (SWAM), add the entry to the SWAM login module.

  SWAM is deprecated in WAS v9.0 and will be removed in a future release.

• For LTPA, add the entry to the WEB_INBOUND, RMI_INBOUND, and DEFAULT login modules.

  LTPA is the default authentication mechanism for WAS v9.0.

For base configuration, if we select SWAM as your authentication mechanism, update the SWAM entry. However, if we plan to use LTPA as your authentication mechanism, set up all four system login module entries. For a WAS ND configuration, we only need to configure the LTPA authentication mechanism configuration entries.

Tasks

1. Configure the custom mapping module:

   1. Click Security > Global security.

   2. Under Java Authentication and Authorization Service, click System logins > login_module_name.

   3. Under Additional properties, click JAAS login modules > New.

   4. Enter the class name of the custom login module in the Module Classname file. (Use com.ibm.websphere.security.SampleSAFMappingModule for the shipped sample module).

   5. Click Apply to add the new module to the login module list.

2. Configure the supplied com.ibm.ws.security.common.auth.module.MapPlatformSubject login module:

   1. Click Security > Global security.

   2. Under Java Authentication and Authorization Service, click System logins > login_module_name

   3. Under Additional properties, click JAAS login modules > New.

   4. Enter the class name: com.ibm.ws.security.common.auth.module.MapPlatformSubject.

   5. Click Apply to add the new module to the login module list.

3. Click Security > Global security.

4. Under Authentication, expand JAAS and click System logins > login_module_name.

5. Under Additional properties, click JAAS login modules > Set Order, and verify that the new mapping module comes before com.ibm.ws.security.common.auth.module.MapPlatformSubject and after com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule.

   The new mapping module must come before com.ibm.ws.security.common.auth.module.MapPlatformSubject and after com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule.

6. Select the box next to the new mapping module and then click Move up. When the mapping modules are in the correct order, click Apply, then Save, and Save (be sure to select Synchronize changes with Nodes if we are working with a WAS ND cell).

What to do next

Make these changes for each of the system login modules needed for our WAS for z/OS configuration. The choice of which system login modules are needed is based on your authentication mechanism (SWAM or LTPA).

If the SAF identity mapping module we installed has configurable properties, we can update them by creating custom properties in the JAAS system logins panel in the administrative console. Use this example to update properties if we used the SampleSAFMapping module as a prototype and updated the else clause to provide custom mapping logic. In this case, create the useWSPrincipleName custom property and set it to false for each affected JAAS login configuration that uses the modified SampleSAFMappingModule.

1. Click Security > Global security.

2. Under Java Authentication and Authorization Service, click System logins > login_module_name.

3. Under Additional properties, click JAAS login modules > com.ibm.websphere.security.SampleSAFMappingModule.

4. Under Additional properties, click Custom Properties > New.

5. Enter the custom property name useWSPrincipalName and the value false.

6. Click Apply, Save, and Save.

Repeat this process for each of the system login modules that use the modified SampleSAFMappingModule.

Related:

(ZOS) Custom System Authorization Facility mapping modules

(ZOS) Distributed identity mapping using SAF

Developing programmatic logins with the JAAS

Enable pluggable login modules to map Java EE identities to System Authorization Facility (SAF)

(ZOS) Update system login configurations to perform a System Authorization Facility identity user mapping

(ZOS) Writing a custom System Authorization Facility (SAF) mapping module with non-local operating system

(ZOS) Configure a custom System Authorization Facility (SAF) mapping module for federated repositories

Map a registry principal to a System Authorization Facility user ID using a JAASs login module