Configure JAAS login

 

JAAS is a collection of WAS authentication APIs, mandated by the J2EE V 1.3 specification, that replaces the CORBA APIs.

JAAS logins can be configured by going to...

Security | JAAS Configuration | Application Login

The following JAAS login configurations are available:

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

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.

DefaultPrincipalMapping, Most common enterprise configuration. Defines a special LoginModule module that is typically used by Java 2 Connector to map an authenticated WebSphere user identity to a set of user authentication data (user ID and password) for the specified back-end enterprise information system.

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

To configure a new JAAS login configuration

  1. Go to...

    Security | JAAS Configuration | Application Logins | New

    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 for creating a new LoginContext.

  2. Click...

    JAAS Login Modules | New

  3. Specify the Module Classname. Specify WebSphere Proxy LoginModule because of the limitation of the class loader visibility problem.

  4. Specify the LoginModule implementation as the delegate property of the Proxy LoginModule. The WebSphere Proxy LoginModule class name is...

    com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy

  5. Select Authentication Strategy from the list and click Apply.

  6. Click Custom Properties. The Custom Properties panel is displayed for the selected LoginModule.

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

  8. Click Save. For a Network Deployment installation, make sure that a file synchronization operation is performed to propagate the changes to other nodes.

  9. An appserver restart is required for the changes to take effect at run time.

 

Change the plain text file

WAS supports the default JAAS login configuration format (plain text file) provided by the JAAS default implementation:

$WAS_HOME/properties/wsjaas.conf

Java client programs that use the JAAS for authentication must invoke with the JAAS configuration file specified. This configuration file is set in

$WAS_HOME/bin/launchClient.sh

...as...

JAAS_LOGIN_CONFIG=-Djava.security.auth.login.config=$WAS_HOME/properties/wsjaas_client.conf

If the launchClient.sh file is not used to invoke the Java client program, verify that the appropriate JAAS configuration file is passed to the JVM with the flag...

-Djava.security.auth.login.config

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 cycling the appserver process.

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

 

JAAS login module settings

To define the login module for a JAAS login configuration...

Security | JAAS Configuration | Application Logins | alias_name | JAAS Login Modules.

 

Configuration tab

Module Class Name Specifies the class name of the given login module.

The default login modules defined by the WebSphere product use a proxy LoginModule class...

com.ibm.ws.security.common.auth.module.WSLoginModuleProxy

This proxy class loads the WebSphere login module with the thread context class loader and delegates all the operations to the real login module implementation. The real login module implementation is specified as the delegate option in the option configuration. The proxy class is needed because the Developer Kit application class loaders do not have visibility of the WebSphere product class loaders.

Data type... String

Authentication Strategy Specifies the authentication behavior as authentication proceeds down the list of login modules.

A JAAS authentication provider supplies the authentication strategy. In JAAS, an authentication strategy is implemented through the LoginModule interface.

Data type... String
Default... Required
Range... Required, Requisite, Sufficient and Optional

Specify additional options in Options Additional Properties. These name and value pairs are passed to the login modules during initialization. This process is one of the mechanisms used to passed information to login modules.

 

JAAS login configuration

JAAS is a new feature in WAS. It is mandated by J2EE 1.3 Specification. JAAS is WebSphere strategic APIs for authentication and it will replace of the CORBA programmatic login APIs. WAS provides some extensions to JAAS...

  • com.ibm.websphere.security.auth.WSSubject: Due to a design oversight in the JAAS 1.0, javax.security.auth.Subject.getSubject() does not return the Subject associated with the thread of execution inside a java.security.AccessController.doPrivileged() code block. This can present a inconsistent behavior that is problematic and causes undesirable effort. com.ibm.websphere.security.auth.WSSubject provides a work around to associate Subject to thread of execution. com.ibm.websphere.security.auth.WSSubject extends the JAAS authorization model to J2EE resources.

    You can retrieve the subjects in a Subject.doAs() block with the Subject.getSubject() call. However, this procedure does not work if there is an AccessController.doPrivileged() call within the Subject.doAs() block. In the following example, s1 is equal to s, but s2 is null: 

    * AccessController.doPrivileged() not only truncates the Subject propagation, 
* but also reduces the permissions. It does not include the JAAS security 
* policy defined for the principals in the Subject.
Subject.doAs(s, new PrivilegedAction() {
  public Object run() {
    System.out.println("Within Subject.doAsPrivileged()");
    Subject s1 = Subject.getSubject(AccessController.getContext());
    AccessController.doPrivileged(new PrivilegedAction() {
      public Object run() {
      Subject s2 = Subject.getSubject(AccessController.getContext());
      return null;
    }
  });
  return null;
}
});

  • JAAS Login Configuration can be configured in Admin Console and stored in WCCM (WebSphere Common Configuration Model): Application can define new JAAS login configuration in the Admin Console and the the data is persisted in the configuration respository (stored in the WCCM). However, WebSphere still support the default JAAS login configuration format (plan text file) provided by the JAAS default implementation. But if there are duplication login configurations defined in both the WCCM and the plan text file format, the one in the WCCM takes precedence. There are advantages to define the login configuration in the WCCM...

    • UI support in defining JAAS login configuration.

    • The JAAS configuration login configuration can be managed centrally.

    • The JAAS configuration login configuration is distributed in a Network Deployment installation.

  • Proxy LoginModule: The default JAAS implementation does not use the thread context class loader to load classes, the LoginModule could not be loaded if the LoginModule class file is not in the application class loader or the Java extension class loader classpath. Due to this class loader visibility problem, WebSphere provides a proxy LoginModule to load JAAS LoginModule using the thread context class loader. The LoginModule implementation does not have to be placed on the application class loader or the Java extension class loader classpath with this proxy LoginModule.

Note that Do not remove or delete the pre-defined JAAS Login Configurations (ClientContainer, WSLogin and DefaultPrincipalMapping). Deleting or removing them could cause other enterprise applications to fail. A system administrator determines the authentication technologies, or LoginModules, to be used for each application and configures them in a login configuration. The source of the configuration information (for example, a file or a database) is up to the current javax.security.auth.login.Configuration implementation. The WAS implementation permits the login configuration to be defined in both the WebSphere Common Configuration Model (WCCM) security document and in a JAAS configuration file where the former takes precedence.

Two JAAS login configurations are defined in the WCCM security document for applications to use. They may be found in the left navigation pane at Security > JAAS Configuration > Application Login Config: WSLogin and ClientContainer. The WSLogin defines a login configuration and LoginModule implementation that may be used by applications in general. The ClientContainer defines a login configuration and LoginModule implementation that is similar to that of WSLogin but enforces the requirements of the WAS Client Container. The third entry, DefaultPrincipalMapping, defines a special LoginModule that is typically used by Java 2 Connector to map an authenticated WebSphere 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 2 Connector and the DefaultMappingModule please refer to the Java 2 Security section.

New JAAS login configuration may be added and modified using Security Center. The changes are saved in the cell level security document and are available to all managed appservers. An appserver restart is required for the changes to take effect at run time.

WebSphere Application Server also reads JAAS Configuration information from the wsjaas.conf file under the properties sub directory of the root directory under which WAS is installed. Changes made to the wsjaas.conf file is used only by the local appserver and will take effect after cycling the appserver. Note that JAAS configuration in the WCCM security document takes precedence over that defined in the wsjaas.conf file. In other words, a configuration entry in wsjaas.conf will be overridden by an entry of the same alias name in the WCCM security document.

Note that The JAAS login configuration entries in the Security Center are propagated to the server run time when they are created, not when the configuration is saved. However, the deleted JAAS login configuration entries are not removed from the server run time. To remove the entries, save the new configuration, then stop and restart the server.

 

WAS Extensions to JAAS

WAS provides some extensions to JAAS...

  • Due to a design oversight, the method...

    javax.security.auth.Subject.getSubject()

    ...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 is problematic and causes undesirable effort.

    The com.ibm.websphere.security.auth.WSSubject API provides a workaround to associate the subject to a running thread, extending the JAAS authorization model to J2EE resources.

  • You can configure JAAS login in the administrative console and store this configuration using WebSphere Common Configuration Model (WCCM) or in a plain text file. If duplicate login configurations are defined in both the WCCM and the plain text file format, the one in the WCCM takes precedence. WCCM advantages include...

    • User interface support in defining the configuration
    • Central management of the configuration
    • Federation of the configuration in a Network Deployment instance

  • The default JAAS LoginModule interface cannot load if the LoginModule class file is not in the application or the Java extension class loader class path. WAS provides a proxy LoginModule interface to load the JAAS LoginModule using the thread context class loader. You do not need to place the LoginModule implementation on the application class loader or the Java extension class loader class path with this proxy LoginModule module.

 

See Also

Java 2 Connector security
Programmatic login
Developing with the JAAS to log in programmatically
JAAS login configuration
Warning: no string named [usecjaas] found.
JAAS module settings
Application login configuration settings