Configuring a JAAS programmatic login on the Liberty application client container

The Liberty application client container can be configured to use a JAAS programmatic login.

Before you begin

Review the different ways of authenticating users on the application client container, and decide whether the programmatic login option is best for your environment. For further details, see Authentication on the Liberty application client container.

About this task

A programmatic login is a type of form login that supports application presentation login forms for authentication. This approach requires the application developer to collect the user's credentials and authenticate that user. This method takes advantage of the JAAS framework to send a user's credentials to the server for authentication. The JAAS framework consists of creating a login context by specifying a JAAS login configuration and by using a callback handler to gather the user's credentials. When a subject is obtained from the login context, you can use a Liberty security API to set that Subject on the thread, and it is used for your outbound call to the server.
The JAAS login configuration specifies how and which login modules are used for authentication. Here are the JAAS login configurations that are provided by Liberty on the client:
  • WSLogin JAAS login configuration: A generic JAAS login configuration that a Liberty application client container application can use to perform authentication that is based on a user ID and password. However, this configuration does not support the CallbackHandler handler that is specified in the deployment descriptor of the client application module.
  • ClientContainer JAAS login configuration: This JAAS login configuration recognizes the CallbackHandler handler that is specified in the client application module's deployment descriptor, if one is specified. If a handler is not specified in the deployment descriptor, then the handler that was specified programmatically is used.

    The login modules that are specified by the JAAS login configuration implement a certain authentication technology. A login module can gather credentials from the user by using the javax.security.auth.callback.CallbackHandler interface. Liberty provides a non-prompt implementation of the CallbackHandler interface, which is called com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl. This implementation enables an application developer to specify the credentials directly in the application without having to prompt the user. There are two ways to specify your CallbackHandler implementation:

    • Specify your implementation programmatically, as an argument to the javax.security.auth.login.LoginContext constructor; for example:
      LoginContext logincontext = new LoginContext("ClientContainer", new WSCallbackHandlerImpl("user", "password"));
    • Specify your implementation name in the client application module's deployment descriptor (application-client.xml); for example:
      <callbackhandler>com.acme.callbackhandler.WSCallbackHandlerImpl/<callbackhandler>
Note: The WSLogin login configuration does not recognize the second option of specifying a CallbackHandler handler in the deployment descriptor.

Procedure

  1. Add the appSecurityClient-1.0 feature to your client.xml file.
    <feature>appSecurityClient-1.0</feature>
  2. Configure SSL for your client:
    1. Optional: Use the securityUtility command to create an SSL certificate for the client; for example:
      securityUtility createSSLCertificate --client=myClient --password=liberty
    2. Recommended: Use the securityUtility command to generate an xor encoded password. For example, to encode the password liberty:
      securityUtility encode liberty
    3. Add a keyStore element to your client.xml file. The following example uses the default SSL configuration:
      <keyStore id="defaultKeyStore" password="{xor}MzY9Oi0rJg=="/> <!-- pwd:
      liberty -->
  3. In the application code, create a Subject using the ClientContainer JAAS login configuration and the WSCallbackHandlerImpl callback handler.
    1. Before the application makes an outbound request, add the following code. Change the userName and userPassword to valid credentials for a user that exists in the user registry of the target server.
      CallbackHandler wscbh = new WSCallbackHandlerImpl("userName", "userPassword");
      LoginContext ctx = null;
      try {
            ctx = new LoginContext("ClientContainer", wscbh);
      } catch (LoginException le) {
            le.printStackTrace();
      }
      try {
            ctx.login();
      } catch (LoginException le) {
            le.printStackTrace();
      }
      Subject subject = ctx.getSubject();
  4. Set the Subject obtained in the previous step on the thread and use that Subject to look up an EJB. Use the WSSubject.doAs, or doAsPrivilieged APIs to accomplish this action. The Subject within the com.ibm.websphere.security.auth.WSSubject.doAs or com.ibm.websphere.security.auth.WSSubject.doAsPrivileged code block is used for Java™ Platform, Enterprise Edition (J2EE) resources authorization checks.
    WSSubject.doAs(subject, new PrivilegedAction() {
        public Object run() {
               try {
                      //Perform EJB lookup and invocation
               } catch (Exception ex) {
                      ex.printStackTrace();
               }
               return null;
        }
    });
  5. If Java 2 security is enabled on your client and your application code is calling JAAS or Liberty security APIs, add the necessary Java 2 Security permissions to either the permissions.xml file or the client.xml file of the application. For more details on which Liberty security APIs are protected by Java 2 Security permissions, see Programming Interfaces (APIs). For further details, see Java 2 Security.

What to do next

As on the server, you can use a custom login module to either make more authentication decisions or add information to the subject to make finer-grained authorization decisions inside your client application. For further details, see Configuring a JAAS custom login module for the Liberty application client container.

Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Monday, 5 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_config_jaas_prog_login
File name: twlp_config_jaas_prog_login.html