Develop with JAAS to log in programmatically

Java Authentication and Authorization Service (JAAS) is a new feature in WebSphere Application Server Version 5. It is also mandates by J2EE 1.3 Specification. Java Authentication and Authorization Service represents the strategic APIs for authentication and replaces the CORBA programmatic login APIs. Additionally, WebSphere Application Server has 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 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 provides these extensions to JAAS:

• com.ibm.websphere.security.auth.WSSubject
  Due to a design oversight in the JAAS 1.0, 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.

• UI support for defining new JAAS login configuration
  JAAS login configuration can be configured in the administrative console and stored in WebSphere common configuration model. Application can define new JAAS login configuration in the administrative console and the the data is persisted in the configuration repository (stored in the WebSphere common configuration model). However, WebSphere still support the default JAAS login configuration format (plan text file) provided by the JAAS default implementation. But if there are duplication login configurations defined in both the WebSphere common configuration and the plan text file format, the one in the WebSphere common configuration takes precedence. There are advantages to define the login configuration in the WebSphere common configuration:

  • UI support in defining JAAS login configuration.
  • The JAAS configuration login configuration can be managed centrally.
  • The JAAS configuration login configuration is distributed in a Network Deployment installation.

• 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:

  • WSLogin JAAS login configuration
    This is a generic JAAS login configuration can be used by Java clients, client container application, servlets, JSP, and enterprise bean components, for example. to perform authentication based on a user ID and password, or a token to the the WebSphere security runtime. However, this does not honors the CallbackHandler specified in the Client Container deployment descriptor.

  • ClientContainer JAAS login configuration
    This JAAS login configuration honors the CallbackHandler specified in the Client Container deployment descriptor. The Login Module of this login configuration will use the CallbackHandler in the Client Container deployment descriptor if one specified, even if the application code specified one CallbackHandler in the LoginContext. This is for Client Container application.

    Note: Subject authenticated with the above JAAS login configurations 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.

    Version 5.0.1 and later:

    • 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.

• Customer defined JAAS login configurations
  Customer 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.

• Naming requirements for programmatic login on a pure Java client
  When programmatic login occurs on a pure Java client and the property com.ibm.CORBA.validateBasicAuth equals true, it is necessary for the security code to know where the SecurityServer resides. Typically, the default InitialContext is sufficient when a java.naming.provider.url property is set as a system property or when the property is set in the jndi.properties file. In other cases it is not desirable to have the same java.naming.provider.url properties set in a system wide scope. In this case, there is a need to specify security specific bootstrap information in the sas.client.props file. The following is the order of precedence for determining how to find the SecurityServer in a pure Java client:

  1. Use the sas.client.props file and look for the following properties:

     com.ibm.CORBA.securityServerHost=myhost.mydomain
     com.ibm.CORBA.securityServerPort=mybootstrap port

     If you specify these properties, you are guaranteed that security looks here for the SecurityServer. The host and port specified can represent any valid WebSphere host and bootstrap port. The SecurityServer resides on all server processes and therefore it is not important which host or port you choose. If specified, the security infrastructure within the client process look up the SecurityServer based on the information in the sas.client.props file.

  2. Place the following code in your client application to get a new InitialContext():

      ...
       import java.util.Hashtable;
       import javax.naming.Context;
       import javax.naming.InitialContext;
       ...
        
       // Perform an InitialContext and default lookup prior to logging in so
       // that target realm and bootstrap host/port can be determined for
       // SecurityServer lookup.
       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("");
     
       // programmatic login code goes here.

     Complete this step prior to any programmatic login. It is in this code that you specify a URL provider for your naming context, but it must point to a valid WebSphere Application Server within the cell to which you are authenticating. This allows thread specific programmatic logins going to different cells to have a single system-wide SecurityServer location.

     For more information, see Example: JAAS programmatic login.

  3. Use the new default InitialContext() method, relying on the naming precedence rules:

     1. The InitialContext constructor
        This does not apply to the above example since the example uses the empty InitalContext constructor.

     2. System environment
        You can add JNDI properties to the system environment as an option on the java command invocation and by program code. The recommended way to set the provider URL in the system environment is as an option supplied to the Java command invocation. Setting the provider URL in this manner is not temporal, so that getting a default initial context will always yield the same result. It is generally recommended that program code not set the provider URL property in the system environment because as a side-effect, this could adversely affect other, possibly unrelated, code running elsewhere in the same process.

     3. jndi.properties file
        There may be many jndi.properties files that are within the scope of the class loader in effect. All jndi.properties files are used for setting JNDI properties, but the provider URL setting is determined by the first jndi.properties file returned by the class loader.

Version 5.0.2 JAAS usage

See the following topics for more information about using JAAS with WebSphere Application Server Version 5.0.2:

• Find the root cause login exception
• Get the RunAs Subject from the Thread
• Override the RunAs Subject on the Thread
• Get the Caller Subject from the Thread
• User revocation from a cache