WebSphere Application Server Network Deployment, Version 6.0.x     Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

Web authentication using the Java Authentication and Authorization Service programming model

WebSphere Application Server supports the Java 2 Platform, Enterprise Edition (J2EE) declarative security model. You can define authentication and access control policy using the J2EE deployment descriptor. You can further stack custom LoginModules to customize WebSphere Application Server authentication mechanism. A custom LoginModule 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. Note that you should use the programming techniques 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 Release 4.0. Note that you should use declarative security (you should use the techniques described in this section as the last resort).

When the Lightweight Third-Party Authentication (LTPA) authentication mechanism single signon (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 note that the server-side subject is not deleted). When you use 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 directing client requests to your login page first. Your login page can use the JAAS programming model to perform authentication. You need to do the following to enable WebSphere Application Server Web LoginModules to generate SSO cookies.

  1. Create a new system login JAAS configuration on the Global Security panel.
    1. Clone the WEB_INBOUND login configuration and give it a new alias. 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.
    2. There are two LoginModules defined in your login configuration: ltpaLoginModule and wsMapDefaultInboundLoginModule. Select the ltpaLoginModule, and then select Custom properties. Add a login property name cookie with a value of true. The two LoginModules are enabled to generate LTPA SSO cookies. The cookie option defined at the ltpaLoginModule applies to both LoginModules in your login configuration. You should never add the cookie login option to the original WEB_INBOUND login configuration.
    3. Stack your custom LoginModule(s) in the new login configuration (optional).
  2. Use your login page for programmatic login:
    1. 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).
    2. 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.
  3. Use your programmatic logout page to revoke SSO cookies:
    1. Invoke the revokeSSOCookies method from the WSSecurityHelper class to revoke all SSO cookies. 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.
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);
		 }
	 }

For more information on JAAS authentication, refer to Developing programmatic logins with the Java Authentication and Authorization Service. For more information on AuthenLoginModule, refer to Example: Customizing a server-side Java Authentication and Authorization Service authentication and login configuration.




Related tasks
Developing programmatic logins with the Java Authentication and Authorization Service

Related reference
Example: Customizing a server-side Java Authentication and Authorization Service authentication and login configuration

Concept topic    

Terms of Use | Feedback

Last updated: Mar 17, 2005 4:28:29 AM CST
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/csec_jaasauthentprog.html

© Copyright IBM Corporation 2004, 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)