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
- 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 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 WAS_HOME/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.
For a WebSphere Application Server Network Deployment installation,
make sure that a file synchronization operation is performed to propagate
the changes to other nodes.
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.
This location is not recommended
for WebSphere Application Server for z/OS® or WebSphere Business Integration Server Foundation.
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.