Interface IAuthenticator

The authentication handler that processes authentication requests from the server.

Namespace: PushTechnology.ClientInterface.Client.Security.Authentication

Assembly: Diffusion.Client.dll

Syntax

public interface IAuthenticator

Remarks

Instances can be registered with the server using the IAuthenticationControl 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(IReadOnlyDictionary<String, String>) 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.

Methods

Authenticate(String, ICredentials, IReadOnlyDictionary<String, String>, IReadOnlyDictionary<String, String>, IAuthenticatorCallback)

Processes an authentication request.

Declaration

void Authenticate(string principal, ICredentials credentials, IReadOnlyDictionary<string, string> sessionProperties, IReadOnlyDictionary<string, string> proposedProperties, IAuthenticatorCallback callback)

Parameters

Type	Name	Description
System.String	principal	The name of the proposed principal, or System.String.Empty if none was supplied.
ICredentials	credentials	The credentials to authenticate the principal.
System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>	sessionProperties	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 ReauthenticateAsync(String, ICredentials, IReadOnlyDictionary<String, String>), this will be the full set of fixed property values plus any user-defined properties from the existing session. Modifications made to this dictionary by the authenticator are ignored unless the dictionary is passed to the allow Allow(IReadOnlyDictionary<String, String>) method.
System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>	proposedProperties	The user-defined properties proposed by the client. The authenticator may 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 the allow Allow(IReadOnlyDictionary<String, String>) method. Modifications made to this dictionary by the authenticator are ignored unless the dictionary is passed to the allow Allow(IReadOnlyDictionary<String, String>) method.
IAuthenticatorCallback	callback	The single-use callback.

Remarks

This method will be called to authenticate new sessions, and when a session re-authenticates (using ), when the principal for the session can optionally be changed.

For each call to this method, the authenticator should respond by calling one of the methods of the provided IAuthenticatorCallback. 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 using , as shown below:

Initial Authentication:

Fixed Properties User-defined Properties

Fixed Properties	User-defined Properties
A full set of fixed session properties as defined in SessionProperty. `$Principal` will be the same as the supplied principal. `$Roles` will contain the configured default roles for the principal. Properties not listed above are assigned by the server when the session connects, unless they are explicitly assigned values by the authenticator.	None

A full set of fixed session properties as defined in SessionProperty.

$Principal will be the same as the supplied principal.

$Roles will contain the configured default roles for the principal.

Properties not listed above are assigned by the server when the session connects, unless they are explicitly assigned values by the authenticator.

None

ReauthenticateAsync call:

Fixed Properties User-defined Properties

Fixed Properties	User-defined Properties
A full set of fixed session properties as defined in SessionProperty. `$Principal` will be the principal from the previously authenticated session which may differ from the supplied principal. `$Roles` will contain the configured default roles for the new principal.	Existing user-defined properties

A full set of fixed session properties as defined in SessionProperty.

$Principal will be the principal from the previously authenticated session which may differ from the supplied principal.

$Roles will contain the configured default roles for the new principal.

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 the reauthenticate method .

The authenticator can choose to call Allow() to accept the authentication request with default behavior or Allow(IReadOnlyDictionary<String, String>) to accept the authentication request with modifications to the session properties. Alternatively it may 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 authenticator.

If the authenticator calls Allow()allow() then the resulting session properties for the session will be as follows: Initial Authentication:

Fixed Properties	User-defined Properties
As supplied plus those assigned by the server on connection.	None.

ReauthenticateAsync call:

Fixed Properties	User-defined Properties
As supplied but with `$Principal` replaced by the supplied principal.	None.

If the authenticator calls Allow(IReadOnlyDictionary<String, String>) then the dictionary may 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 may be those proposed by the client or they can be 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 Allow(IReadOnlyDictionary<String, String>):

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.

Handling the `$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.