Programmatic login for JAAS

Before you begin developing with programmatic login APIs, consider the following points:

• For the pure Java client application or client container application, initialize the client Object Request Broker (ORB) security prior to performing a JAAS login. Do this by running the following code prior to the JAAS login:

  ...
  import java.util.Hashtable;
  import javax.naming.Context;
  import javax.naming.InitialContext;
  ...
  // Perform an InitialContext and default lookup prior to logging 
  // in to initialize ORB security and for the bootstrap host/port 
  // to be determined for SecurityServer lookup. If you do not want 
  // to validate the userid/password during the JAAS login, disable 
  // the com.ibm.CORBA.validateBasicAuth property in the 
  // sas.client.props file.
  
  Hashtable env = new Hashtable();
  env.put(Context.INITIAL_CONTEXT_FACTORY, 
      "com.ibm.websphere.naming.WsnInitialContextFactory");
  env.put(Context.PROVIDER_URL, 
       "corbaloc:iiop:myhost.mycompany.com:2809");
  Context initialContext = new InitialContext(env);
  Object obj = initialContext.lookup("");
  

  Note: Set com.ibm.CORBA.validateBasicAuth=false whenever connecting to a z/OS® server. This function does not currently work from a distributed client to a z/OS server since the SecurityServer is located using the "UNAUTHENTICATED" principal, which is not accepted on a z/OS system.
• For the pure Java client application or the client container application, make sure that the host name and the port number of the target Java Naming and Directory Interface (JNDI) bootstrap properties are specified properly. See the Developing applications that use CosNaming (CORBA Naming interface) section for details.
• If the application uses custom JAAS login configuration, make sure that the custom JAAS login configuration is properly defined.
• Some of the JAAS APIs are protected by Java 2 security permissions. If these APIs are used by application code, make sure that these permissions are added to the application was.policy file. See Adding the was.policy file to applications for Java 2 security, Using PolicyTool to edit policy files for Java 2 security and Configuring the was.policy file for Java 2 security sections for details. For more details of which APIs are protected by Java 2 Security permissions, check the IBM® Developer Kit, Java Technology Edition; JAAS and the WebSphere Application Server public APIs documentation for more details. The following list contains the APIs that are used in the samples code provided in this documentation.
  • javax.security.auth.login.LoginContext constructors are protected by javax.security.auth.AuthPermission "createLoginContext".
  • javax.security.auth.Subject.doAs and com.ibm.websphere.security.auth.WSSubject.doAs are protected by javax.security.auth.AuthPermission "doAs".
  • javax.security.auth.Subject.doAsPrivileged and com.ibm.websphere.security.auth.WSSubject.doAsPrivileged are protected by javax.security.auth.AuthPermission "doAsPrivileged".
• com.ibm.websphere.security.auth.WSSubject: Due to a design oversight in JAAS Version 1.0, javax.security.auth.Subject.getSubject does not return the Subject associated with the running thread inside a java.security.AccessController.doPrivileged code block. This can present an inconsistent behavior that is problematic and causes an undesirable effort to work around. The com.ibm.websphere.security.auth.WSSubject API provides a workaround to associate the Subject to the running thread. The com.ibm.websphere.security.auth.WSSubject API extends the JAAS model to Java EE resources for authorization checks. The Subject that is associated with the running thread within com.ibm.websphere.security.auth.WSSubject.doAs or com.ibm.websphere.security.auth.WSSubject.doAsPrivileged code block is used for Java EE resources authorization checks.
• Administrative console support for defining new JAAS login configuration: You can configure JAAS login configuration in the administrative console and store it in the WebSphere Application Server configuration API. Applications can define new JAAS login configuration in the administrative console and the data is persisted in the configuration repository that is stored with the WebSphere Application Server configuration API. However, WebSphere Application Server still supports the default JAAS login configuration format that is provided by the JAAS default implementation. If duplication login configurations are defined in both the WebSphere Application Server configuration API and the plain text file format, the login configuration in the WebSphere Application Server configuration API takes precedence. Advantages to define the login configuration in the WebSphere Application Server configuration API include:
  • Defining the JAAS login configuration using the administrative console.
  • Managing the JAAS login configuration centrally.
  • Distributing the JAAS login configuration in a WebSphere Application Server Network Deployment installation.
• JAAS login configurations for WebSphere Application Server: WebSphere Application Server provides JAAS login configurations for applications to perform programmatic authentication to the WebSphere Application Server security runtime. These JAAS login configurations for WebSphere Application Server perform authentication to the configured authentication mechanism, Simple WebSphere Authentication Mechanism (SWAM) or Lightweight Third-Party Authentication (LTPA), and user registry (Local OS, LDAP, or Custom) based on the authentication data supplied. The authenticated Subject from these JAAS login configurations contain the required principal and credentials that can be used by the WebSphere Application Server security runtime to perform authorization checks on Java EE role-based protected resources.
  Note: SWAM is deprecated in WebSphere Application Server Version 8.5 and will be removed in a future release.
  Here are the JAAS login configurations that are provided by WebSphere Application Server:
  • WSLogin JAAS login configuration: A generic JAAS login configuration that a Java client, client container application, servlet, JSP file, enterprise bean, and so on, can use to perform authentication that is based on a user ID and password, or a token to the WebSphere Application Server security runtime. However, this configuration does not support the CallbackHandler handler that is specified in the client container deployment descriptor.
  • ClientContainer JAAS login configuration: This JAAS login configuration recognizes the CallbackHandler handler that is specified in the client container deployment descriptor. The login module of this login configuration uses the CallbackHandler handler in the client container deployment descriptor if one is specified, even if the application code specified one CallbackHandler handler in the login context. This is for client container application.
  • The Subjects that are authenticated with the previously mentioned JAAS login configurations contain a com.ibm.websphere.security.auth.WSPrincipal principal and a com.ibm.websphere.security.auth.WSCredential credential. If the authenticated Subject is passed to the com.ibm.websphere.security.auth.WSSubject.doAs method or the other doAs methods, the WebSphere Application Server security runtime can perform authorization checks on Java EE resources, based on the Subject com.ibm.websphere.security.auth.WSCredential credential.
• Customer-defined JAAS login configurations: You can define other JAAS login configurations. Use these login configurations to perform programmatic authentication to the custom authentication mechanism. However, the subjects from these customer-defined JAAS login configurations might not be used by the WebSphere Application Server security runtime to perform authorization checks if the subject does not contain the required principal and credentials.

The following determineCause example 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 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,
								// lets return now, this is the root from the WebSphere 
								//  Application Server perspective
								return root_exception;
						}
						if (temp_exception != null)
						{
								// we have an exception; 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;
						}
				}
		}

You can also receive the root cause exception from a servlet filter when addressing post-form login processing. This exception is useful because it shows the user what happened. You can issue the following API to obtain the root cause exception:

Throwable t = com.ibm.websphere.security.auth.WSSubject.getRootLoginException();  
if (t != null)  	
         t = determineCause(t);

WebSphere Application Server provides a non-prompt implementation of the javax.security.auth.callback.CallbackHandler interface, which is called com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl. Using this interface, an application can push authentication data to the WebSphere LoginModule instance to perform authentication. This capability is useful for server-side application code to authenticate an identity and to use that identity to invoke downstream Java EE resources.

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", 
      "securityrealm", "securedpassword"));

// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determine how authentication data is collected
// in this case, the authentication data is "push" 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE resource 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 a protected EJB
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}

WebSphere Application Server also provides a user interface implementation of the javax.security.auth.callback.CallbackHandler implementation to collect authentication data from a user through user interface login prompts. The com.ibm.websphere.security.auth.callback.WSGUICallbackHandlerImpl callback handler presents a user interface login panel to prompt users for authentication data.

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

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

// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determine how authentication data is collected
// in this case, the authentication date is collected by GUI login prompt
//   and pass 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE 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 a protected enterprise bean
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}

If the following options exist in the wsjaas_client.conf file, set them to false:

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

String krb5Ccache = /etc/krb5/krb5cc_utle;

try {
lc = new javax.security.auth.login.LoginContext("WSKRB5Login",
new com.ibm.websphere.security.auth.callback.WSCcacheCallBackHandlerImpl(user, krb5Realm, krb5Ccache, false));
// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determines how authentication data is collected
// in this case, the authentication date is collected by stdin prompt
// and passed 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE resource 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 a protected enterprise bean
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}

Application Server with the default Kerberos credential cache.

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

try {
lc = new javax.security.auth.login.LoginContext("WSKRB5Login",
new com.ibm.websphere.security.auth.callback.WSCcacheCallBackHandlerImpl(user, krb5Realm, null, true));
// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determines how authentication data is collected
// in this case, the authentication date is collected by stdin prompt
// and passed 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE resource 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 a protected enterprise bean
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}

Application Server with the Microsoft native Kerberos credential cache. The client must
login to the Microsoft Domain Controller.

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

try {
lc = new javax.security.auth.login.LoginContext("WSKRB5Login",
new com.ibm.websphere.security.auth.callback.WSCcacheCallBackHandlerImpl(null, null, null, true));
// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determines how authentication data is collected
// in this case, the authentication date is collected by stdin prompt
// and passed 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE resource 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 a protected enterprise bean
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}

WebSphere Application Server also provides a stdin implementation of the javax.security.auth.callback.CallbackHandler interface. The callback handler, com.ibm.websphere.security.auth.callback.WSStdinCallbackHandlerImpl, prompts and collects authentication data from a user through the stdin prompt.

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

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

// create a LoginContext and specify a CallbackHandler implementation
// CallbackHandler implementation determines how authentication data is collected
// in this case, the authentication date is collected by stdin prompt
// and passed 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();

// maybe 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
javax.security.auth.Subject s = lc.getSubject();
// get the authenticated subject

// Invoke a Java EE resource 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 a protected enterprise bean
} catch (Exception e) {
System.out.println("ERROR: error while accessing EJB 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
}