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.
Before you begin
Java™
Authentication and Authorization Service (JAAS) is a feature in WebSphere® Application Server. JAAS is a collection of WebSphere Application Server strategic authentication APIs and replaces the
Common Object Request Broker Architecture (CORBA) programmatic login APIs.
WebSphere Application Server 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 Platform, Enterprise Edition (Java EE) resources.
- You can configure the JAAS login in the administrative console and store this login
configuration in the Application Server configuration. However, WebSphere Application Server still supports the default JAAS login configuration
format (plain text file) that is provided by the JAAS default implementation. If duplicate login
configurations are defined in both the WebSphere Application Server
configuration API and the plain text file format, the one in the WebSphere Application Server 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
Due to a design oversight in JAAS Version 1.0, the javax.security.auth.Subject.getSubject
method does not return the subject that is 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, WebSphere Application Server provides a proxy LoginModule module 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 class path for the Java extension class loader with
this proxy LoginModule module.
If you do not want to use the Proxy LoginModule
module, you can place the LoginModule module in the app_server_root/lib/ext/ directory. However, this action is not
recommended due to the security risks.
If you do not want to use the Proxy LoginModule module, you can place the
LoginModule module 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 you
add the file to the /QIBM/UserData/Java400/ext/ directory, the file is also added to the
default class path for the Java extended directories, which is accessible to the entire operating
system
JAAS login configurations are defined in the WebSphere Application Server
configuration application programming interface (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 WebSphere Application Server client container. For more information, see Configuration entry settings for Java Authentication and Authorization Service.
- DefaultPrincipalMapping,
- Defines a special LoginModule module that is typically used by Java EE connectors to map an
authenticated WebSphere Application Server 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.
Attention: 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.
Procedure
- Delete a JAAS login configuration.
- Click Security > Global security.
- Under Java Authentication and Authorization Service, click Application
logins.
The Application Login Configuration panel is displayed.
- Select the check box for the login configurations to delete and click
Delete.
- Create a new JAAS login configuration.
- Click Security > Global security.
- Under Java Authentication and Authorization Service, click Application
logins.
- Click New.
The Application Login Configuration panel is
displayed.
- 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.
- Under Additional properties, click JAAS Login Modules.
- Click New.
- Specify the Module class name.
Specify the WebSphere Application Server proxy LoginModule module because of the limitation
of the class loader visibility.
- Specify the LoginModule implementation as the delegate property of the Proxy
LoginModule module.
The WebSphere Application Server proxy
LoginModule class name is com.ibm.ws.security.common.auth.module.proxy.WSLoginModuleProxy.
- Select Authentication strategy from the list and click
Apply.
- Under Additional properties, click Custom properties.
The Custom properties panel is displayed for the selected LoginModule.
- 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
true value. These properties are passed to the LoginModule class as options to the
initialize method of the LoginModule instance.
- Click Save.
Several
locations are within the
WebSphere Application Server directory structure
where you can place a JAAS login module. The following list provides locations for the JAAS login
module in order of recommendation:
- Within an enterprise archive (EAR) file for a specific Java Platform, Enterprise Edition
(Java EE)
application.
If you place the login module within the EAR file, the login module is accessible by
the specific application only.
- In the WebSphere Application Server-shared library.
If you place the
login module in the shared library, you 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 you place the JAAS login module in the Java extensions directory, the
login module is available to all applications.
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 you add the file to the
/QIBM/UserData/Java400/ext directory, you 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.
- Change the plain text file.
WebSphere Application Server supports the default JAAS
login configuration format, which is a plain text file, that is provided by the JAAS default
implementation. However, a tool is not provided that edits plain text files in this format. You 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.
WebSphere Application Server supports the default JAAS
login configuration format, which is a plain text file, that is provided by the JAAS default
implementation. However, a tool is not provided that edits plain text files in this format. You 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 Java Authentication and
Authorization Service (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.
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 you 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.
Results
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 that are
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.
However, new JAAS login configurations that are
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 that are used by enterprise applications to perform
custom authentication. Use these newly defined JAAS login configurations to perform programmatic
login.