Title: Apache Felix JAAS Support

<style type="text/css">
img {
 width:auto;
}
</style>

[TOC]

Apache Felix JAAS support aims to simplify usage of JAAS in OSGi.

It supports following features

1. It can work both in Standalone and AppServer deployments i.e. in those environment where global JAAS configuration
   might be used by other applications and our usage of JAAS should not affect them
2. It enables usage of OSGi Configuration support to dynamically configure the login modules.
3. It allows LoginModule instances to be created via factories registered in OSGi Service Registry
4. It does not require the client to depend on any OSGi API
5. It works well with the dynamic nature of the OSGi env
6. Implementation depends only on Core OSGi API and ConfigAdmin (RFC 104)

## The Problem

The basic problem when using JAAS in OSGi is that it creates the LoginModule instance using reflection. This poses
problem in OSGi env as the client bundle does not have the visibility of all the required LoginModule classes.

A typical use of JAAS login looks like below

    :::java
    // let the LoginContext instantiate a new Subject
    LoginContext lc = new LoginContext("myApp");
    lc.login();


In this mode the `LoginContext` would access the global JAAS `Configuration` internally via `Configuration.getConfiguration()`.
It would then instantiate the LoginModule instance based on the configuration value. It uses the Thread Context ClassLoader (TCCL)
to create the instance. This approach fails to work when used in OSGi

1. The Thread Context ClassLoader is not defined in general in an OSGi context. It can and has to be set by the caller
   and OSGi cannot generally enforce that.
2. Instantiating a LoginModule generally requires access to internal implementation classes, by exporting these classes
   an implementing bundle would break its encapsulation.
3. Even if an implementation class was exported, importing this class in a consumer bundle would bind it to the specific
   implementation package provided, which violates the principle of loose coupling.

## Usage
The JAAS support involves following parts

1. LoginModule Registration - Mechanism by which LoginModule is registered with a given `realm`.
2. LoginContext Creation - Refers to the client code which constructs the LoginContext and then perform login operation

In section below we would first provide details on various ways by which a `LoginModule` would be configured so that
it can participate in JAAS flow and then about various ways in which the client code can invoke the JAAS logic

### LoginModule registration

The login modules can be registered via two mechanism

* OSGi Configuration - LoginModule are registered via OSGi configuration
* LoginModuleFactory - LoginModule are registered with the OSGi ServiceRegistry via `LoginModuleFactory`

#### A - OSGi Configuration
LoginModules can also be configured via configuration which is somewhat similar to the file based configuration. It consist of two parts

* Information around which bundle provides a specific LoginModule module
* Configuration required to be passed to that LoginModule

##### Manifest Header Entry
Any bundle which provides a LoginModule class needs to provide this information via *Jaas-ModuleClass* manifest header.

    :::xml
    <Jaas-ModuleClass>org.apache.felix.example.jaas.config.internal.SampleConfigLoginModule</Jaas-ModuleClass>

##### Configuration
JAAS module depends on OSGi Configuration for managing the LoginModule configuration. The configuration factory PID is
`org.apache.felix.jaas.Configuration.factory`.It provides the required metatype descriptor thus enabling configuration
via "Configuration" tab of Felix WebConsole

<img src="jaas-config.png" />

Configuration properties

* `jaas.classname` - Fully qualified name of the LoginModule class
* `jaas.controlFlag` - LoginControlFlag to use like required, optional, requisite, sufficient. Default is set to required
* `jaas.realmName` - JAAS Realm name. If specified then LoginModule would be registered against given realm otherwise it
   is bound to a 'other' realm
* `jaas.ranking` - Ranking for the LoginModule. It would be used to order the various login modules. The entries are sorted
   in a descending order (i.e. higher value ranked configurations come first)

For an example refer to [Sample Configuration][4]. It configures a SampleConfigLoginModule for `sample` realm

#### B - LoginModuleFactory

Any bundle which want to provide a LoginModule implementation would need to provide a factory service which implements the
[LoginModuleFactory][5] interface. The factory needs to be registeredwith following optional properties

* `jaas.controlFlag` - LoginControlFlag to use like required, optional, requisite, sufficient. Default is set to required
* `jaas.realmName` - JAAS Realm name. If specified then LoginModule would be registered against given realm otherwise it
   is bound to a 'other' realm.
* `service.ranking` - Ranking for the LoginModule. It would be used to order the various login modules.

Interface

    :::java
    /**
     * A factory for creating {@link LoginModule} instances.
     */
    public interface LoginModuleFactory
    {
        /**
         * Property name specifying whether or not a <code>LoginModule</code> is
         * REQUIRED, REQUISITE, SUFFICIENT or OPTIONAL. Refer to {@link javax.security.auth.login.Configuration}
         * for more details around the meaning of these flags
         *
         * By default the value is set to REQUIRED
         */
        String JAAS_CONTROL_FLAG = "jaas.controlFlag";

        /**
         * Property name specifying the Realm name (or application name) against which the
         * LoginModule would be registered.
         *
         * <p>If no realm name is provided then LoginModule would registered with a default realm
         * as configured
         */
        String JAAS_REALM_NAME = "jaas.realmName";

        /**
         * Creates the LoginModule instance
         * @return loginModule instance
         */
        LoginModule createLoginModule();
    }

Refer to [JdbcLoginModuleFactory][1] for one example of its usage. It constructs a JdbcLoginModule based on the
configuration and passes on the datasource.

### LoginContext creation patterns

There are various ways through which a JAAS Client can invoke the JAAS login.

#### LoginContextFactory Mode

In this mode the client logic obtains a reference to the `org.apache.felix.jaas.LoginContextFactory` service
and then creates a `LoginContext` instance

    :java
    LoginContextFactory loginContextFactory = ...
    CallbackHandler handler = ...;
    Subject subject = new Subject();
    try
    {
        LoginContext lc = loginContextFactory.createLoginContext("sample",subject,handler);
        lc.login();
        ...
    }
    catch (LoginException e)
    {
        handleAuthenticationFailure(e);
    }

Refer to [FactoryDemoServlet][6] for an example. Following points to be noted for this usage pattern

* Client code needs to depend on Apache Felix JAAS Support API
* No need to manage Thread Context Classloader while invoking `LoginContext`
* No need to import LoginModule related packages

#### Configuration SPI with Default Policy Mode

In this mode the client logic explicitly fetch the JAAS Configuration and then pass it on to the LoginContext. In this
mode the [JAAS Configuration Policy](#configuration-spi) is set to `Default`.

    :::java
    CallbackHandler handler = ...;

    Subject subject = new Subject();
    final ClassLoader cl = Thread.currentThread().getContextClassLoader();
    try
    {
        Configuration config = Configuration.getInstance(
                                  'JavaLoginConfig',      //Algorithm name
                                  null,                   //Extra params to be passed. For this impl its null
                                  'FelixJaasProvider'     //Name of the config provider
                          );
        Thread.currentThread().setContextClassLoader(getClass().getClassLoader());
        LoginContext lc = new LoginContext("sample", subject, handler, config);
        lc.login();

        ...
    }
    finally
    {
        Thread.currentThread().setContextClassLoader(cl);
    }

In above flow the `Configuration` instance is explicitly fetched and passed on to the

Refer to [TCCLDemoServlet][3] for an example. Following points to be noted for this usage pattern

* Client code needs to be aware of the name of the config provider.
* Client bundle would need to have an import for package `org.apache.felix.jaas.boot`.
  Refer to [Boot classpath](#boot-classpath) section for more details
* Global configuration is not modified so other users of JAAS are not affected

#### Replace Global Configuration Mode

In this mode the JAAS bundle would replace the Global configuration through Configuration.setConfiguration call. In this
mode the client code would use the normal LoginContext creation and the [JAAS Configuration Policy](#configuration-spi)
is set to `Replace Global Configuration`.

    :::java
    final ClassLoader cl = Thread.currentThread().getContextClassLoader();
    try
    {
        Thread.currentThread().setContextClassLoader(getClass().getClassLoader());

        // let the LoginContext instantiate a new Subject
        LoginContext lc = new LoginContext("appName");
        lc.login();
    }
    finally
    {
        Thread.currentThread().setContextClassLoader(cl);
    }

Following points need to be considered this mode

* Client code is not aware of the provider name
* Client bundle would need to have an import for package `org.apache.felix.jaas.boot`.
  Refer to [Boot classpath](#boot-classpath) section for more details
* Global configuration is modified. So it might cause issue while running in co deployed scenarios like Application Server.

Refer to [GlobalConfigDemoServlet][2] for an example

#### <a name="boot-classpath"></a>Modified Boot Classpath Mode

In previous modes (except the LoginContextFactory mode) the client code needs to switch the Thread Context Classloader (TCCL).
This is due the way JAAS logic instantiates the `LoginModule`. The Felix JAAS Support provides a `ProxyLoginModule` which
takes care of routing the LoginModule calls properly. However for this class to be visible to JAAS logic one of the
two approaches can be used

**Manage TCCL Explicitly**

The client bundle  would need to

1. Have an explicit import for `org.apache.felix.jaas.boot` package and
2. Manage TCCL explicitly which making JAAS related calls.

        :::java
        final Thread current = Thread.currentThread();
        final ClassLoader orig = current.getContextClassLoader();
        try {
          current.setContextClassLoader(getClass().getClassLoader());
         loginContext = new LoginContext(appName, subject,callbackHandler, config);
       } finally{
          current.setContextClassLoader(orig);
       }

Note that in above flow the TCCL is managed explicitly

**Modify Boot Classpath**

Another way would involve modifying the boot classpath.

1. Place the `org.apache.felix.jaas-xxx-boot.jar` in the boot classpath via `-Xbootclasspath:bootclasspath` option
2. Make the `org.apache.felix.jaas.boot` part of boot delegation list

        :::java
        LoginContext lc = new LoginContext("sample", subject, handler);
        lc.login();

Note that in above code we do not have to manage TCCL and neither add an import to `org.apache.felix.jaas.boot` package

Refer to [BootClasspathDemoServlet][7] for code sample

### <a name="configuration-spi"></a>JAAS Configuration SPI Settings

There are various ways in which LoginContext can be created depending on the usage mode. The JAAS support exposes
following properties

<img src="jaas-spi-config.png" align="center" />

* `Default JAAS Realm` - Name of the realm to use in case a LoginModule does not provide an explicit realmName.
   This is useful for single application mode where all LoginModule in an OSGi container are to be used. Usage of realm
   help in global settings because same config file is used to capture settings for all applications running on same JVM
* `JAAS Config Provider name` - Name against which the Configuration SPI provider should register
* `Configuration Policy` - This would be explained in next section
    * `Default` - Global configuration is not touched. Client code are expected to use the Configuration Spi mode
    * `Replace Global Configuration` - In this the global configuration is replaced with OSGi configuration. Client code
      need not perform any special configuration handling. At most they need to switch the Thread Context Classloader
    * `Proxy Global Configuration` - Similar to previous one  but it saves the default configuration and does a fallback
      check on that also. This should minimize any disruption in shared mode

## WebConsole Plugin

The runtime JAAS realm is exposed via a WebConsole Plugin.

<img src="jaas-plugin.png" align="center"/>

## Resources

1. [Java JAAS Reference Guide](http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/JAASRefGuide.html)
2. [JAAS Login Configuration File](http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/tutorials/LoginConfigFile.html)

[1]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/lm-jdbc/src/main/java/org/apache/felix/example/jaas/jdbc/JdbcLoginModuleFactory.java
[2]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/GlobalConfigDemoServlet.java
[3]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/TCCLDemoServlet.java
[4]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/launcher/src/main/config/org.apache.felix.jaas.Configuration.factory-simple.cfg
[5]: http://svn.apache.org/repos/asf/felix/trunk/jaas/src/main/java/org/apache/felix/jaas/LoginModuleFactory.java
[6]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/FactoryDemoServlet.java
[7]: http://svn.apache.org/repos/asf/felix/trunk/examples/jaas/app/src/main/java/org/apache/felix/example/jaas/app/internal/BootClasspathDemoServlet.java