# Java Authentication and Authorization Service (JAAS) Provider

## Overview

Spring Security provides a package able to delegate authentication requests to the Java Authentication and Authorization Service (JAAS). This package is discussed in detail below.

Central to JAAS operation are login configuration files. To learn more about JAAS login configuration files, consult the JAAS reference documentation available from Sun Microsystems. We expect you to have a basic understanding of JAAS and its login configuration file syntax in order to understand this section.

## Configuration

The `JaasAuthenticationProvider` attempts to authenticate a user’s principal and credentials through JAAS.

Let’s assume we have a JAAS login configuration file, `/WEB-INF/login.conf`, with the following contents:

    JAASTest {
        sample.SampleLoginModule required;
    };

Like all Spring Security beans, the `JaasAuthenticationProvider` is configured via the application context. The following definitions would correspond to the above JAAS login configuration file:

    <bean id="jaasAuthenticationProvider"
                class="org.springframework.security.providers.jaas.JaasAuthenticationProvider">
      <property name="loginConfig" value="/WEB-INF/login.conf"/>
      <property name="loginContextName" value="JAASTest"/>
      <property name="callbackHandlers">
        <list>
          <bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/>
          <bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/>
        </list>
      </property>
      <property name="authorityGranters">
        <list>
          <bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/>
        </list>
      </property>
    </bean>

The `CallbackHandler`s and `AuthorityGranter`s are discussed below.

### JAAS CallbackHandler

Most JAAS `LoginModule`s require a callback of some sort. These callbacks are usually used to obtain the username and password from the user.

In a Spring Security deployment, Spring Security is responsible for this user interaction (via the authentication mechanism). Thus, by the time the authentication request is delegated through to JAAS, Spring Security's authentication mechanism will already have fully-populated an Authentication object containing all the information required by the JAAS `LoginModule`.

Therefore, the JAAS package for Spring Security provides two default callback handlers, `JaasNameCallbackHandler` and `JaasPasswordCallbackHandler`. Each of these callback handlers implement `JaasAuthenticationCallbackHandler`. In most cases these callback handlers can simply be used without understanding the internal mechanics.

For those needing full control over the callback behavior, internally `JaasAutheticationProvider` wraps these `JaasAuthenticationCallbackHandler`s with an `InternalCallbackHandler`. The `InternalCallbackHandler` is the class that actually implements JAAS’ normal `CallbackHandler` interface. Any time that the JAAS `LoginModule` is used, it is passed a list of application context configured `InternalCallbackHandler`s. If the `LoginModule` requests a callback against the `InternalCallbackHandler`s, the callback is in-turn passed to the `JaasAuthenticationCallbackHandler`s being wrapped.

### JAAS AuthorityGranter

JAAS works with principals. Even "roles" are represented as principals in JAAS. Spring Security, on the other hand, works with Authentication objects. Each Authentication object contains a single principal, and multiple GrantedAuthority[]s. To facilitate mapping between these different concepts, Spring Security's JAAS package includes an `AuthorityGranter` interface.

An `AuthorityGranter` is responsible for inspecting a JAAS principal and returning a `String`. The `JaasAuthenticationProvider` then creates a `JaasGrantedAuthority` (which implements Spring Security’s GrantedAuthority interface) containing both the `AuthorityGranter`-returned `String` and the JAAS principal that the `AuthorityGranter` was passed. The `JaasAuthenticationProvider` obtains the JAAS principals by firstly successfully authenticating the user’s credentials using the JAAS `LoginModule`, and then accessing the `LoginContext` it returns. A call to `LoginContext.getSubject().getPrincipals()` is made, with each resulting principal passed to each `AuthorityGranter` defined against the `JaasAuthenticationProvider.setAuthorityGranters(List)` property.

Spring Security does not include any production `AuthorityGranter`s given that every JAAS principal has an implementation-specific meaning. However, there is a `TestAuthorityGranter` in the unit tests that demonstrates a simple `AuthorityGranter` implementation.