Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Security

# Using JAAS Authentication in Java Clients

The following topics are covered in this section:

- JAAS and WebLogic Server
- JAAS Authentication Development Environment
- Writing a Client Application Using JAAS Authentication
- Using JNDI Authentication
- Java Client JAAS Authentication Code Examples

The sections refer to sample code which is available online at BEA's dev2dev web site, and is also included in the WebLogic Server distribution at:

>     SAMPLES_HOME\server\examples\src\examples\security\jaas

The `jaas` directory contains an `instructions.html` file, `ant` build files, a `sample_jaas.config` file, and the following Java files:

- `BaseClient.java`
- `BaseClientConstants.java`
- `SampleAction.java`
- `SampleCallbackHandler.java`
- `SampleClient.java`
- `TradeResult.java`
- `TraderBean.java`

You will need to look at the examples when reading the information in the following sections.

# JAAS and WebLogic Server

The Java Authentication and Authorization Service (JAAS) is a standard extension to the security in the J2SE 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 the `weblogic.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 call `weblogic.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.

Note: In order to implement security in a WebLogic client you must install the WebLogic Server software distribution kit on the Java client.

The following topics are covered in this section:

- JAAS Authentication APIs
- JAAS Client Application Components
- WebLogic LoginModule Implementation

## JAAS Authentication APIs

To implement Java clients that use JAAS authentication on WebLogic Server, you use a combination of Java J2SE 5.0 application programming interfaces (APIs) and WebLogic APIs.

Table 4-1 lists and describes the Java API packages used to implement JAAS authentication. The information in Table 4-1 is taken from the Java API documentation and annotated to add WebLogic Server specific information. For more information on the Java APIs, see the Javadocs at http://java.sun.com/j2se/1.5.0/docs/api/index.html and http://java.sun.com/j2ee/1.4/docs/api/index.html.

Table 4-2 lists and describes the WebLogic APIs used to implement JAAS authentication. For more information, see Javadocs for WebLogic Classes.

Table 4-1 Java JAAS APIs

Java JAAS API | Description
--- | ---
javax.security.auth.Subject | The `Subject` class represents the source of the request, and can be an individual user or a group. The `Subject` object is created only after the subject is successfully logged in.
javax.security.auth.login. LoginContext | The `LoginContext` class describes the basic methods used to authenticate `Subjects` and provides a way to develop an application independent of the underlying authentication technology. A `Configuration` specifies the authentication technology, or LoginModule, to be used with a particular application. Therefore, different LoginModules can be plugged in under an application without requiring any modifications to the application itself. After the caller instantiates a `LoginContext`, it invokes the `login` method to authenticate a `Subject`. This `login` method invokes the `login` method from each of the LoginModules configured for the name specified by the caller. If the `login` method returns without throwing an exception, then the overall authentication succeeded. The caller can then retrieve the newly authenticated `Subject` by invoking the `getSubject` method. Principals and credentials associated with the `Subject` may be retrieved by invoking the `Subject`'s respective `getPrincipals`, `getPublicCredentials`, and `getPrivateCredentials` methods. To log the `Subject` out, the caller invokes the `logout` method. As with the `login` method, this `logout` method invokes the `logout` method for each LoginModule configured for this `LoginContext`. For a sample implementation of this class, see Listing 4-3.
javax.security.auth.login. Configuration | This is an abstract class for representing the configuration of LoginModules under an application. The `Configuration` specifies which LoginModules should be used for a particular application, and in what order the LoginModules should be invoked. This abstract class needs to be subclassed to provide an implementation which reads and loads the actual configuration. In WebLogic Server, use a login configuration file instead of this class. For a sample configuration file, see Listing 4-2. By default, WebLogic Server uses the Sun Microsystems, Inc. configuration class, which reads from a configuration file.
javax.security.auth.spi. LoginModule | `LoginModule` describes the interface implemented by authentication technology providers. `LoginModules` are plugged in under applications to provide a particular type of authentication. While application developers write to the `LoginContext` API, authentication technology providers implement the LoginModule interface. A configuration specifies the LoginModule(s) to be used with a particular login application. Therefore, different LoginModules can be plugged in under the application without requiring any modifications to the application itself. Note: WebLogic Server provides an implementation of the LoginModule (`weblogic.security.auth.login. UsernamePasswordLoginModule`). BEA recommends that you use this implementation for JAAS authentication in WebLogic Server Java clients; however, you can develop your own LoginModule.
javax.security.auth. callback.Callback | Implementations of this interface are passed to a `CallbackHandler`, allowing underlying security services to interact with a calling application to retrieve specific authentication data, such as usernames and passwords, or to display information such as error and warning messages. `Callback` implementations do not retrieve or display the information requested by underlying security services. `Callback` implementations simply provide the means to pass such requests to applications, and for applications to return requested information to the underlying security services.
javax.security.auth. callback.CallbackHandler | An application implements a `CallbackHandler` and passes it to underlying security services so that they can interact with the application to retrieve specific authentication data, such as usernames and passwords, or to display information such as error and warning messages. `CallbackHandlers` are implemented in an application-dependent fashion. Underlying security services make requests for different types of information by passing individual `Callbacks` to the `CallbackHandler`. The `CallbackHandler` implementation decides how to retrieve and display information depending on the `Callbacks` passed to it. For example, if the underlying service needs a username and password to authenticate a user, it uses a `NameCallback` and `PasswordCallback`. The `CallbackHandler` can then choose to prompt for a username and password serially, or to prompt for both in a single window.

Table 4-2 WebLogic JAAS APIs

WebLogic JAAS API | Description
--- | ---
`weblogic.security.auth. Authenticate` | An authentication class used to authenticate user credentials. The WebLogic implementation of the LoginModule, (`weblogic.security.auth.login. UsernamePasswordLoginModule`, uses this class to authenticate a user and add `Principals` to the `Subject`. Developers who write LoginModules must also use this class for the same purpose.
`weblogic.security.auth. Callback. ContextHandlerCallback` | Underlying security services use this class to instantiate and pass a `ContextHandlerCallback` to the `invokeCallback` method of a `CallbackHandler` to retrieve the ContextHandler related to this security operation. If no ContextHandler is associated with this operation, the `javax.security.auth.callback.UnsupportedCallbackexception` is thrown. This callback passes the ContextHandler to LoginModule.login() methods.
`weblogic.security.auth. Callback.GroupCallback` | Underlying security services use this class to instantiate and pass a `GroupCallback` to the `invokeCallback` method of a `CallbackHandler` to retrieve group information.
`weblogic.security.auth. Callback.URLCallback` | Underlying security services use this class to instantiate and pass a `URLCallback` to the `invokeCallback` method of a `CallbackHandler` to retrieve URL information. The WebLogic implementation of the `LoginModule,` (`weblogic.security.auth.login. UsernamePasswordLoginModule`, uses this class. Note: Application developers should not use this class to retrieve URL information. Instead, they should use the weblogic.security.URLCallbackHandler.
weblogic.security.Security | This class implements the WebLogic Server client `runAs` methods. Client applications use the `runAs` methods to associate their `Subject` identity with the `PrivilegedAction` or `PrivilegedExceptionAction` that they execute. For a sample implementation, see Listing 4-5.
weblogic.security. URLCallbackHandler | The class used by application developers for returning a `username`, `password` and `URL`. Application developers should use this class to handle the `URLCallback` to retrieve URL information.

## JAAS Client Application Components

At a minimum, a JAAS authentication client application includes the following components:

- Java client

The Java client instantiates a `LoginContext` object and invokes the login by calling the object's `login()` method. The `login()` method calls methods in each LoginModule to perform the login and authentication.

The LoginContext also instantiates a new empty `javax.security.auth.Subject` object (which represents the user or service being authenticated), constructs the configured LoginModule, and initializes it with this new `Subject` and `CallbackHandler`.

The LoginContext subsequently retrieves the authenticated Subject by calling the LoginContext's `getSubject` method. The LoginContext uses the `weblogic.security.Security.runAs()` method to associate the `Subject` identity with the `PrivilegedAction` or `PrivilegedExceptionAction` to be executed on behalf of the user identity.

- LoginModule

The LoginModule uses the `CallbackHandler` to obtain the user name and password and determines whether that name and password are the ones required.

If authentication is successful, the LoginModule populates the Subject with a Principal representing the user. The Principal the LoginModule places in the Subject is an instance of `Principal`, which is a class implementing the `java.security.Principal` interface.

You can write LoginModule files that perform different types of authentication, including username/password authentication and certificate authentication. A client application can include one LoginModule (the minimum requirement) or several LoginModules.

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 J2SE security in WebLogic Server applications, but such usage is independent of the need to use the `Security.runAs()` method.

- Callbackhandler

The `CallbackHandler` implements the `javax.security.auth.callback.CallbackHandler` interface. The LoginModule uses the `CallbackHandler` to communicate with the user and obtain the requested information, such as the username and password.

- Configuration file

This file configures the LoginModule(s) used in the application. It specifies the location of the LoginModule(s) and, if there are multiple LoginModules, the order in which they are executed. This file enables Java applications to remain independent from the authentication technologies, which are defined and implemented using the LoginModule.

- Action file

This file defines the operations that the client application will perform.

- `ant` build script (`build.xml`)

This script compiles all the files required for the application and deploys them to the WebLogic Server applications directories.

For a complete working JAAS authentication client that implements the components described here, see the JAAS sample application in the SAMPLES_HOME`\server\examples\src\examples\security\jaas` directory provided with WebLogic Server. This example is also available online at BEA's dev2dev site.

For more information on the basics of JAAS authentication, see Sun's JAAS Authentication Tutorial available at http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html.

## WebLogic LoginModule Implementation

The WebLogic implementation of the `LoginModule` class is provided in the WebLogic Server distribution in the `weblogic.jar` file, located in the `WL_HOME\server\lib` directory.

Note: WebLogic Server supports all callback types defined by JAAS as well as all callback types that extend the JAAS specification.

The WebLogic Server `UsernamePasswordLoginModule` checks for existing system user authentication definitions prior to execution, and does nothing if they are already defined.

For more information about implementing JAAS LoginModules, see the LoginModule Developer's Guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html

## JVM-Wide Default User and the runAs() Method

The first time you use the WebLogic Server implementation of the LoginModule (`weblogic.security.auth.login.UsernamePasswordLoginModule`) to log on, the specified user becomes the machine-wide default user for the JVM (Java virtual machine). When you execute the `weblogic.security.Security.runAs()` method, it associates the specified `Subject` with the current thread's access permissions and then executes the action. If a specified `Subject` represents a non-privileged user (users who are not assigned to any groups are considered non-privileged), the JVM-wide default user is used. Therefore, it is important make sure that the `runAs()` method specifies the desired `Subject`. You can do this using one of the following options:

- Option 1: If the client has control of `main()`, implement the wrapper code shown in Listing 4-1 in the client code.
- Option 2: If the client does not have control of `main()`, implement the wrapper code shown in Listing 4-1 on each thread's `run()` method.

Listing 4-1 runAs() Method Wrapper Code

>     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: BEA 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-3.

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 online and as part of the distribution:

- Online: Follow the links for BEA-Certified Code from http://dev.bea.com/code.
- WebLogic Server Distribution: In the directory SAMPLES_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, see Javadocs 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 Listing 4-2 for the sample configuration file used in the JAAS client sample provided in the WebLogic Server distribution.

Listing 4-2 sample_jaas.config Code Example

>     /** 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 Listing 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.

Listing 4-3 LoginContext Code Fragment

>     ...
>     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 Listing 4-4 for an example of the `login()` method.

Listing 4-4 Login() Method Code Fragment

>     ...
>     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 the `weblogic.security.Security`.`runAs()` method. The `runAs()` method associates the specified Subject with the current thread's access permissions and then executes the action. See Listing 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 J2SE security in WebLogic Server applications, but such usage is independent of the need to use the `Security.runAs()` method.

Listing 4-5 getSubject() and runAs() Methods Code Fragment

>     ...
>     /**
>      * 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. BEA provides a a sample implementation, `SampleAction`, of the `javax.security.PrivilegedAction` class that executes an EJB to trade stocks. The `SampleAction.java` code is available online and as part of the distribution:

- Online: Follow the links for BEA-Certified Code from http://dev.bea.com/code.
- WebLogic Server Distribution: In the directory SAMPLES_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 Listing 4-6 for an example of the `login()` method.

Listing 4-6 logout() Method Code Example

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

Note: The `LoginModule.logout()` method is never called for a WebLogic Authentication provider or a custom Authentication provider, because once the `Principals` are created and placed into a `Subject`, the WebLogic Security Framework no longer controls the lifecycle of the `Subject`. Therefore, code that creates the JAAS `LoginContext` to log in and obtain the `Subject` should also call the `LoginContext` to log out. Calling `LoginContext.logout()` results in the clearing of the `Principals` from the `Subject`.

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

Note: JAAS is the preferred method of authentication, however, the WebLogic Authentication provider's LoginModule supports only user name 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 Authentication provider whose LoginModule does certificate authentication. For information on how to write LoginModules, see http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASLMDevGuide.html.

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

Table 4-3 JNDI Properties Used for Authentication

Property | Meaning
--- | ---
`INITIAL_CONTEXT_FACTORY` | Provides an entry point into the WebLogic Server environment. The class weblogic.jndi.WLInitialContextFactory is the JNDI SPI for WebLogic Server.
`PROVIDER_URL` | Specifies the host and port of the WebLogic Server that provides the name service. For example:`t3://weblogic:7001`.
`SECURITY_PRINCIPAL` | Specifies the identity of the user when that user authenticates to the default (active) security realm.
`SECURITY_CREDENTIALS` | Specifies the credentials of the user when that user authenticates to the default (active) security realm.

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

Listing 4-7 Example of Authentication

>     ...
>     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);

Note: For information on JNDI contexts and threads and how to avoid potential JNDI context problems, see JNDI Contexts and Threads and How to Avoid Potential JNDI Context Problems in Programming WebLogic JNDI.

Note: In versions of WebLogic Server prior to 9.0, when using protocols other than IIOP with JNDI, the first user is "sticky" in the sense that it becomes the default user when no other user is present. This is not a good practice, as any subsequent logins that do not have a username and credential are granted the identify of the default user.

In version 9.0, this is no longer true and there is no default user.

To return to the previous behavior, the `weblogic.jndi.WLContext.ENABLE_DEFAULT_USER` field must be set, either via the command line or through the `InitialContext` interface.

# Java Client JAAS Authentication Code Examples

A complete working JAAS authentication sample is provided with the WebLogic Server product. The sample is located in the SAMPLES_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 the `package.html` file in the sample directory. You can modify this code example and reuse it.