Interface Authenticator
- All Known Subinterfaces:
AuthenticationControl.ControlAuthenticator
Instances can be registered with the server using the
AuthenticationControl
feature.
The server calls an authenticator when a client application creates a session, or re-authenticates a session, allowing the handler to veto individual requests.
Authenticators are configured in precedence order. Authentication will
succeed if an authenticator responds by calling allow()
or allow(Map)
and authenticators with
higher precedence respond by calling abstain()
.
Authentication will fail if an authenticator responds by calling
deny()
and all higher precedence authenticators
respond by calling abstain()
.
If all authenticators respond by calling abstain()
, the request will be denied. Once the outcome is known, the server
can choose not to call any remaining authenticators.
- Since:
- 6.2
- Author:
- DiffusionData Limited
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Single-use callback provided to theauthenticate
call. -
Method Summary
Modifier and TypeMethodDescriptionvoid
authenticate
(String principal, Credentials credentials, Map<String, String> sessionProperties, Map<String, String> proposedProperties, Authenticator.Callback callback) Processes an authentication request.
-
Method Details
-
authenticate
void authenticate(String principal, Credentials credentials, Map<String, String> sessionProperties, Map<String, String> proposedProperties, Authenticator.Callback callback) Processes an authentication request.This method will be called to authenticate new sessions, and when a session re-authenticates (using
reauthenticate
), when the principal for the session can optionally be changed.For each call to
authenticate
, the authenticator should respond by calling one of the methods of the providedcallback
. The authenticator 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 authenticator is being called on initial authentication of a session or as a result of a session re-authenticating usingreauthenticate
, as shown below:
Initial Authentication Re-authentication Fixed Properties A full set of fixed session properties as defined in Session
.$Principal
will be the same as the suppliedprincipal
.$Roles
will contain the configured default roles for the principal.A full set of fixed session properties as defined in Session
.$Principal
will be the principal from the previously authenticated session which can differ from the suppliedprincipal
.$Roles
will contain the configured default roles for the new principal.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. On re-authentication it will provide any user-defined properties that the client supplied to thereauthenticate
method.The authenticator can choose to call
allow()
to accept the authentication request with default behaviour orallow(Map)
to accept the authentication request with modifications to the session properties. Alternatively it can calldeny()
to deny the request orabstain()
to abstain from authentication, in which case the request will be passed on to the next configured authenticator.If the authenticator calls
allow()
then the resulting session properties for the session will be as follows:Initial Authentication Re-authentication Fixed Properties As supplied plus those assigned by the server on connection. As supplied but with $Principal
replaced by the suppliedprincipal
.User-defined Properties None None If the authenticator 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 authenticator chooses.Permitted fixed property adjustments
An authenticator can set values for any of the following fixed properties to
An authenticator can only set values of these fixed properties. Other fixed properties provided by the authenticator will be ignored. If the authenticator does not set a fixed property, the value will be as supplied, or as assigned by the server.allow(Map)
:Handling the
$Roles
propertyThe
$Roles
property is formatted as a quoted list of strings. To make the handling of this property value easier there are methods on theDiffusion
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);
- Parameters:
principal
- the name of the proposed principal, orANONYMOUS
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 usingreauthenticate
, 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 theallow
method.proposedProperties
- provides any user-defined properties proposed by the client. The authenticator 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. Authenticators should not blindly pass proposed properties to theallow
method. Modifications made to this map by the authenticator are ignored unless the map is passed to theallow
method.callback
- single use callback
-