Commit d83c355

The Identity Store Interfaces are described in the following sections:

The IdentityStore Interface

The `IdentityStore` interface defines an SPI for interacting with identity stores,

which are directories or databases containing user account information.

An implementation of the `IdentityStore` interface can validate users' credentials,

provide information about the groups they belong to, or both. Most often, an

`IdentityStore` implementation will interact with an external identity store --

an LDAP server, for example -- to perform the actual credential validation and

group lookups, but an `IdentityStore` may also manage user account data itself.

There are two built-in implementations of `IdentityStore`: an LDAP identity store,

and a Database identity store. These identity stores delegate to external stores

that must already exist; the IdentityStore implementations do not provide or

manage the external store. They are configured with the parameters necessary

to communicate with an external store using the following annotations:

link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example]

demonstrates usage of the built-in database identity store.

Multiple implementations of `IdentityStore` may be present; if so, they are invoked

in priority order, based on each identity store's self-declared priority and

type (validation, groups, or both). An implementation of `IdentityStore` must be a

CDI bean to be recognized and deployed at runtime, and is assumed to be normal scoped.

IdentityStores are primarily intended for use by implementations of

`HttpAuthenticationMechanisms`, but this is not a requirement.

They can be used by other types of authentication mechanisms as well, or by containers.

The IdentityStoreHandler Interface

Authentication mechanisms do not interact with `IdentityStore` directly; instead,

they call an `IdentityStoreHandler`. An implementation of the `IdentityStoreHandler`

interface provides a single method, `validate(Credential)`, which, when invoked,

iterates over the available IdentityStores and returns an aggregated result.

An `IdentityStoreHandler` must also be a CDI bean, and is assumed to be normal scoped.

At runtime, an authentication mechanism injects the `IdentityStoreHandler` and

invokes on it. The `IdentityStoreHandler`, in turn, looks up the available IdentityStores

and invokes on them to determine the aggregate result.

There is a built-in `IdentityStoreHandler` that implements a standard algorithm

defined by JSR-375. The JSR-375 specification provides a full description of

the algorithm, but it can be roughly summarized as follows:

An application may also supply its own `IdentityStoreHandler`, which can use any

desired algorithm to select and invoke on IdentityStores, and return an

aggregated (or non-aggregated) result.

IdentityStore Interface Details:

The IdentityStore interface itself has four methods:

Because `getCallerGroups()` is a sensitive operation -- it can return information

about arbitrary users, and does not require that the caller provide the user's

credential or proof of identity -- the caller should have the

`IdentityStorePermission("getGroups")` permission. Enforcement of this check is

incumbent on the implementation of the `getCallerGroups()` method; the built-in

IdentityStores do check for this permission, if a SecurityManager is configured,

and the built-in IdentityStoreHandler invokes the `getCallerGroups()` method in

the context of a `PrivilegedAction` block.

The PasswordHash Interface

Unlike some types of identity stores, for example LDAP directories,

databases can store and retrieve user passwords, but can't verify them natively.

Therefore, the built-in Database identity store must verify user passwords itself.

Most often, this involves generating a hash of the user's password for comparison

with a hash value stored in the database.

In order to provide maximum flexibility and interoperability, the Database identity

store does not implement any specific password hashing algorithms. Instead, it

defines the PasswordHash interface, and expects the application to provide an

implementation of PasswordHash that can verify passwords from the specific store

the application will use. The PasswordHash implementation must be made available

as a dependent scoped bean, and is configured by providing the fully-qualified

name of the desired type as a hashAlgorithm value on the DatabaseIdentityStoreDefinition.

The RememberMeIdentityStore Interface

The `RememberMeIdentityStore` interface represents a special type of identity store.

It is not directly related to the `IdentityStore` interface; that is, it does not

implement or extend it. It does, however, perform a similar, albeit specialized, function.

In some cases, an application wants to "remember" a user's authenticated session

for an extended period. For example, a web site may remember you when you visit,

and prompt for your password only periodically, perhaps once every two weeks,

as long as you don't explicitly log out.

RememberMe works as follows:

The `RememberMeIdentityStore` interface defines the following methods:

An implementation of `RememberMeIdentityStore` must be a CDI bean, and is assumed

to be normal scoped. It is configured by adding a `RememberMe` annotation to an

application's `HttpAuthenticationMechanism`, which indicates that a

`RememberMeIdentityStore` is in use, and provides related configuration parameters.

A container-supplied interceptor then intercepts calls to the `HttpAuthenticationMechanism`,

invokes the `RememberMeIdentityStore` as necessary before and after calls to the

authentication mechanism, and ensures that the user's identity is correctly

set for the session. The JSR-375 specification provides a detailed description

of the required interceptor behavior.

Implementations of `RememberMeIdentityStore` should take care to manage tokens

and user identity information securely. For example, login tokens should not

contain sensitive user information, like credentials or sensitive attributes,

to avoid exposing that information if an attacker were able to gain access

to the token -- even an encrypted token is potentially vulnerable to an

attacker with sufficient time/resources. Similarly, tokens should be

encrypted/signed wherever possible, and sent only over secure channels (HTTPS).

User identity information managed by a `RememberMeIdentityStore` should be stored

as securely as possible (but does not necessarily need to be reliably persisted --

the only impact of a "forgotten" session is that the user will be prompted to

log in again).

The PasswordHash algorithm defines three methods:

Note that, while the interface is oriented toward hashing passwords, it can also

support alternative approaches, such as two-way encryption of stored passwords.

There is a built-in `Pbkdf2PasswordHash` implementation that supports, as it's

name suggests, PBKDF2 password hashing. It supports several parameters that

control the generation of hash values

(key size, iterations, and so on -- see the Javadoc),

and those parameters are encoded into the resulting hash value, so that hashes

can be verified even if the currently configured parameters are different from

the parameters in effect when a stored hash was generated.

While it is necessary to write a custom `PasswordHash` to enable interoperability

with a legacy identity store that stores password hashes in a format other

than the `Pbkdf2PasswordHash` format, developers should consider carefully

whether `Pbkdf2PasswordHash` is sufficient for new identity stores, and avoid

writing a new PasswordHash implementation without a solid understanding of the

cryptographic and other security considerations involved. Some of the

considerations specific to password hashing are:

the `ApplicationConfig.java` file. This example also demonstrates the use of the

`Pbkdf2PasswordHash` interface.