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.
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.
gotcha
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);
}
}