== LoginModule Bridge Profile


This chapter defines an internal contract that specifies how a server-side message layer authentication module
(that is, an implementation of the `ServerAuthModule` interface as defined
by this specification) may delegate some of its security processing
responsibilities to a (JAAS) `LoginModule`. A `LoginModule` is an object
that implements the `javax.security.auth.spi.LoginModule` interface in the
Java Platform, Standard Edition.

[[a685]]
=== Processing Model

The `ServerAuthModule` must create an instance
of a `javax.security.auth.login.LoginContext`. If the `options` argument
passed to the initialize method of the `ServerAuthModule` contains a
non-null `String` value for the `String` key
"javax.security.auth.login.LoginContext", then the `ServerAuthModule` must
pass this value as the name parameter in its calls to the `LoginContext`
constructor. If the options argument does not contain a non-null String
value for this key, the `ServerAuthModule` must use its own fully
qualified class name in its calls to the constructor. In either case,
the administrator of the `javax.security.auth.login.Configuration` system
of the `LoginContext` is responsible for establishing the
`javax.security.auth.login.AppConfigurationEntry` objects (with
corresponding login module name, control flag, and initialization
options) to be returned for the entry name used by the `ServerAuthModule`
and for the default entry name "other".

If the `ServerAuthModule` passes a `Subject` to
the LoginContext constructor, it must pass its client `Subject`. The
`ServerAuthModule` must pass a `CallbackHandler` to the constructor and the
passed `CallbackHandler` must conform to the requirements of
<<a692>>

A new LoginContext instance should be created
for each new request, and a `LoginContext` instance should not be shared
across different requests. Once a `LoginContext` object has been created,
the `LoginContext.login` method may be invoked from within the
`ServerAuthModule.validateRequest` method to delegate security processing
to the `LoginModule` objects configured in the `LoginContext`.

=== Division of Responsibility

A `ServerAuthModule` must only interact with a
`LoginModule` in a protocol-independent fashion. Specifically, a
`ServerAuthModule` is the only entity that may interpret protocol-specific
messages (a SOAP request or an HTTP Servlet request, for example). A
`LoginModule` must only perform protocol-independent security processing
(for example, verifying a username/password that was transmitted in the
request).

A `LoginModule` requests information from the
`ServerAuthModule` using the `ServerAuthModule` provided `CallbackHandler`.
Since the `LoginModule` must only perform protocol-independent operations,
it follows that any callback it requests from the handler must also be
protocol-independent. It is the responsibility of the provided
`CallbackHandler` implementation to return the requested
protocol-independent information to the `LoginModule`. The `CallbackHandler`
is responsible for any protocol-specific message parsing required to
extract the protocol-independent information returned by the
`CallbackHandler`.

[[a692]]
=== Standard Callbacks

This profile requires that the
`CallbackHandler` provided by the `ServerAuthModule` to the `LoginContext`
constructor support the `javax.security.auth.callback.NameCallback` and
the `javax.security.auth.callback.PasswordCallback`. If the
`ServerAuthModule` passes its client `Subject` to the `LoginContext`
constructor, the `CallbackHandler` provided to the `LoginContext`
constructor must also support the `GroupPrincipalCallback`. Future
versions of this profile may require that additional callbacks be
supported by the handler.

[[a694]]
=== Subjects

If authentication succeeds, a `LoginModule` may
update its `Subject` instance with authenticated Principal and credential
objects. If the `ServerAuthModule` did not pass its client `Subject` to the
`LoginContext` constructor, then it must transfer the Principals and
credentials from the `LoginContext` `Subject` to the client `Subject`.

If the `ServerAuthModule` is implementing a
profile of this specification that requires the module to employ the
`CallerPrincipalCallback`, then the `ServerAuthModule` must satisfy this
requirement using the `CallbackHandler` provided to the `ServerAuthModule`,
and the `CallerPrincipalCallback` must be constructed using the
namefootnote:[The `CallerPrincipalCallback` may be constructed with a `String` argument containing the `name` value, or with a `Principal` argument whose `getName` method returns the name value.] value that would be obtained by the
`LoginModule` if it were to use its `CallbackHandler` to handle a
NameCallback.

=== Logout

When `ServerAuthModule.cleanSubject` is called
on the client `Subject`, the `cleanSubject` method must invoke the
`LoginContext.logout` method.

=== LoginExceptions

If the `LoginContext` instance throws a
`LoginException`, the `ServerAuthModule` must throw a corresponding
`AuthException`. The `LoginException` may be established as the cause of the
`AuthException`.

