public interface Authenticator
Instances can be registered with the server using the
AuthenticationControl
feature.
The server calls an authentication handler when a client application creates a session, or changes the principal associated with a session, allowing the handler to veto individual requests.
Authentication handlers are configured in precedence order. Authentication
will succeed if a handler responds by calling allow()
or allow(Map)
and handlers with higher
precedence respond by calling abstain()
.
Authentication will fail if a handler responds by calling
deny()
and all higher precedence handlers respond by
calling abstain()
.
If all authentication handlers respond by calling abstain()
, the request will be denied. Once the outcome is known, the server
can choose not to call any remaining authentication handlers.
Modifier and Type | Interface and Description |
---|---|
static interface |
Authenticator.Callback
Single-use callback provided to the
authenticate call. |
Modifier and Type | Method and Description |
---|---|
void |
authenticate(String principal,
Credentials credentials,
Map<String,String> sessionProperties,
Map<String,String> proposedProperties,
Authenticator.Callback callback)
Processes an authentication request.
|
void authenticate(String principal, Credentials credentials, Map<String,String> sessionProperties, Map<String,String> proposedProperties, Authenticator.Callback callback)
This method will be called to authenticate new sessions, and when a
session requests that the session principal is changed (for example,
using changePrincipal
).
For each call to authenticate
, the handler should respond by
calling one of the methods of the provided callback
. The
handler can return immediately and process the authentication request
asynchronously. The authentication will not proceed until a callback
method is called.
The content of the sessionProperties
parameter depends upon
whether the authentication handler is being called on initial
authentication of a session or as a result of a session re-authenticating
using changePrincipal
, as shown
below:
Initial Authentication | changePrincipal | |
---|---|---|
Fixed Properties | A full set of fixed session properties as defined in Session .
|
A full set of fixed session properties as defined in Session .
|
User-defined Properties | None | Existing user-defined properties |
On initial authentication the proposedProperties
parameter will
provide any user-defined properties that the client supplied when opening
the client session, but on re-authentication it will be empty
The handler can choose to call allow()
to accept
the authentication request with default behavior or
allow(Map)
to accept the authentication
request with modifications to the session properties. Alternatively it
can call deny()
to deny the request or
abstain()
to abstain from authentication, in
which case the request will be passed on to the next configured
authentication handler.
If the handler calls allow()
then the resulting
session properties for the session will be as follows:
Initial Authentication | changePrincipal | |
---|---|---|
Fixed Properties | As supplied plus those assigned by the server on connection. | As supplied but with $Principal replaced by the supplied
principal . |
User-defined Properties | None | None |
If the handler calls allow(Map)
then the map
can contain values for any fixed properties that can be changed/supplied
(see below) and/or all user-defined properties to assign to the session.
The user-defined properties can be those proposed by the client or any
set of user-defined properties that the handler chooses.
An authentication handler can set values for any of the following fixed
properties to allow(Map)
:
$Roles
property
The $Roles
property is formatted as a quoted list of strings. To
make the handling of this property value easier there are methods on the
Diffusion
singleton. Using these methods an authenticator can
adjust roles as follows:
final Set<String> roles = Diffusion.stringToRoles(sessionProperties.get(Session.ROLES)); ... changes roles are required ... sessionProperties.put(Session.ROLES, Diffusion.rolesToString(roles)); callback.allow(sessionProperties);
principal
- the name of the proposed principal, or
ANONYMOUS
if none was suppliedcredentials
- authenticating the principal; for example, a passwordsessionProperties
- supplies the currently known session properties
for the client. On initial authentication this will be the known
fixed property values. If the session is re-authenticating using
changePrincipal
, this will be the
full set of fixed property values plus any user-defined properties
from the existing session. Modifications made to this map by the
authenticator are ignored unless the map is passed to the
allow
method.proposedProperties
- provides any user-defined properties proposed
by the client. The handler can choose to pass on these properties
as they are, veto some properties, or add more properties before
passing them to the result. The client can provide arbitrary keys
and values. Supplied properties should be checked and
filtered/constrained to ensure they do not affect the integrity of
the application. Authentication handlers should not blindly pass
proposed properties to the allow
method. Modifications made to this map by the authenticator are
ignored unless the map is passed to the allow
method.callback
- single use callbackCopyright © 2024 DiffusionData Ltd. All Rights Reserved.