Develop with JAAS to log in programmatically

Java Authentication and Authorization Service (JAAS) is a new feature in WebSphere Application Server - Express Version 5. JAAS represents the strategic APIs for authentication and replaces the CORBA programmatic login APIs of previous releases. Additionally, WebSphere Application Server - Express provides some extensions to JAAS.

If the application is using custom JAAS login configuration, please make sure that the custom JAAS login configuration is properly defined. See Configure JAAS login configuration for details.

Some of the JAAS APIs are protected by Java 2 Security permissions, if these APIs are used by application code, please make sure that these permissions are added to the application was.policy file. See The was.policy file for more information. For more details of which APIs are protected by Java 2 Security permissions, please check the J2SDK, JAAS, and WebSphere Application Server - Express APIs javadoc. The following lists some of the APIs used in the sample code in this documentation and the Java 2 Security permissions required by these APIs:

WebSphere Application Server - Express provides these extensions to JAAS:

Version 5.0.1 and later:

For programmatic login with JAAS, the product provides an implementation of the javax.security.auth.callback.CallbackHandler interface, which is called com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl. Go to API documentation This com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl allows application to "push" authentication data to the WebSphere LoginModule to perform authentication. This can be useful for server side application code to authenticate an identity and use the identity to invoke downstream J2EE resources. Here is an example:

javax.security.auth.login.LoginContext lc = null;

try {
  lc = new javax.security.auth.login.LoginContext("WSLogin",
        new com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl
        ("user", "securedpassword"));

  // create a LoginContext and specify a CallbackHandler implementation
  // CallbackHandler implementation determine how authentication data is collected
  // in this case, the authentication data is "pushed" to the authentication
  // mechanism implemented by the LoginModule.
} catch(javax.security.auth.login.LoginException e) {
  System.err.println("ERROR: failed to instantiate a LoginContext "
                     + "and the exception: " + e.getMessage());
  e.printStackTrace();

  // may be javax.security.auth.AuthPermission "createLoginContext" is not granted
  // to the application, or the JAAS login configuration is not defined.
}

if (lc != null) {
  try {
    lc.login();  // perform login

    // get the authenticated subject
    javax.security.auth.Subject s = lc.getSubject();

    // Invoke a J2EE resources using the authenticated subject
    com.ibm.websphere.security.auth.WSSubject.doAs(s, 
                 new java.security.PrivilegedAction() {
      public Object run() {
        try {
          bankAccount.deposit(100.00);
          // where bankAccount is an protected resource
        } catch (Exception e) {
          System.out.println("ERROR: error while accessing resource, exception: " +
                              e.getMessage());
          e.printStackTrace();
        }
        return null;
      }
    }
  ) catch (javax.security.auth.login.LoginException e) {
    System.err.println("ERROR: login failed with exception: " + e.getMessage());
    e.printStackTrace();

    // login failed, might want to provide relogin logic
  }
}

See Example: JAAS programmatic login for more information.

Find the root cause login exception from a JAAS login (Version 5.0.2 and later)

If you get a LoginException after issuing the LoginContext.login() API, you can find the root cause exception from the configured user registry. In the login modules, the registry exceptions are wrapped by a com.ibm.websphere.security.auth.WSLoginFailedException. This exception has a getCause() method that allows you to pull out the exception that was wrapped.

Note: You are not always guaranteed to get an exception of type WSLoginFailedException, but you should note that most of the exceptions generated from the user registry show up here.

The following is a LoginContext.login() API example with associated catch block. WSLoginFailedException has to be casted to com.ibm.websphere.security.auth.WSLoginFailedException if you want to issue the getCause() API.

Note: The determineCause() example below can be used for processing CustomUserRegistry exception types.

try {
  lc.login(); 
} catch (LoginException le) {
  // Drill down through the exceptions as they might cascade through the runtime.
  Throwable root_exception = determineCause(le);
  
  // Now you can use "root_exception" to compare to a particular exception type.
  // For example, if you have implemented a CustomUserRegistry type, you would know
  // what to look for here.
}

/* Method used to drill down into the WSLoginFailedException to find the
 * "root cause" exception */
public Throwable determineCause(Throwable e) {
  Throwable root_exception = e, temp_exception = null;

  // Keep looping until there are no more embedded WSLoginFailedException
  // or WSSecurityException exceptions.
  while (true) {
    if (e instanceof com.ibm.websphere.security.auth.WSLoginFailedException) {                
      temp_exception =
         ((com.ibm.websphere.security.auth.WSLoginFailedException) e).getCause();
    }
    else if (e instanceof com.ibm.websphere.security.WSSecurityException) {
      temp_exception =
         ((com.ibm.websphere.security.WSSecurityException) e).getCause();
    }
    else if (e instanceof com.ibm.ws.security.registry.os400.OS400RegistryException) {
      // get OS400 specific error code, if configured
      System.out.println ("Error code from OS400 exception: "
         + ((com.ibm.ws.security.registry.os400.OS400RegistryException)e).getErrorCode());
      return e;
    }
    else if (e instanceof javax.naming.NamingException) {
      // check for Ldap embedded exception
      temp_exception = ((javax.naming.NamingException)e).getRootCause();
    }
    else if (e instanceof your_custom_exception_here) {
      // your custom processing here, if necessary
    }
    else {
      // This exception is not one of the types we are looking for, return now.
      // This is the root from the WebSphere perspective
      return root_exception;
    }
                 
    if (temp_exception != null) {
      // We have an exception, let's go back and see if this has another
      // one embedded within it.
      root_exception = temp_exception;
      e = temp_exception;
      continue;
    } 
    else  {
      // We finally have the root exception from this call path,
      // this has to occur at some point.
      return root_exception;
    }
  }
}