Using JAAS Authentication in Java Clients---weblogic document

JAAS and WebLogic Server

The Java Authentication and Authorization Service (JAAS) is a standard extension to the security in the Java EE Development Kit 5.0. JAAS provides the ability to enforce access controls based on user identity. JAAS is provided in WebLogic Server as an alternative to the JNDI authentication mechanism.

WebLogic Server clients use the authentication portion of the standard JAAS only. The JAAS LoginContext provides support for the ordered execution of all configured authentication provider LoginModule instances and is responsible for the management of the completion status of each configured provider.

Note the following considerations when using JAAS authentication for Java clients:

• WebLogic Server clients can either use the JNDI login or JAAS login for authentication, however JAAS login is the preferred method.

• While JAAS is the preferred method of authentication, the WebLogic-supplied LoginModule (weblogic.security.auth.login.UsernamePasswordLoginModule) only supports username and password authentication. Thus, for client certificate authentication (also referred to as two-way SSL authentication), you should use JNDI. To use JAAS for client certificate authentication, you must write a custom LoginModule that does certificate authentication.

  Note:

  If you write your own LoginModule for use with WebLogic Server clients, have it call weblogic.security.auth.Authenticate.authenticate() to perform the login.

• To perform a JAAS login from a remote Java client (that is, the Java client is not a WebLogic Server client), you may use the WebLogic-supplied LoginModule to perform the login. However, if you elect not to use the WebLogic-supplied LoginModule but decide to write your own instead, you must have it call theweblogic.security.auth.Authenticate.authenticate() method to perform the login.

• If you are using a remote, or perimeter, login system such as Security Assertion Markup Language (SAML), you do not need to callweblogic.security.auth.Authenticate.authenticate(). You only need to call the authenticate() method if you are using WebLogic Server to perform the logon.

  Note:

  WebLogic Server provides full container support for JAAS authentication and supports full use of JAAS authentication and authorization in application code.

• Within WebLogic Server, JAAS is called to perform the login. Each Authentication provider includes a LoginModule. This is true for servlet logins as well as Java client logins via JNDI or JAAS. The method WebLogic Server calls internally to perform the JAAS logon is weblogic.security.auth.Authentication.authenticate(). When using the Authenticate class, weblogic.security.SimpleCallbackHandler may be a useful helper class.

• While WebLogic Server does not protect any resources using JAAS authorization (it uses WebLogic security), you can use JAAS authorization in application code to protect the application‘s own resources.

For more information about JAAS, see the JAAS documentation at http://java.sun.com/products/jaas/reference/docs/index.html.

JAAS Authentication Development Environment

Whether the client is an application, applet, Enterprise JavaBean (EJB), or servlet that requires authentication, WebLogic Server uses the JAAS classes to reliably and securely authenticate to the server. JAAS implements a Java version of the Pluggable Authentication Module (PAM) framework, which permits applications to remain independent from underlying authentication technologies. Therefore, the PAM framework allows the use of new or updated authentication technologies without requiring modifications to a Java application.

WebLogic Server uses JAAS for remote Java client authentication, and internally for authentication. Therefore, only developers of custom Authentication providers and developers of remote Java client applications need to be involved with JAAS directly. Users of Web browser clients or developers of within-container Java client applications (for example, those calling an EJB from a servlet) do not require direct use or knowledge of JAAS.

The following topics are covered in this section:

• JAAS Authentication APIs

• JAAS Client Application Components

• WebLogic LoginModule Implementation

import java.security.PrivilegedAction;
import javax.security.auth.Subject;
import weblogic.security.Security;

public class client
{
  public static void main(String[] args)
  {
  Security.runAs(new Subject(),
    new PrivilegedAction() {
       public Object run() {
       //
       //If implementing in client code, main() goes here.
       //
       return null;
       }
    });
  }
}

Writing a Client Application Using JAAS Authentication

To use JAAS in a WebLogic Server Java client to authenticate a subject, perform the following procedure:

1. Implement LoginModule classes for the authentication mechanisms you want to use with WebLogic Server. You will need a LoginModule class for each type of authentication mechanism. You can have multiple LoginModule classes for a single WebLogic Server deployment.

   Note:

   Oracle recommends that you use the implementation of the LoginModule provided by WebLogic Server (weblogic.security.auth.login.UsernamePasswordLoginModule) for username/password authentication. You can write your own LoginModule for username/password authentication, however, do not attempt to modify the WebLogic Server LoginModule and reuse it. If you write your own LoginModule, you must have it call the weblogic.security.auth.Authenticate.authenticate() method to perform the login. If you use a remote login mechanism such as SAML, you do not need to call the authenticate() method. You only need to call authenticate() if you are using WebLogic Server to perform the logon.

   The weblogic.security.auth.Authenticate class uses a JNDI Environment object for initial context as described in Table 4-1.

2. Implement the CallbackHandler class that the LoginModule will use to communicate with the user and obtain the requested information, such as the username, password, and URL. The URL can be the URL of a WebLogic cluster, providing the client with the benefits of server failover. The WebLogic Server distribution provides a SampleCallbackHandler which is used in the JAAS client sample. The SampleCallbackHandler.java code is available as part of the distribution in the directorySAMPLES_HOME\server\examples\src\examples\security\jaas.

   Note:

   Instead of implementing your own CallbackHandler class, you can use either of two WebLogic-supplied CallbackHandler classes, weblogic.security.SimpleCallbackHandler or weblogic.security.URLCallbackHandler. For more information on these classes, seeJavadocs for WebLogic Classes.

3. Write a configuration file that specifies which LoginModule classes to use for your WebLogic Server and in which order the LoginModule classes should be invoked. See Example 4-2 for the sample configuration file used in the JAAS client sample provided in the WebLogic Server distribution.

/** Login Configuration for the JAAS Sample Application **/
Sample {
    weblogic.security.auth.login.UsernamePasswordLoginModule
            required debug=false;
};

1. In the Java client, write code to instantiate a LoginContext. The LoginContext consults the configuration file, sample_jaas.config, to load the default LoginModule configured for WebLogic Server. See Example 4-3 for an example LoginContext instantiation.

   Note:

   If you use another means to authenticate the user, such as an Identity Assertion provider or a remote instance of WebLogic Server, the default LoginModule is determined by the remote source.

...
import javax.security.auth.login.LoginContext;
...
    LoginContext loginContext = null;
    try
    {
      // Create LoginContext; specify username/password login module
      loginContext = new LoginContext("Sample", 
             new SampleCallbackHandler(username, password, url));
    }

1. Invoke the login() method of the LoginContext instance. The login() method invokes all the loaded LoginModules. Each LoginModule attempts to authenticate the subject. If the configured login conditions are not met, the LoginContext throws a LoginException. See Example 4-4 for an example of the login() method.

...
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;
import javax.security.auth.login.FailedLoginException;
import javax.security.auth.login.AccountExpiredException;
import javax.security.auth.login.CredentialExpiredException;
...
 /**
     * Attempt authentication
     */
    try
    {
      // If we return without an exception, authentication succeeded
      loginContext.login();
    }
    catch(FailedLoginException fle)
    {
      System.out.println("Authentication Failed, " +
                               fle.getMessage());
      System.exit(-1);
    }
    catch(AccountExpiredException aee)
    {
      System.out.println("Authentication Failed: Account Expired");
      System.exit(-1);
    }
    catch(CredentialExpiredException cee)
    {
      System.out.println("Authentication Failed: Credentials
                               Expired");
      System.exit(-1);
    }
    catch(Exception e)
    {
      System.out.println("Authentication Failed: Unexpected
                               Exception, " + e.getMessage());
      e.printStackTrace();
      System.exit(-1);
    }

1. Write code in the Java client to retrieve the authenticated Subject from the LoginContext instance using the javax.security.auth.Subject.getSubject() method and call the action as the Subject. Upon successful authentication of a Subject, access controls can be placed upon that Subject by invoking theweblogic.security.Security.runAs() method. The runAs() method associates the specified Subject with the current thread‘s access permissions and then executes the action. See Example 4-5 for an example implementation of the getSubject() and runAs() methods.

   Note:

   Use of the JAAS javax.security.auth.Subject.doAs methods in WebLogic Server applications do not associate the Subject with the client actions. You can use the doAs methods to implement Java EE security in WebLogic Server applications, but such usage is independent of the need to use the Security.runAs() method.

...
/**
 * Retrieve authenticated subject, perform SampleAction as Subject
 */
   Subject subject = loginContext.getSubject();
   SampleAction sampleAction = new SampleAction(url);
   Security.runAs(subject, sampleAction);
   System.exit(0);
...

1. Write code to execute an action if the Subject has the required privileges. Oracle provides a a sample implementation, SampleAction, of thejavax.security.PrivilegedAction class that executes an EJB to trade stocks. The SampleAction.java code is available as part of the distribution in the directorySAMPLES_HOME\server\examples\src\examples\security\jaas.

2. Invoke the logout() method of the LoginContext instance. The logout() method closes the user‘s session and clear the Subject. See Example 4-6 for an example of thelogin() method.

...
import javax.security.auth.login.LoginContext;
...
try
    {
      System.out.println("logging out...");
      loginContext.logout();
    }

Using JNDI Authentication

Java clients use the Java Naming and Directory Interface (JNDI) to pass credentials to WebLogic Server. A Java client establishes a connection with WebLogic Server by getting a JNDI InitialContext. The Java client then uses the InitialContext to look up the resources it needs in the WebLogic Server JNDI tree.

To specify a user and the user‘s credentials, set the JNDI properties listed in Table 4-1.

INITIAL_CONTEXT_FACTORY 

PROVIDER_URL 

SECURITY_PRINCIPAL 

SECURITY_CREDENTIALS 

These properties are stored in a hash table that is passed to the InitialContext constructor. Example 4-7illustrates how to use JNDI authentication in a Java client running on WebLogic Server.

...
Hashtable env = new Hashtable();
     env.put(Context.INITIAL_CONTEXT_FACTORY,
              "weblogic.jndi.WLInitialContextFactory");
     env.put(Context.PROVIDER_URL, "t3://weblogic:7001");
     env.put(Context.SECURITY_PRINCIPAL, "javaclient");
     env.put(Context.SECURITY_CREDENTIALS, "javaclientpassword");
     ctx = new InitialContext(env);

Java Client JAAS Authentication Code Examples

A complete working JAAS authentication sample is provided with the WebLogic Server product. The sample is located in theSAMPLES_HOME\server\examples\src\examples\security\jaas directory. For a description of the sample and instructions on how to build, configure, and run this sample, see thepackage.html file in the sample directory. You can modify this code example and reuse it.

reference :http://sqltech.cl/doc/oas11gR1/web.1111/e13711/fat_client.htm#autoId0