Configuring security for a Liberty JVM server

You can use the CICS® Liberty security feature to authenticate users and authorize access to web applications through Java™ Platform, Enterprise Edition roles (Java EE roles), providing integration with CICS transaction and resource security. You can also use CICS resource security to authorize the appropriate users to manage the lifecycle of both the JVMSERVER resource and Java web applications that are deployed in a CICS BUNDLE resource. In this topic, authentication verifies the identity of a given user, typically by requiring the user to enter a username and password. Authorization grants access control permissions based on the identity of the authenticated user.

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. The default behavior of the CICS TS security feature, cicsts:security-1.0, is to use the SAF registry. If you use an LDAP registry, a SAF registry is not created. For more information, see Configuring security for a Liberty JVM server by using distributed identity mapping. The basic user registry (which is also used by quickStartSecurity) is only suitable for simple security testing. Be aware that if you configure and run with basic user registry and you need to switch to cicsts:security-1.0, you need to delete the session tokens.

About this task

This task explains how to configure security for a Liberty JVM server and integrate Liberty security with CICS security. For information about how to configure security for Link to Liberty, see Linking to a Java EE application from a CICS program.

The default transaction ID for running web requests is CJSA. However, you can configure CICS to run web requests under a different transaction ID by using a URIMAP of type JVMSERVER. Typically, you might 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 might choose to run each individual servlet under a different transaction with a more precise URI.

The default user ID for running web requests is the CICS default user ID. If a URIMAP is available and contains a static user ID, it is used in preference to the default user ID. If the web request contains a user ID in its security header, it takes precedence over all other mechanisms.

Tasks that emanate from Liberty that are not classified as web requests run under the CJSU transaction by default. Although there is no URIMAP style mechanism for these types of tasks, you can override the default transaction ID by using the JVM profile property of com.ibm.cics.jvmserver.unclassified.tranid and the default user ID by using the JVM profile property com.ibm.cics.jvmserver.unclassified.userid.

Note: The user ID requires permission to attach the specified transaction. For more information, see Transaction security.

Procedure

Configure the Liberty angel process to provide authentication and authorization services to the Liberty JVM server, see The Liberty server angel process.
Tip: If you have a named angel process, you need to configure your Liberty JVM server to connect to it by adding the following line to your JVM profile.
```
-Dcom.ibm.ws.zos.core.angelName=<named_angel>
```
Optional: Enforce the requirement to connect to the Liberty angel process when the Liberty JVM server is being enabled by adding the following line to your JVM profile:
```
-Dcom.ibm.ws.zos.core.angelRequired=true
```
This option prevents the Liberty JVM server from starting if the angel process is unavailable.
It instructs CICS to call the Liberty angel check API to verify whether an angel process is available for Liberty JVM server startup.
If the angel process is unavailable, CICS reacts as follows:
- If the Liberty JVM server is being enabled through the CEMT transaction, a message is issued, and the Liberty JVM server is disabled.
- If the Liberty JVM server is being enabled by the SET JVMSERVER SPI command or by using the CMCI through the CICS Explorer, a message is issued, and the Liberty JVM server is disabled.
- If the Liberty JVM server is being enabled by the CICS CREATE SPI, by BAS, or from GRPLIST, a message is issued, and CICS will wait 30 seconds before retrying the Liberty angel check API call. If the angel process is unavailable on the fifth attempt, a WTOR message is issued, giving the operator the option to continue waiting or to disable the JVMSERVER resource.

Add the cicsts:security-1.0 feature to the featuremanager list in the server.xml,

<featureManager>
   ...
   <feature>cicsts:security-1.0</feature>
</featureManager>
...

Add the System Authorization Facility (SAF) registry to server.xml by using the following example:
```
<safRegistry id="saf" enableFailover="false"/>
```
Save the changes to server.xml.
Optional: Alternatively, if you are autoconfiguring the Liberty JVM server and the SEC system initialization parameter is set to YES in the CICS region, the Liberty JVM server is dynamically configured to support Liberty JVM security when the JVM server is restarted. For more information, see Configuring a Liberty JVM server.
If the SEC system initialization parameter is set to NO, you can still use Liberty security for authentication or SSL support. If CICS security is turned off, and you want to use a Liberty security, you must configure the server.xml file manually:
1. Add the appSecurity-2.0 feature to the featuremanager list.
2. Add a user registry to authenticate users. Liberty security supports SAF, LDAP, and basic user registries. For more information, see Configuring a user registry in Liberty.
3. Add security-role definitions to authorize access to application resources, see Authorizing users to run applications in a Liberty JVM server.

Results

The web container is automatically configured to use the z/OS Security feature of Liberty. A SAF registry is used for authentication, and Java EE roles are respected for authorization. Authorization constraints and security roles govern who can access the application. These are usually defined in the deployment descriptor (web.xml) of the application, but might also be defined as security annotations in the source-code. Typically, users and groups are mapped to roles by the applications <application-bnd> element in server.xml. Alternatively, if the<safAuthorization> element is configured in server.xml, the mappings are held in SAF (as EJBROLES in RACF).

What to do next

Note: You can also delegate authentication to another identity by configuring the RunAs specification for Liberty, see Configuring RunAs authentication in Liberty.

Configure Liberty application security authentication rules; see Authenticating users in a Liberty JVM server.
Define authorization rules for web applications; see Authorizing users to run applications in a Liberty JVM server and Authorization using SAF role mapping.
Modify the Liberty authentication cache.

For more information about using Secure Sockets Layer (SSL), see Configuring SSL (TLS) for a Liberty JVM server using a Java keystore.