Use of JAAS Login Utility

The JAAS Authentication tutorial shows how you can use the LoginContext and Subject classes to write a program to authenticate users to verify their identity.

This tutorial describes a Login utility that performs these operations and then executes any specified application as the authenticated user.

Use of the Login utility with a sample application is demonstrated in this tutorial. The next tutorial, Use of JAAS Login Utility and Java GSS-API for Secure Message Exchanges, a client/server application using the Java GSS-API, also uses the Login utility.

It is not necessary to read the previous tutorial on JAAS authentication prior to reading this one. However, you should read Appendix B: JAAS Login Configuration File for information as to what a login configuration file is, since one is needed for this and all other tutorials in this series.

As with all tutorials in this series of tutorials, the underlying technology used to support authentication is Kerberos. See Kerberos Requirements.

If you want to first see the tutorial code in action, you can skip directly to Running the Sample Program with the Login Utility and then go back to the other sections to learn more.

What You Need to Know About the Login Utility

You do not need to understand the code contained in Login.java; you can just use it as is. However, you need to understand some facts about what it does so that your program and login configuration file will properly work with it. The following is a summary of these facts, followed by sections with further information and examples.

The Login class does the following:

Assumes it is passed, as arguments, your application's top-level class name, followed by any arguments your application may require.
Assumes that the class name of your top-level application class is also used as the name of the entry to be looked up in your login configuration file.
Specifies the TextCallbackHandler class (from the com.sun.security.auth.callback package) as the class to be used when communicating with the user. This class can prompt the user for a user name and password.
Uses a LoginContext to authenticate the user. The LoginContext invokes the appropriate authentication technology, or LoginModule, to perform the authentication. LoginModules use a CallbackHandler (in our case, TextCallbackHandler) as needed to communicate with the user.
Allows the user three attempts to successfully log in.
Creates an instance of the MyAction class (also in Login.java), passing it the application arguments, if any.
Invokes Subject.callAs, passing it a Subject representing the user and the MyAction instance. The result is that the public static main method from your application is invoked and your application code is considered to be executed on behalf of the user.

Application and Other File Requirements

To utilize the Login utility to authenticate the user and execute your application, you may need a small number of additions or modifications to your login configuration file as described in Login Configuration File Requirements.

Application Requirements

In order to utilize the Login utility, your application code does not need anything special. All you need is for the entry point of your application to be the main method of a class you write, as usual.

The way to invoke Login such that it will authenticate the user and then instantiate MyAction to invoke your application is the following:

java <options> Login <AppName> <app arguments>

where <AppName> is your application's top-level class name and <app arguments> are any arguments required by your application. See Running the Sample Program with the Login Utility for the full command used for this tutorial.

Login Configuration File Requirements

Whenever a LoginContext is used to authenticate the user, you need a login configuration file to specify the desired login module. See the The Login Configuration section in the JAAS authentication tutorial for more information as to what a login configuration file is and what it contains.

When you use the Login utility, the name for the login configuration file entry must be exactly the same as your top-level application class name. See The Login Configuration File in this tutorial for an example.

The Sample Application Program

The Sample.java application does the following:

Reads and prints the value of the java.home system property,
Reads and prints the value of the user.home system property, and
Determines whether or not a file named foo.txt exists in the current directory.

The Login Configuration File

The sample.conf login configuration file for this tutorial contains a single entry, just like the login configuration file for the JAAS Authentication tutorial. The entry contents are the same since the class implementing the desired authentication technology in both cases is the Krb5LoginModule in the com.sun.security.auth.module package.

The only difference is the name used for the entry. In the previous tutorial we used the name "JaasSample", since that is the name used by the JaasAcn class to look up the entry. When you use the Login utility with your application, it expects the name for your login configuration file entry to be the same as the name of your top-level application class. That application class for this tutorial is named "Sample" so that must also be the name of the login configuration file entry. Thus the login configuration file looks like the following:

Sample {
   com.sun.security.auth.module.Krb5LoginModule required;
};

The "required" indicates that login using the Krb5LoginModule is required to "succeed" in order for authentication to be considered successful. The Krb5LoginModule succeeds only if the name and password supplied by the user are successfully used to log the user into the Kerberos KDC.

See the Krb5LoginModule JavaDoc API documentation for information about all the possible options that can be passed to Krb5LoginModule.

Running the Sample Program with the Login Utility

To execute the Sample application with the Login utility, do the following:

Place the following files into a directory:
- The Login.java source file.
- The Sample.java source file.
- The sample.conf login configuration file.
Compile Login.java and Sample.java:
```
javac Login.java Sample.java
```
Note that Login.java contains two classes and thus compiling Login.java creates Login.class and MyAction.class.
Create a JAR file named Login.jar containing Login.class and MyAction.class:
```
jar -cvf Login.jar Login.class MyAction.class
```
Create a JAR file named Sample.jar containing Sample.class:
```
jar -cvf Sample.jar Sample.class
```
Execute the Login class, specifying
- An appropriate -classpath clause that classes should be searched for in the Login.jar and Sample.jar JAR files
- -Djava.security.krb5.realm=<your_realm> that your Kerberos realm is the one specified
- -Djava.security.krb5.kdc=<your_kdc> that your Kerberos KDC is the one specified
- -Djava.security.auth.login.config=sample.conf that the login configuration file to be used is sample.conf
Note:
If you use a single equals sign (=) with the java.security.auth.login.config system property (instead of a double equals sign (==)), then the configurations specified by both this system property and the java.security file are used.

You pass the name of your application (in this case, Sample) as an argument to Login. You would then add as arguments any arguments required by your application, but in our case Sample does not require any.

The following are the full commands to use for Windows, Linux, and macOS. The only difference is that on Windows you use semicolons to separate classpath items, while you use colons for that purpose on Linux and macOS. Be sure to replace <your_realm> with your Kerberos realm, and <your_kdc> with your Kerberos KDC.

Here is the full command for Windows:
```
java -classpath Login.jar;Sample.jar
 -Djava.security.krb5.realm=<your_realm> 
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.auth.login.config=sample.conf Login Sample
```
Here is the full command for Linux and macOS:
```
java -classpath Login.jar:Sample.jar
 -Djava.security.krb5.realm=<your_realm>
 -Djava.security.krb5.kdc=<your_kdc>
 -Djava.security.auth.login.config=sample.conf Login Sample
```
Type the full command on one line. Multiple lines are used here for legibility. If the command is too long for your system, you may need to place it in a .bat file (for Windows) or a .sh file (for Linux and macOS) and then run that file to execute the command.

You will be prompted for your Kerberos user name and password, and the underlying Kerberos login module specified in the login configuration file will log you into Kerberos. Once authentication is successfully completed, the Sample code will be executed on behalf of you, the user. You will see a display of the values of your java.home and user.home system properties and a statement as to whether or not you have a file named foo.txt in the current directory.

For login troubleshooting suggestions, see Troubleshooting Logins.