Authenticating users in a Liberty JVM server

Although you can configure CICS® security for all web applications that run in a Liberty JVM server, the web application will only authenticate users if it includes a security constraint. The security constraint is defined by an application developer in the deployment descriptor (web.xml) of the Dynamic Web Project or OSGi Application Project. The security constraint defines what is to be protected (URL) and by which roles.

A <login-config> element defines the way a user gains access to web container and the method used for authentication. The supported methods are either HTTP basic authentication, form based authentication or SSL client authentication. For further details on how to define application security for CICS see SSL security for Explorer connections in the CICS Explorer product documentation. Here is an example of those elements in web.xml:

<!-- Secure the application -->
<security-constraint>
	<display-name>com.ibm.cics.server.examples.wlp.tsq.web_SecurityConstraint</display-name>
		<web-resource-name>com.ibm.cics.server.examples.wlp.tsq.web</web-resource-name>
		<description>Protection area for com.ibm.cics.server.examples.wlp.tsq.web</description>
		<url-pattern>/*</url-pattern>
	</web-resource-collection>
	<auth-constraint>
		<description>Only SuperUser can access this application</description>
		<role-name>SuperUser</role-name>
	</auth-constraint>
	<user-data-constraint>
		<!-- Force the use of SSL -->
		<transport-guarantee>CONFIDENTIAL</transport-guarantee>
	</user-data-constraint>
</security-constraint>

<!-- Declare the roles referenced in this deployment descriptor -->
<security-role>
	<description>The SuperUser role</description>
	<role-name>SuperUser</role-name>
</security-role>

<!--Determine the authentication method -->
<login-config>
		<auth-method>BASIC</auth-method>	
</login-config>

Note: If you use RequestDispatcher.forward() methods to forward requests from one servlet to another, the security check occurs only on the first servlet that is requested from the client.

Tasks that are authenticated in CICS using Liberty security can use the user ID derived from any of the Liberty application security mechanisms to authorize transaction and resource security checks in CICS. The CICS user ID is determined according to the following criteria:

Liberty application security authentication.
Integration with the SAF user registry is part of the CICS Liberty security feature, unless distributed identity mapping is used. Any of the application security mechanisms supported by Liberty are supported in CICS, this includes HTTP basic authentication, form login, SSL client certificate authentication, identity assertion using a custom login module, JACC, JASPIC, or a Trust Association Interceptor (TAI). All SAF user IDs authenticated by Liberty must be granted read access to the Liberty JVM server APPL class profile. The name of this is determined by the profilePrefix setting in the safCredentials element in the Liberty server configuration file server.xml.
```
<safCredentials profilePrefix="BBGZDFLT"/>
```
The APPL class is also used by CICS terminal users to control access to specific CICS regions and your Liberty JVM server can use the same profile as the CICS APPLID depending upon your security requirements. If you do not specify this element, then the default profilePrefix of BBGZDFLT is used.
You must define the APPLID and users must have access to the it. To configure and activate the BBGZDFLT profile in the APPL class:
```
RDEFINE APPL BBGZDFLT UACC(NONE)
SETROPTS CLASSACT(APPL)
```
The users must be given read access to the BBGZDFLT profile in the APPL class in order to authenticate. To allow user AUSER to authenticate against the BBGZDFLT APPL class profile:
```
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(AUSER)
```
The Liberty SAF unauthenticated user id must be given read access to the APPL class profile. The SAF unauthenticated user id can be specified in the safCredentials element in the Liberty server configuration file server.xml.
```
<safCredentials unauthenticatedUser="WSGUEST"/>
```
If you do not specify the element, then the default unauthenticatedUser is WSGUEST. To allow the SAF unauthenticated user id WSGUEST read access to the BBGZDFLT profile in the APPL class:
```
PERMIT BBGZDFLT CLASS(APPL) ACCESS(READ) ID(WSGUEST)
```
If you use WSGUEST, then you should follow the steps to configure the SAF user registry as described in Setting up the System Authorization Facility (SAF) unauthenticated user.
The WLP z/OS® System Security Access Domain (WZSSAD) refers to the permissions granted to the Liberty server. These permissions control which System Authorization Facility (SAF) application domains and resource profiles the server is permitted to query when authenticating and authorizing users. The CICS region user ID must be granted permission within the WZSSAD domain to make authentication calls. To grant permission to authenticate, the CICS region ID must be granted READ access to the BBG.SECPFX.<APPL> profile in the SERVER class:
```
RDEFINE SERVER BBG.SECPFX.BBGZDFLT UACC(NONE)
PERMIT BBG.SECPFX.BBGZDFLT CLASS(SERVER) ACCESS(READ) ID(cics_region_user)
```
For more details refer to Liberty: Accessing z/OS security resources using WZSSAD.
If an unauthenticated subject is supplied from Liberty, then the USERID defined in the URIMAP will be used.
If no USERID is defined in the URIMAP the request will run under the CICS default user ID.

Note:

Due to the way that security processing for Liberty transactions is deferred during CICS transaction attach processing, the user ID used in the CICS Monitoring Facility (CMF) records, the z/OS Workload Manager (WLM) classification, and the task association data and the UEPUSID global user exits field for the XAPADMGR exit, will be determined as follows; the user ID in the HTTP security header, or if there isn't one, the user ID taken from matching URIMAP. If neither exist, the CICS default user ID will be used.

Be aware that Liberty caches authenticated user IDs and, unlike CICS, does not check for an expired user ID within the cache period. You can configure the cache timeout by using the standard Liberty configuration process. Please see Configuring the authentication cache in Liberty.