Configure programmatic logins for Java Authentication and Authorization Service

A new JAAS login configuration can be added and modified using the administrative console. The changes are saved in the cell-level security document and are available to all managed application servers.

JAAS is a feature in WebSphere Application Server. JAAS is a collection of WAS strategic authentication APIs and replaces the Common Object Request Broker Architecture (CORBA) programmatic login APIs.

WAS provides some extensions to JAAS:

• com.ibm.websphere.security.auth.WSSubject.

  The com.ibm.websphere.security.auth.WSSubject API extends the JAAS authorization model to Java EE resources.

  We can configure the JAAS login in the administrative console and store this login configuration in the Application Server configuration. However, WAS still supports the default JAAS login configuration format (plain text file) provided by the JAAS default implementation. If duplicate login configurations are defined in both the WAS configuration API and the plain text file format, the one in the WAS configuration API takes precedence. Advantages to defining the login configuration in the WebSphere configuration API include:

  • User interface support in defining JAAS login configuration
  • Central management of the JAAS login configuration
  • Distribution of the JAAS login configuration during installation

  Due to a design oversight in JAAS Version 1.0, the javax.security.auth.Subject.getSubject method does not return the subject associated with the running thread inside a java.security.AccessController.doPrivileged code block. This problem presents an inconsistent behavior that might cause unfavorable results. The com.ibm.websphere.security.auth.WSSubject API provides a workaround to associate the subject to a running thread.

• Proxy LoginModule

  The Proxy LoginModule loads the actual LoginModule module. The default JAAS implementation does not use the thread context class loader to load classes. The LoginModule module cannot load if the LoginModule class file is not in the application class loader or the Java extension class loader class path. Due to this class loader visibility problem, WAS provides a proxy LoginModule module to load the JAAS LoginModule using the thread context class loader. We do not need to place the LoginModule implementation on the application class loader or the class path for the Java extension class loader with this proxy LoginModule module. If we do not want to use the Proxy LoginModule module, we can place the LoginModule module in the app_server_root/lib/ext/ directory. However, this action is not recommended due to the security risks.

JAAS login configurations are defined in the WAS configuration API security document. Click Security > Global security. Under Java Authentication and Authorization Service, click Application logins. The following JAAS login configurations are available:

ClientContainer

Defines a login configuration and a LoginModule implementation that is similar to that of the WSLogin configuration, but enforces the requirements of the WAS client container. See Configuration entry settings for JAAS.

DefaultPrincipalMapping,

Defines a special LoginModule module that is typically used by Java EE connectors to map an authenticated WAS user identity to a set of user authentication data (user ID and password) for the specified back-end enterprise information system (EIS). For more information about Java EE Connector and the DefaultMappingModule module, refer to the Java EE security section.

WSLogin

Defines a login configuration and a LoginModule implementation that applications can use in general.

A new JAAS login configuration can be added and modified using the administrative console. The changes are saved in the cell-level security document and are available to all managed application servers. An application server restart is required for the changes to take effect at run time.

Do not remove or delete the predefined JAAS login configurations (such as, ClientContainer, WSLogin, and DefaultPrincipalMapping). Deleting or removing them can cause other enterprise applications to fail.

Tasks

1. Delete a JAAS login configuration.

   1. Click Security > Global security.

   2. Under Java Authentication and Authorization Service, click Application logins. The Application Login Configuration panel is displayed.

   3. Select the check box for the login configurations to delete and click Delete.

2. Create a new JAAS login configuration.

   1. Click Security > Global security.

   2. Under Java Authentication and Authorization Service, click Application logins.

   3. Click New. The Application Login Configuration panel is displayed.

   4. Specify the alias name of the new JAAS login configuration and click Apply. This value is the name of the login configuration that you pass in the javax.security.auth.login.LoginContext implementation for creating a new LoginContext context.

      Click Apply to save changes and to add the extra node name that precedes the original alias name. Clicking OK does not save the new changes in the security.xml file.

   5. Under Additional properties, click JAAS Login Modules.

   6. Click New.

   7. Specify the Module class name. Specify the WAS proxy LoginModule module because of the limitation of the class loader visibility.

   8. Specify the LoginModule implementation as the delegate property of the Proxy LoginModule module. The WAS proxy LoginModule class name is com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy.

   9. Select Authentication strategy from the list and click Apply.

   10. Under Additional properties, click Custom properties. The Custom properties panel is displayed for the selected LoginModule.

   11. Create a new property with the name delegate and the value of the real LoginModule implementation. We can specify other properties like debug with the true value. These properties are passed to the LoginModule class as options to the initialize method of the LoginModule instance.

   12. Click Save.

       For a WAS ND installation, make sure that a file synchronization operation is performed to propagate the changes to other nodes.

   Several locations are within the WAS directory structure where we can place a JAAS login module. The following list provides locations for the JAAS login module in order of recommendation:

   • Within an EAR file for a specific Java EE application.

     If we place the login module within the EAR file, the login module is accessible by the specific application only.

   • In the WAS-shared library.

     If we place the login module in the shared library, we must specify which applications can access the module. For more information on shared libraries, see the Managing shared libraries article.

   • In the Java extensions directory.

     If we place the JAAS login module in the Java extensions directory, the login module is available to all applications.

     (ZOS) This location is not recommended for WAS for z/OS or WebSphere Business Integration Server Foundation.

     (iSeries) Place the class file in the /QIBM/UserData/Java400/ext directory to add it to the class path for the Java extended directories. Also, grant *PUBLIC *RX authority to the file. However, when we add the file to the /QIBM/UserData/Java400/ext directory, we are adding the file to the default class path for the Java extended directories, which is accessible to the entire operating system

   Although the Java extensions directory provides the greatest availability for the login module, place the login module in an application EAR file. If other applications need to access the same login module, consider using shared libraries.

3. Change the plain text file.

   WAS supports the default JAAS login configuration format, which is a plain text file, provided by the JAAS default implementation. However, a tool is not provided that edits plain text files in this format. We can define the JAAS login configuration in the plain text file, which is located in the app_server_root/properties/wsjaas.conf file. Any syntax errors can cause the incorrect parsing of the plain JAAS login configuration text file. This problem can cause other applications to fail.

   (iSeries) WAS supports the default JAAS login configuration format, which is a plain text file, provided by the JAAS default implementation. However, a tool is not provided that edits plain text files in this format. We can define the JAAS login configuration in the profile_root/properties/wsjaas.conf file. Any syntax errors can cause the incorrect parsing of the plain JAAS login configuration text file. This problem can cause other applications to fail.

   Java client programs that use the JAAS for authentication must invoke with the JAAS configuration file specified. This configuration file is set in the app_server_root/bin/launchClient.bat file as:

   set JAAS_LOGIN_CONFIG=-Djava.security.auth.login.config=%install_root%\properties\wsjaas_client.conf
   

   If the launchClient.bat file is not used to invoke the Java client program, verify that the appropriate JAAS configuration file is passed to the Java virtual machine with the -Djava.security.auth.login.config flag.

   (iSeries) Java client programs that use JAAS for authentication must invoke with the JAAS configuration file specified. This configuration file is set in the launchClient QShell script. If we do not use the launchClient script to invoke the Java client program, verify that the appropriate JAAS configuration file is passed to the Java virtual machine using the -Djava.security.auth.login.config flag.

A new JAAS login configuration is created or an old JAAS login configuration is removed. An enterprise application can use a newly created JAAS login configuration without restarting the application server process.

However, new JAAS login configurations defined in the app_server_root/properties/wsjaas.conf file, do not refresh automatically. Restart the application servers to validate changes. These JAAS login configurations are specific to a particular node and are not available for other application servers running on other nodes.

(iSeries) However, new JAAS login configurations defined in the profile_root/properties/wsjaas.conf file, do not refresh automatically. Restart the application servers to validate changes. These JAAS login configurations are specific to a particular node and are not available for other application servers running on other nodes.

What to do next

Create new JAAS login configurations used by enterprise applications to perform custom authentication. Use these newly defined JAAS login configurations to perform programmatic login.

Subtopics

• Login configuration for JAAS
  JAAS is a new feature in WAS. JAAS is WAS strategic API for authentication that replaces the Common Object Request Broker Architecture (CORBA) programmatic login API.
• Configuration entry settings for JAAS
  Specify a list of JAAS login configurations for the application code to use, including Java EE components such as enterprise beans, JSP files, servlets, resource adapters, and message-driven beans (MDBs).
• System login configuration entry settings for JAAS
  Specify a list of JAAS system login configurations.
• Login module settings for JAAS
  Use this page to define the login module for a JAAS login configuration.
• Login module order settings for JAAS
  Specify the order in which the application server processes the login configuration modules.
• Login configuration settings for JAAS
  Configure application login configurations.
• Manage Java 2 Connector Architecture authentication data entries for JAAS
  This task creates and deletes Java 2 Connector (J2C) authentication data entries.

Related:

Java EE connector security

Programmatic login for JAAS

Customize application login with JAAS

Developing programmatic logins with the JAAS

Manage shared libraries