Authentication using JAAS

What are authentication and authorization?

Authentication can defined as the process to confirm the identity of an user. This can be achieved in a variety of ways, e.g. by entering a password, swiping an ID card, or using a biometrical scanner. The user need not be a human being, but can be a computer process.

Authorization can be defined as the process of deciding whether an authenticated user/system is allowed to access a certain resource or perform a certain action or not. A system may have many logical sections/modules, and not all users might have access to all modules. For example, one would not want an employee of a company to be authorized to get into parts of an application related to the company's appraisal system or other confidential data. This is where authorization comes into play. Though the user might have authenticated himself, he might not have sufficient authorization to access certain particular data items.

Both the above –authentication and authorization– are addressed by JAAS.

What is JAAS?

As the name –Java Authentication and Authorization Services– suggests, it provides a framework and an API for the authentication and authorization of users, whether they're human or automated processes. Both parts provide full-fledged capabilities and can be used in small-sized applications as well as enterprise applications, where security is a major concern. JAAS was inspired by PAM (Pluggable Authentication Module); one might say that JAAS is a Java version of PAM. It was introduced as an optional package for use with JDK 1.3, but has been integrated as part of the standard JDK 1.4.

JAAS uses a service provider approach to its authentication features, meaning that it is possible to configure different login modules for an application without changing any code. The application remains unaware of the underlying authentication logic. It's even possible for an application to contain multiple login modules, somewhat akin to a stack of authentication procedures.

In this article we will discuss the authentication part of JAAS in detail, starting with the various classes and interfaces which are involved, followed by a ready-to-run example.

Classes and interfaces

LoginModule (javax.security.auth.spi.LoginModule)

Login modules are written by implementing this interface; they contain the actual code for authentication. It can use various mechanisms to authenticate user credentials. The code could retrieve a password from a database and compare it to the password supplied to the module. It could also use a flat file, LDAP or any other means of storing user information for that purpose. Generally, in enterprise networks all authentication credentials are stored in one place, which might be accessed through LDAP.

LoginContext (javax.security.auth.login.LoginContext)

The login context is the core of the JAAS framework which kicks off the authentication process by creating a Subject. As the authentication process proceeds, the subject is populated with various principals and credentials for further processing.

Subject (javax.security.auth.Subject)

A subject represents a single user, entity or system –in other words, a client– requesting authentication.

Principal (java.security.Principal)

A principal represents the face of a subject. It encapsulates features or properties of a subject. A subject can contain multiple principals.

Credentials

Credentials are nothing but pieces of information regarding the subject in consideration. They might be account numbers, passwords, certificates etc. As the credential represents some important information, the further interfaces might be useful for creating a proper and secure credential – javax.security.auth.Destroyable and javax.security.auth.Refreshable. Suppose that after the successful authentication of the user you populate the subject with a secret ID (in the form of a credential) with which the subject can execute some critical services, but the credential should be removed after a specific time. In that case, one might want to implement the Destroyable interface. Refreshable might be useful if a credential has only a limited timespan in which it is valid.

The process of authentication

The authentication process starts with creating an instance of the LoginContext. Various constructors are available; the example uses the LoginContext(String, CallbackHandler) variety. The first parameter is the name (which acts as the index to the login module stack configured in the configuration file), and the second parameter is a callback handler used for passing login information to the LoginModule. CallbackHandler has a handle method which transfers the required information to the LoginModule. The example uses a very simple handler which saves the username and password in an instance variable, so that it can be passed on during the invocation of the handle method from the LoginModule. It's also possible to create callbacks that interact with the user to obtain user credentials, and transfer that information to the LoginModule for authentication.

An empty Subject is created before the authentication begins. This is passed to all login modules configured for the application. If the authentication is successful, the subject is populated with various principals and credentials.

The login method in the LoginContext is used to start the login process. After its successful completion, the application can retrieve the Subject from the LoginContext using the getSubject() method.

The login process has two phases. In the first phase, the individual login module's login method is invoked, but at this point the principals and credentials are not attached to the subject. The reason being that if the overall login fails, the principals and credentials attached to the subject are invalid, and have to be removed.

If the login process is successful the commit methods of all login modules are invoked, and the individual login modules take care of attaching the appropriate principals and credentials to the subject. If it fails then the abort method would be invoked; that gives the login modules a chance to perform any necessary cleanup.

The login method of the login module should return true if the authentication is successful, false if this module should be ignored, and it throws a LoginException if the authentication fails.

JAAS configuration in detail

Let's take a look at a sample JAAS configuration file.

CallbackHandler handler = new RanchCallbackHandler(userName, password);

try {
    LoginContext loginContext = new LoginContext("RanchLogin", handler);
    // starts the actual login
    loginContext.login();
} catch (LoginException e) {
    // log  error (failed to authenticate the user - do something about it)
    e.printStackTrace();
}

RanchLogin {
    com.javaranch.auth.RanchLoginModule required;
};

public boolean login() throws LoginException {
    boolean returnValue = true;
	if (callbackHandler == null){
        throw new LoginException("No callback handler supplied.");
    }

    Callback[] callbacks = new Callback[2];
    callbacks[0] = new NameCallback("Username");
    callbacks[1] = new PasswordCallback("Password", false);

    try {
        callbackHandler.handle(callbacks);
        String userName = ((NameCallback) callbacks[0]).getName();
        char [] passwordCharArray = ((PasswordCallback) callbacks[1]).getPassword();
        String password = new String(passwordCharArray);
        //--> authenticate if username is the same as password (yes, this is a somewhat simplistic approach :-)
        returnValue = userName.equals(password);
    } catch (IOException ioe)  {
        ioe.printStackTrace();
        throw new LoginException("IOException occured: "+ioex.getMessage());
    } catch (UnsupportedCallbackException ucbe) {
        ucbe.printStackTrace();
        throw new LoginException("UnsupportedCallbackException encountered: "+ucbe.getMessage());
    }

    System.out.println("logged in");
    return returnValue;
}

java -Duser=rahul
     -Dpass=rahul
     -Djava.security.auth.login.config=jaas.config
     -jar jaas-example.jar

java -Duser=rahul
     -Dpass=notrahul
     -Djava.security.auth.login.config=jaas.config
     -jar jaas-example.jar

java -Duser=rahul
     -Dpass=rahul
     -Djava.security.auth.login.config=jaas.config
     -Djava.security.manager
     -jar jaas-example.jar

java -Duser=rahul
     -Dpass=rahul
     -Djava.security.auth.login.config=jaas.config
     -Djava.security.manager
     -Djava.security.policy=policy.config
     -jar jaas-example.jar