Configuring security for a Liberty JVM server by using an LDAP registry

Liberty uses a user registry to authenticate a user and retrieve information about users and groups to perform security-related operations, including authentication and authorization. Default CICS® Liberty security uses the SAF registry. However, many transactions that run on CICS are initiated by users who authenticate their identities on distributed application servers, so CICS also supports the use of a Lightweight Directory Access Protocol (LDAP) registry in Liberty. To use LDAP, it is necessary to manually configure the server.xml.

Before you begin

Ensure that the CICS region is configured to use SAF security and is defined with SEC=YES as a system initialization parameter.
Authorize application developers and system administrators to create, view, update, and remove JVMSERVER and BUNDLE resources to deploy web applications into a Liberty JVM server. The JVMSERVER resource controls the availability of the JVM server, and the BUNDLE resource is a unit of deployment for the Java™ applications and controls the availability of the applications.

About this task

This task explains how to configure LDAP security for a Liberty JVM server, and integrate Liberty security with CICS security. Distributed identity mapping can be used to associate a SAF user ID with a distributed identity. You can use the CICS distributed identity mapping feature to set up distributed identity mapping. A user can then log on to a CICS web application with their distributed identity, as authenticated by an LDAP server. Filters that are defined in the z/OS® security product (RACMAP) determine the mapping of this identity to a SAF user ID. This SAF user ID can then be used to authorize access to web applications through JEE application role security, providing integration with CICS transaction and resource security. You can map a SAF user ID to one or more distributed identities.

The default transaction ID for running any web request is CJSA. You can configure CICS to run web requests under a different transaction ID by using a URIMAP of type JVMSERVER. You can specify a URIMAP to match the generic context root (URI) of a web application to scope the transaction ID to the set of servlets that make up the application. Or you can choose to run each individual servlet under a different transaction with a more precise URI.

There are three scenarios for this task:

Scenario 1 – Distributed identity mapping with SAF authorization
Scenario 2 – Distributed identity mapping without SAF authorization
Scenario 3 – LDAP for authentication and authorization

Procedure

Distributed identity mapping with SAF authorization
You can use the CICS distributed identity mapping feature, cicsts:distributedIdentity-1.0 to enable LDAP distributed identities to be mapped to SAF user IDs. When used with the CICS security feature cicsts:security-1.0, Liberty LDAP security is used for authentication and JEE application role security from EJB role mappings are respected for authorization. CICS transactions run under the mapped SAF user ID providing integration with CICS transaction and resource security.
1. Configure the WebSphere® Liberty angel process to provide authentication and authorization services to the Liberty JVM server, for more information see The Liberty server angel process.
2. Add the cicsts:security-1.0 and the cicsts:distributedIdentity-1.0 feature to the featureManager list in the server.xml.
```
<featureManager>
   ...
   <feature>cicsts:security-1.0</feature>
   <feature>cicsts:distributedIdentity-1.0</feature>
</featureManager>
...
```
3. Configure Liberty to use LDAP authentication by defining the LDAP server in the server.xml, for example:
```
  <ldapRegistry id="ldap"
                 host="host.domain.com" port="389"
                 ldapType="IBM Tivoli Directory Server"
                 baseDN="ou=users,dc=domain,dc=com"
                 ignoreCase="true">
  </ldapRegistry>
```
  Full details on configuring LDAP user registries with Liberty are available in Configuring LDAP user registries in Liberty.
4. Remove the safRegistry element, if present. Save the changes to the server.xml.
5. Make the necessary RACF® definitions, including setting up the RACMAPs to map distributed identities to SAF user IDs as which are described in Configuring LDAP user registries in Liberty and providing access for these user IDs to the appropriate EJBROLES as described in Authorization using SAF role mapping. CICS configures SAF authorization and the mapDistributedIdentities attributes in the safCredentials configuration element for you.
When the cicsts:distributedIdentity-1.0 feature is used with the cicsts:security-1.0 feature, Liberty LDAP security is used for authentication, and JEE application role security from EJB role mappings are respected for authorization. CICS transactions run under the RACMAP mapped user ID providing integration with CICS transaction and resource security.
What to do next
Back to top
Distributed identity mapping without SAF authorization
It is possible to allow CICS transactions to run under a RACMAP mapped user ID while respecting the roles configured in the application’s <application-bnd> element. This might be useful when migrating work from distributed Liberty to CICS Liberty. Be aware that CICS bundles cannot be used to install applications as SAF authorization is not being used. See Authorization using SAF role mapping for more details.
1. Configure the WebSphere Liberty angel process to provide authentication and authorization services to the Liberty JVM server, for more information, see The Liberty server angel process.
2. Add the cicsts:security-1.0 and the ldapRegistry-3.0 feature to the featureManager list in the server.xml.
```
<featureManager>
   ...
   <feature>cicsts:security-1.0</feature>
   <feature>ldapRegistry-3.0</feature>
</featureManager>
...
```
3. Configure Liberty to use LDAP authentication by defining the LDAP server in the server.xml, for example:
```
  <ldapRegistry id="ldap"
                 host="host.domain.com" port="389"
                 ldapType="IBM Tivoli Directory Server"
                 baseDN="ou=users,dc=domain,dc=com"
                 ignoreCase="true">
  </ldapRegistry>
```
  Full details on configuring LDAP user registries with the Liberty are available in Configuring LDAP user registries in Liberty.
4. Configure Liberty to use distributed identity filters to map the distributed identities to SAF user IDs by setting the mapDistributedIdentities attribute in the safCredentials configuration element to true in the server.xml.
5. Remove the safRegistry element, if present. Save the changes to the server.xml.
6. Make the necessary RACF definitions, including setting up the RACMAPs to map distributed identities to SAF user IDs as which are described in Configuring LDAP user registries in Liberty.
7. If JEE application role security is required for authorization then refer to the topic Authorization using SAF role mapping. Be aware that CICS bundles cannot be used to install applications when SAF is not used for JEE role authorization.
Applications use Liberty LDAP security for authentication, and JEE application role security in an <application-bnd> element are respected for authorization of the distributed identity. In CICS, transactions run under the RACMAP mapped user ID, providing integration with CICS transaction and resource security.
What to do next
Back to top
LDAP for authentication and authorization
LDAP security can be used in a CICS Liberty JVM server for both authentication and authorization using JEE application role security. URIMAP definitions can then be used to set the user ID under which transaction run. This scenario might be useful if migrating a distributed application into a CICS Liberty JVM server, without requiring any significant security resource changes.
1. Add the cicsts:security-1.0 and the ldapRegistry-3.0 feature to the featureManager list in the server.xml.
```
<featureManager>
   ...
   <feature>cicsts:security-1.0</feature>
   <feature>ldapRegistry-3.0</feature>
</featureManager>
...
```
2. Configure Liberty to use LDAP authentication by defining the LDAP server in the server.xml, for example:
```
  <ldapRegistry id="ldap"
                 host="host.domain.com" port="389"
                 ldapType="IBM Tivoli Directory Server"
                 baseDN="ou=users,dc=domain,dc=com"
                 ignoreCase="true">
  </ldapRegistry>
```
  Full details on configuring LDAP user registries with Liberty are available in Configuring LDAP user registries in Liberty.
3. Remove the safRegistry element, if present. Save the changes to the server.xml.
4. To configure JEE application role security for authorization refer to the topic Authorization using SAF role mapping. Be aware that CICS bundles cannot be used to install applications when SAF is not used for JEE role authorization.
Applications use Liberty LDAP security for authentication, and JEE application role security in an <application-bnd>element are respected for authorization. In CICS transactions run under the URIMAP or CICS DFLTUSER user ID as appropriate.
What to do next
Back to top

What to do next

This applies to all three scenarios:

Modify the Liberty authentication cache.
Set up URIMAP definitions to map web application URIs to transaction IDs.

This applies to scenarios 1 and 2:

Set up CICS transaction security definitions to authorize access to URIs based on the mapped user ID.