WebSphere Application Server supports the Java 2 Platform, Enterprise
Edition (J2EE) declarative security model. You can define the authentication
and access control policy using the J2EE 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. For example, if you have applications that programmed to
the SSOAuthenticator helper function, you can use the following programming
interface. The SSOAuthenticator helper function was deprecated starting with
WebSphere Application Server Version 4.0. 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 J2EE 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
on the Global Security panel.
- Manually clone the WEB_INBOUND login configuration
and give it a new alias. To clone the login configuration, you can click New,
enter a name for the configuration, click Apply, and 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 ltpaLoginModule login
module and click Custom properties. There are two login modules defined
in your login configuration: ltpaLoginModule and wsMapDefaultInboundLoginModule.
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. The cookie
option defined at the ltpaLoginModule applies to both login modules
in your login configuration.
- Optional: Set an order for 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 Release 5.1.1 (and
later) release supports 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.
Example
Use the following code sample to perform authentication:
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);
}
}