Authenticating users to run CICS Liberty web applications

Basic authentication

Basic authentication is a simple authentication scheme that is built into the HTTP protocol. It requires the client to provide a user ID and password when a request is made. The user ID and password are encoded in base64 and sent in the HTTP Authorization header of the request. The Liberty JVM server validates the user ID and password against a configured user registry. The user ID is set as the authenticated user.

The following types of user ID and password are supported for basic authentication with CICS Liberty:

• A user ID and password that is defined in a basic registry.
• An LDAP distinguished name and password, which is defined in an LDAP registry.
• A SAF user ID and password (or passphrase) defined in the SAF registry on the same LPAR as the Liberty server.

Basic authentication encodes but does not encrypt the credentials. You must use HTTPS (TLS) to ensure confidentiality.

<login-config>
  <auth-method>BASIC</auth-method>
</login-config>

For more information about configuring basic authentication, see Configuring basic authentication for Liberty web applications.

Form-based authentication

Use form-based authentication when you need to create a customized login form for users to access your application from a browser. You must specify a login page that contains the form to obtain the credentials as well as an error page that displays when login authentication fails.

<login-config>
  <auth-method>FORM</auth-method>
</login-config>

Client-certificate authentication

Certificate-based client authentication maps information that is provided in the client’s TLS certificate to an associated user ID. It also provides all the normal benefits that are associated with a secure TLS connection.

When client-certificate authentication is configured, for each HTTPS connection, the Liberty JVM server asks the client to provide its certificate. The server validates the chain of trust by checking that the client certificate issuer is in the truststore. This process is standard TLS behavior and if the client certificate is successfully validated, the connection can be established to the Liberty JVM server.

If the client certificate is successfully validated, it is then mapped to a user identity in the user registry.

<login-config>
  <auth-method>CLIENT-CERT</auth-method>
</login-config>

For more information about configuring client-certificate authentication with RACF, see Configuring TLS for a Liberty JVM server by using RACF.

Third-party authentication

JWT

Third-party authentication can be implemented with CICS Liberty by using a range of different authentication tokens. The most widely used third-party authentication token is the JSON Web Token (JWT).

Single Sign-On

Single Sign-On (SSO) enables users to log in to one server and access applications on other servers without getting prompted to log in again. When a user authenticates on one Liberty server, authentication information that is generated by the server is transported to the web browser in a cookie. The cookie is used to propagate the authentication information to other Liberty servers.

The most commonly used SSO token is the How it works: LTPA (Lightweight Third Party Authentication) token although it is also possible to use a How it works: JSON Web Token (JWT) as an SSO token.

If you use the cicts:security-1.0 feature or the appSecurity-2.0 feature (or a more recent version of this feature) in your Liberty JVM server, Liberty uses LTPA tokens by default in its web authentication processing.

For instructions on how to change the default behavior, see Configuring LTPA in Liberty.

Custom authentication options

JWT feature

The Liberty jwt-1.0 feature provides a set of APIs that you can use to work with JWTs. You can use the feature to build or consume a JWT.

For more information about the JWT feature, see Building and consuming JSON Web Token (JWT) tokens in Liberty.

For an example on using the JWT feature with CICS Liberty, see JWT feature sample with CICS Liberty on GitHub.

Enterprise Java™ Security API

The JSR 375 specification for Java EE 8 introduced the Java EE Security API 1.0. Jakarta EE 8 offers an identical implementation for Jakarta EE Security API 1.0. Jakarta Security 2.0 in Jakarta EE 9.0 supersedes version 1.0 of the specification for both Enterprise variants. Collectively this function is referred to as the Enterprise Java EE Security API. This API provides portable, plug-in interfaces to enable HTTP authentication in web applications and a standardized API for programmatic security.

In Liberty, appSecurity-3.0 feature enables Enterprise Java Security API 1.0 and appSecurity-4.0 feature enables Jakarta Security API 2.0.

You can use the built-in implementations of the plug-in interfaces, or write your own custom implementations.

Using the Enterprise Java EE Security API, you can define all of the security information directly within the application. Declarative security expressed by web.xml constraints or annotations, such as @RolesAllowed, continue to work as normal.

The three principles of the Enterprise Java EE Security API are as follows:

1. The HttpAuthenticationMechanism interface provides an authentication mechanism for the servlet container and offers an alternative to the Java EE function offered by the <login-config> element in the web application’s deployment descriptor.
   There are 3 options that can be used with the HttpAuthenticationMechanism interface.

   1. HTTP basic authentication, this is implemented using the @BasicAuthenticationMechanismDefinition annotation.
   2. Form-based authentication, this is implemented using the @FormAuthenticationMechanismDefinition annotation.
   3. A custom authentication mechanism using a class that implements the HttpAuthenticationMechanism interface.
2. An identity store holds usernames, passwords, role membership and other meta-data to allow it to authenticate a caller’s credentials. Three identity store types are introduced by the Enterprise Java EE Security API:
   1. A database identity store, this is implemented using the @DatabaseIdentityStoreDefinition annotation. For more information, see Configuring security by using a database identity store.
   2. An LDAP identity store, this is implemented using the @LdapIdentityStoreDefinition annotation. For further details see Java EE Security API.
   3. A custom identity store using a class that implements the IdentityStore interface. For more information, see Configuring security by using a custom identity store .

   Liberty also provides the ability to map authenticated identities from an identity store to a SAF user ID using distributed identity mapping. This is configured via the <safCredentials mapDistributedIdentities="true" suppressAuthFailureMessages="false"> configuration element. If the cicsts:security-1.0 feature is also installed in a Liberty JVM server then CICS will set the CICS task user ID based on the mapped SAF user ID.

3. The SecurityContext class can be used to perform programmatic security checks such as checking access to web resources or checking if the authenticated caller is in a specified role. In this example, the user is forwarded to another page only if they have access to it:

   @WebServlet("/home")
   public class HomeServlet extends HttpServlet 
   {
       @Inject
       private SecurityContext securityContext;
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp)
           throws ServletException, IOException 
       {
           if (securityContext.hasAccessToWebResource("/anotherServlet", "GET")) 
           {
               req.getRequestDispatcher("/anotherServlet").forward(req, resp);
           } 
           else 
           {
               req.getRequestDispatcher("/logout").forward(req, resp);
           }
       }
   }
   

For more information about Liberty support for the Enterprise Java security API, see Java EE Security API.

Trust Association Interceptor (TAI)

A TAI can be used to configure a Liberty JVM server to integrate with a third-party security service. The TAI can inspect the HTTP request to see whether it contains a specific security token, for example, a custom token or a standard token such as a JWT.

For an example on using a TAI with CICS Liberty to validate a JWT, see Sample Trust Association Interceptor (TAI) to validate a JWT with CICS Liberty on GitHub.

For more information, see Configuring TAI for Liberty.

Java Authentication Service Provider Interface for Containers (JASPIC)

JASPIC is an Enterprise Java standard service provider API that enables the implementation of authentication mechanisms into Enterprise Java web applications.

For an example on using a JASPIC implementation with CICS Liberty, see Sample implementation of JASPIC with CICS Liberty on GitHub.

For more information, see Configuring a Java Authentication SPI for Containers (JASPIC) User Feature.

Authentication cache

Because the creation of a Java security subject can affect performance, Liberty provides an authentication cache to store the subject. However, unlike CICS, Liberty 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. For more information, see Configuring the authentication cache in Liberty.