| Documentation Contents

## Part I : Secure Authentication using the Java Authentication and Authorization Service (JAAS)

## Exercise 1 : Using the JAAS API

### Goal of this exercise:

The goal of this exercise is to learn how to use the Java Authentication and Authorization (JAAS) API to perform authentication.

### Background for this exercise:

JAAS provides a standard pluggable authentication framework (PAM) for the Java platform. An application uses the JAAS API to perform authentication - the process of verifying the identity of the user who is using the application and gathering his identity information into a container called a subject. The application can then use the identity information in the subject along with the JAAS API to make authorization decisions, to decide whether the authenticated user is allowed to access protected resources or perform restricted actions. This exercise demonstrates JAAS Authentication. It does not demonstrate JAAS Authorization.

### Resources for this exercise:

1. JAAS Reference Guide
2. JAAS Tutorials
3. JAAS javadocs: javax.security.auth, javax.security.auth.callback, javax.security.auth.kerberos, javax.security.auth.login, javax.security.auth.spi, javax.security.auth.x500
4. JAAS white paper

### Steps to follow:

1. Read the following sample code. This is located in src/Jaas.java. The code performs the following tasks:

1. Define a callback handler or use a predefined one. [line 2]
2. Create a LoginContext with a name that identifies which JAAS configuration entry to use. [line 5]
3. Perform the authentication. [line 8]
4. Define the task that the authenticated user is to perform [line 11]
5. Perform the action as the authenticated user [lines 14-15]
6. Logout.

`Subject.doAs` will run the code defined in `MyAction` as the authenticated user [lines 14-15]. This serves two purposes. First, code in `MyAction` that requires identity information for authentication to a service could get it from the subject. This exercise demonstrates this use. Second, if `MyAction` accesses any protected resources/operations, the identity information in the current subject would be used to make the corresponding access control decision. This second aspect is not covered in this exercise.

Code listing for `Jaas.java`.

`// Create a callback handler` `CallbackHandler callbackHandler = new TextCallbackHandler();` `// Create LoginContext with a callback handler` `LoginContext context = new LoginContext(name, callbackHandler);` `// Perform authentication` `context.login();` `// Create action to perform` `PrivilegedAction action = new MyAction();` `// Perform action as authenticated user` `Subject subject = context.getSubject();` `Subject.doAs(subject, action);` `// Logout` `context.logout();`

2. Make sure that the `%JAVA_HOME%/bin` is in the path, and JDK pointed to by the `%JAVA_HOME%` variable points to Java SE 6.
3. Compile the modified sample code.

       % cd auth/src
       % javac Jaas.java

   You will run this code in subsequent exercises after doing some set up. That ends this exercise.

### Summary:

This exercise introduced the main classes of the JAAS APIs: `LoginContext` and `Subject`. You learned how to use `LoginContext` to authenticate a user and collect its identity information in a `Subject`. You then learned how to use the `Subject` to perform an action as the authenticated user.

### Next Steps

1. Proceed to Exercise 2 to learn how to configure the sample application to use Kerberos for authentication.

## Exercise 2: Configuring JAAS for Kerberos Authentication

### Goal of this exercise:

The goal of this exercise is to learn how to configure a JAAS application to use Kerberos for authentication.

### Kerberos Background for this exercise:

Kerberos is an Internet standard protocol for trusted-third party authentication defined in RFC 4120. It is available on most modern computing platforms today, including Solaris, Windows XP, and Linux.

The Kerberos architecture is centered around a trusted authentication service called the key distribution center, or KDC. Users and services in a Kerberos environment are referred to as principals; each principal shares a secret (such as a password) with the KDC. A principal authenticates to Kerberos by proving to the KDC that it knows the shared secret. If the authentication is successful, the KDC issues a ticket-granting-ticket (TGT) to the principal. When the principal subsequently wants to authenticate to a service on the network, such as a directory service or a file service, (thereby, acting as a "client" of the service), it gives the TGT to the KDC to obtain a service ticket to communicate with the service. Not only does the service ticket indicate the identities of the client and service principals, it also contains a session key that can be used by the client and service to subsequently establish secure communication. To authenticate to the service, the client sends the service ticket to the service. When the service receives the ticket, it decodes it using the secret it shares with the KDC.
In this architecture, a principal only authenticates directly (once) to the KDC. It authenticates indirectly to all other services via the use of service tickets. Service tickets are how the KDC vouches for the identity of a principal. The ability of a principal to access multiple secure services by performing explicit authentication only once is called single sign-on.

JAAS Background for this exercise:
In JAAS, for a client principal, "logging into Kerberos" means acquiring the TGT and placing it in the `Subject`, so that it can be used for authentication with services that the client will access. For a service principal, "logging into Kerberos" means obtaining the secret keys that the service needs to decode incoming client authentication requests.

Resources for this exercise:

1. JAAS LoginModule Developer's Guide
2. The Kerberos Network Authentication Service (v5)
3. Example Login Configurations
4. Login module package javadocs: com.sun.security.auth.module
5. The JAAS and Java GSS-API Tutorials

Steps to follow:

1. Examine the JAAS configuration file. This is located in `src/jaas-krb5.conf
   `

This file contains two entries, one named "client" and one named "server." The "client" entry indicates that the `LoginContext` must use the `com.sun.security.auth.module.Krb5LoginModule`. The "server" entry indicates that the LoginContext must use the same login module, and use keys from the `sample.keytab` file for the principal `host/machineName`.

Code listing for `jaas-krb5.conf`.

`client {` `com.sun.security.auth.module.Krb5LoginModule required` `principal="test";` `};` `server {` `com.sun.security.auth.module.Krb5LoginModule required` `useKeyTab=true` `storeKey=true` `keyTab=sample.keytab` `principal="host/machineName";` `};`

2. Determine the hostname of your machine by executing the hostname command.

% hostname

3. Edit this file and change the entry for server principal to use the name of your machine. For example, if your machine name is j1hol-001, this line in the configuration file should look like this.

principal="host/j1hol-001"

4. Perform client authentication by typing

% java -Djava.security.auth.login.config=jaas-krb5.conf\
Jaas client
You will be prompted for a password. Enter "changeit". You should see the following output.

Output for running the JAAS example using the client entry from `jaas-krb5.conf`:

`Kerberos password for test: changeit` `Authenticated principal: [test@J1LABS.EXAMPLE.COM]` `Performing secure action...`

5. Perform server authentication by typing

% java -Djava.security.auth.login.config=jaas-krb5.conf\
Jaas server
You should see the following output.

Output for running JAAS example using "server" entry from `jaas-krb5.conf`.

`Authenticated principal: [host/j1hol-001@J1LABS.EXAMPLE.COM]` `Performing secure action...`

Summary:

In this exercise, you learned how to configure a JAAS application to use a Kerberos login module, both as a client principal who enters his/her username/password interactively, and as a service principal who gets its keys from a keytab file.

### Next Steps

1. Proceed to Part II to learn how to establish secure communication channels using Java security APIs.

Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved. Please send comments using this Feedback page. | Java Technology