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 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(IReadOnlyDictionary<String, String>) 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 may choose not to call any remaining authentication handlers.
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 |
---|---|---|
String | principal | The name of the proposed principal, or |
ICredentials | credentials | The credentials to authenticate the principal. |
IReadOnlyDictionary<String, 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 this will be the full set of fixed property values plus any user-defined properties from the existing session. |
IReadOnlyDictionary<String, String> | proposedProperties | The user-defined properties proposed by the client. The handler 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. Authentication handlers should not blindly pass proposed properties. |
IAuthenticatorCallback | callback | The single-use callback. |
Remarks
This method will be called to authenticate new sessions, and when a session requests that the session principal is changed (for example, using ChangePrincipalAsync(String, ICredentials)).
For each call to this method, the handler should respond by calling one of the methods of the provided IAuthenticatorCallback. The handler may 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 ChangePrincipalAsync(String, ICredentials).
Initial Authentication:
Fixed Properties | User-defined Properties |
---|---|
A full set of fixed session properties as defined in SessionProperty.
Properties not listed above are assigned by the server when the session connects, unless they are explicitly assigned values by the authentication handler. | None |
ChangePrincipalAsync
call:
Fixed Properties | User-defined Properties |
---|---|
A full set of fixed session properties as defined in SessionProperty.
| 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(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 authentication handler.
If the handler 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. |
ChangePrincipalAsync
call:
Fixed Properties | User-defined Properties |
---|---|
As supplied but with `$Principal` replaced by the supplied principal. | None. |
If the handler 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 handler chooses.
Permitted fixed property adjustments
An authentication handler can set values for any of the following fixed properties to Allow(IReadOnlyDictionary<String, String>):
An authentication handler can only set values of these fixed properties. Other fixed properties provided by the handler will be ignored. If the handler 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.