WebSphere® Application Server supports the Java™ Platform, Enterprise Edition
(Java EE)
declarative security model. You can define the authentication and access control policy using the
Java EE
deployment descriptor. You can further stack custom login modules to customize the WebSphere Application Server
authentication mechanism.
Before you begin
A custom login module can perform principal and credential mapping, custom security token
and custom credential-processing, and error-handling among other possibilities. Typically, you do
not need to use application code to perform authentication function. Use the programming techniques
that are described in this section if you have to perform authentication function in application
code. Use declarative security as a rule; use the techniques that are described in this section as a
last resort.
About this task
When the Lightweight Third-Party Authentication (LTPA) mechanism single sign-on (SSO) option is
enabled, the web client login session is tracked by an LTPA SSO token cookie after successful login.
At logout, this token is deleted to terminate the login session, but the server-side subject is not
deleted. When you use the declarative security model, the WebSphere Application Server web
container performs client authentication and login session management automatically. You can perform
authentication in application code by setting a login page without a Java EE security constraint and
by directing client requests to your login page first. Your login page can use the Java
Authentication and Authorization Service (JAAS) programming model to perform authentication. To
enable WebSphere
Application Server web login modules to generate SSO cookies, use the following steps.
Procedure
- Create a new system login JAAS configuration. To access the panel, click Security >
Global security. Under Java Authentication and Authorization Service, click System
logins.
- Manually clone the WEB_INBOUND login configuration, and give it a new alias. To clone the
login configuration, click New, enter a name for the configuration, click Apply, then
click JAAS login modules under Additional properties. Click New and configure the JAAS
login module. For more information, see Login module settings for Java Authentication and Authorization Service.
WebSphere
Application Server web container uses the WEB_INBOUND login configuration to authenticate web
clients. Changing the WEB_INBOUND login configuration affects all web applications in the cell. You
should create your own login configuration by cloning the contents of the WEB_INBOUND login
configuration.
- Select the wsMapDefaultInboundLoginModule login module and click Custom
properties. There are two login modules defined in your login configuration:
ltpaLoginModule and wsMapDefaultInboundLoginModule.
- Add a login property name cookie with a value of true. The two login
modules are enabled to generate LTPA SSO cookies. Do not add the cookie login option to the original
WEB_INBOUND login configuration.
- Stack your custom LoginModule(s) in the new login configuration (optional).
- Use your login page for programmatic login by perform a JAAS LoginContext.login using
your newly defined login configuration. After a successful login, either the
ltpaLoginModule or the wsMapDefaultInboundLoginModule generates an LTPA SSO cookie
upon a successful authentication. Exactly which LoginModule generates the SSO cookie depends on many
factors, including system authentication configuration and runtime condition (which is beyond the
scope of this section).
- Call the modified WSSubject.setRunAsSubject method to add the subject to the
authentication cache. The subject must be a WebSphere Application Server JAAS subject created by
LoginModule. Adding the subject to the authentication cache recreates a subject from SSO
token.
- Use your programmatic logout page to revoke SSO cookies by invoking the
revokeSSOCookies method from the WSSecurityHelper class.
The term "cookies" is used because WebSphere Application Server Version 5.1.1 and later support a new LTPA
SSO token with a different encryption algorithm but can be configured to generate the original LTPA
SSO token for backward compatibility. Note that the subject is still in the authentication cache and
only the SSO cookies are revoked.
Deprecated feature: The revokeSSOCookies(HttpServletRequest,
HttpServletResponse) method from the WSSecurityHelper class is deprecated. Use the functionality
provided by the Java Servlet-3.0 logout() method. Read
Servlet security methods.
Example
Use the following code sample to perform authentication.
Avoid trouble: If you set the password for the
WSCallbackHandlerFactoryset factory class for getting handlers to null, as is
done in the following example, you allow identity assertion without a password.
Suppose you wrote a LoginServlet.java:
Import com.ibm.wsspi.security.auth.callback.WSCallbackHandlerFactory;
Import com.ibm.websphere.security.auth.WSSubject;
public Object login(HttpServletRequest req, HttpServletResponse res)
throws ServletException {
PrintWriter out = null;
try {
out = res.getWriter();
res.setContentType("text/html");
} catch (java.io.IOException e){
// Error handling
}
Subject subject = null;
try {
LoginContext lc = new LoginContext("system.Your_login_configuration",
WSCallbackHandlerFactory.getInstance().getCallbackHandler(
userid, null, password, req, res, null));
lc.login();
subject = lc.getSubject();
WSSubject.setRunAsSubject(subject);
} catch(Exception e) {
// catch all possible exceptions if you want or handle them separately
out.println("Exception in LoginContext login + Exception = " +
e.getMessage());
throw new ServletException(e.getMessage());
}
The following is sample code to revoke the SSO cookies upon a programming logout:
The LogoutServlet.java:
public void logout(HttpServletRequest req, HttpServletResponse res,
Object retCreds) throws ServletException {
PrintWriter out =null;
try {
out = res.getWriter();
res.setContentType("text/html");
} catch (java.io.IOException e){
// Error Handling
}
try {
WSSecurityHelper.revokeSSOCookies(req, res);
} catch(Exception e) {
// catch all possible exceptions if you want or handle them separately
out.println("JAASLogoutServlet: logout Exception = " + e.getMessage());
throw new ServletException(e);
}
}