Develop with JAAS to log in programmatically

Java Authentication and Authorization Service (JAAS) represents the strategic APIs for authentication and replaces the CORBA programmatic login APIs. Additionally, WebSphere Application Server - Express has provides some extensions to JAAS.

If the application is using a custom JAAS login configuration, make sure that the custom JAAS login configuration is properly defined. For more information, see Configure JAAS login configuration.

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 for more details. 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:

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.

WebSphere Application Server - Express provides these extensions to JAAS:

com.ibm.websphere.security.auth.WSSubject
Due to a design oversight in the JAAS 1.0 specification, javax.security.auth.Subject.getSubject() does not return the Subject associated with the thread of execution inside a java.security.AccessController.doPrivileged() code block. This can present a inconsistent behavior that is problematic and causes undesireable effort. com.ibm.websphere.security.auth.WSSubject provides a workaround to associate Subject to thread of execution.

com.ibm.websphere.security.auth.WSSubject extends the JAAS model to J2EE resources for authorization checks. If the Subject associates with the thread of execution within com.ibm.websphere.security.auth.WSSubject.doAs() or if the com.ibm.websphere.security.auth.WSSubject.doAsPrivileged() code block contains product credentials, the Subject will be used for J2EE resources authorization checks. For more information, see com.ibm.websphere.security.auth.WSSubject.
WebSphere JAAS login configurations
WebSphere provides JAAS login configurations for application to perform programmatic authentication to the WebSphere security runtime. These WebSphere JAAS login configurations perform authentication to the WebSphere configured authentication mechanism (SWAM or LTPA) and user registry (LocalOS, 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 WebSphere security runtime to perform authorization checks on J2EE role-based protected resources. Here is the JAAS login configurations provided by WebSphere Application Server - Express:
- WSLogin JAAS login configuration
  This is a generic JAAS login configuration can be used by Java servlets and JavaServer Pages, for example, to perform authentication. The authentication is based on a user ID and password or a token that is passed to the the WebSphere security runtime. However, this does not honor the CallbackHandler specified in the Client Container deployment descriptor.
  
  Note: A subject that is authenticated with the WSLogin JAAS login configuration contains a com.ibm.websphere.security.auth.WSPrincipal and a com.ibm.websphere.security.auth.WSCredential. If the authenticated Subject is passed in com.ibm.websphere.security.auth.WSSubject.doAs() (or the other doAs() methods), the WebSphere security runtime can perform authorization checks on J2EE resources based on the Subject com.ibm.websphere.security.auth.WSCredential.
  
  The subject object generated by the WSLoginModuleImpl instance and WSClientLoginModuleImpl instance contains a principal that implements the WSPrincipal interface. Using the getCredential() method for a WSPrincipal object returns an object that implements the WSCredential interface. You can also find the WSCredential object instance in the PublicCredentials list of the subject instance. You should retrieve the WSCredential object from the PublicCredentials list instead of using the getCredential() method.
  
  The getCallerPrincipal() method for the WSSubject class returns a string representing the caller security identity. The return type differs from the getCallerPrincipal() method of the EJBContext interface (which is java.security.Principal).
  
  The Subject object generated by the J2C DefaultPrincipalMapping module contains a resource principal and a PasswordCredentials list. The resource principal represents the caller.
User-defined JAAS login configurations
Users can define other JAAS login configurations. See Configure Java Authentication and Authorization Service login for details. Use these login configurations to perform programmatic authentication to the customer's authentication mechanism. However, the Subjects from these customer defined JAAS login configurations might not be able to be used by WebSphere security runtime to perform authorization checks if it does not contains the required principal and credentials.

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. 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. See Example: JAAS programmatic login for more information.

See the following topics for more information about using JAAS with WebSphere Application Server - Express: