Configuring a JAAS custom login module for Liberty

You can configure a custom Java™ Authentication and Authorization Service (JAAS) login module before or after you configure the Liberty server login module.

Before you begin

Liberty supports the server.xml file, client.xml file, and the JAAS configuration file for JAAS configuration. However, it is suggested to configure the JAAS custom login module in the server.xml file or client.xml file. For more information, see Configuring an application JAAS custom login context entry and login module using a JAAS configuration file for Liberty.

Make sure you have a JAR file that contains the JAAS custom login module, which implements the javax.security.auth.spi.LoginModule interface as described in Developing JAAS custom login modules for a system login configuration. In that topic, JAAS custom login module uses hashtable, callbacks, or shared state variables that are provided by the Liberty server to pass authentication data to the system login module.

About this task

You can use a custom login module to either make additional authentication decisions or add information to the subject to make finer-grained authorization decisions inside your application. See JAAS configuration and JAAS login modules for a more detailed overview.

For Distributed operating systems You can also use the developer tools to configure a custom JAAS login module. See Configuring JAAS on Liberty by using developer tools. There are several security configuration examples on the Open Liberty website for reference when configuring security for your applications on Liberty.

To configure a JAAS custom login module, complete the following steps:

Procedure

Enable the Liberty Application Security feature, version 2.0 or later, in the server.xml file.
```
<featureManager>
    <feature>appSecurity-2.0</feature>
</featureManager>
```
Create a class com.sample.CustomLoginModule that implements the LoginModule interface and package it into the CustomLoginModule.jar file.
Create a <library> element that uses a <fileset> element that indicates where the CustomLoginModule.jar file is. In this example, the library id is customLoginLib.
```
<library id="customLoginLib">
    <fileset dir="${server.config.dir}" includes="CustomLoginModule.jar"/>
</library> 
```
Create a <jaasLoginModule> element. In this example, the id is myCustom.
1. Configure the custom login module to require a successful authentication by setting the controlFlag attribute to REQUIRED.
2. Set the libraryRef attribute to customLoginLib, the id of the <library> element configured in the previous step. This login module also has two options: UserRegistry is ldap and mapToUser is user1.
```
<jaasLoginModule id="myCustom" 
                 className="com.sample.CustomLoginModule" 
                 controlFlag="REQUIRED" libraryRef="customLoginLib">
    <options UserRegistry="ldap" mapToUser="user1"/>
</jaasLoginModule>
```
Note: The option name cannot start with a period (.), config., or service and must be unique. Also, the property name id or ID is not allowed.
Create a <jaasLogincontextEntry> element with an id and a unique name of the system-defined JAAS configuration: system.WEB_INBOUND. You can also set this JAAS configuration to system.DEFAULT, WSLogin, or your own JAAS configuration. On the loginModuleRef attribute, add myCustom, the id of the jaasLoginModule element created in the previous step. Putting this id first in the list means that it is the first JAAS login module to be called. You must also list the other default login modules: hashtable, userNameAndPassword, certificate, and token.
```
<jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" 
                 loginModuleRef="myCustom, hashtable, userNameAndPassword, certificate, token"  />
```
For more information about the <jaasLoginContextEntry>, <jaasLoginModule>, <options>, and <library> elements, see Application Security 2.0.