Interface IAuthenticationControl

This feature allows a client session to authenticate the credentials of other sessions, and optionally revoke such authentications.

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features.Control.Clients

Assembly: Diffusion.Client.dll

Syntax

public interface IAuthenticationControl : IFeature

Remarks

Sessions are authenticated by a chain of authenticators. A client session can participate in the authentication process by creating an authenticator and registering it with the server.

Each authenticator is registered under a particular authenticator name. For registration to succeed, the server's security configuration must include a matching control-authentication-handler entry for the name, otherwise registration will fail and the authenticator will be closed immediately.

Each client session can register a single authenticator for a given authenticator name.

For each authentication event, the server will use its configuration to determine the authenticator priority order. The server may call authenticators in serial or parallel. The server may stop the authentication process as soon as it has an allow or deny response from an authenticator and all higher priority authenticators have abstained.

For a configured control authenticator, the server will select a single authenticator from those registered for the authenticator name. If no authenticators are currently registered, the server will consult the next configured authenticator in priority order.

Access control

In order to register an authenticator a session needs both REGISTER_HANDLER and AUTHENTICATE permissions.

In order to revoke a session's authentication a session needs both MODIFY_SESSION and AUTHENTICATE permissions.

Accessing the feature

This feature may be obtained from an ISession as follows:

var authenticationControl = session.AuthenticationControl;

Added in version 5.0.

Methods

RevokeAuthenticationAsync(ISessionId)

Revokes a session's authentication.

Declaration

Task<object> RevokeAuthenticationAsync(ISessionId sessionId)

Parameters

Type	Name	Description
ISessionId	sessionId	Identifies the client session to revoke.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This will immediately close the specified client session.

If the identified session was revoked, the Task will complete successfully. The result type is an object rather than void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

This method is the same as calling RevokeAuthenticationAsync(ISessionId, CancellationToken) with System.Threading.CancellationToken.None.

Since 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	The sessionId is null.
System.ArgumentException	The sessionId is an invalid identifier.
NoSuchSessionException	The identified session did not exist or was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have the MODIFY_SESSION and AUTHENTICATE permissions. Thrown by the returned Task.
SessionClosedException	The calling session is closed. Thrown by the returned Task.

RevokeAuthenticationAsync(ISessionId, CancellationToken)

Revokes a session's authentication.

Declaration

Task<object> RevokeAuthenticationAsync(ISessionId sessionId, CancellationToken cancellationToken)

Parameters

Type	Name	Description
ISessionId	sessionId	Identifies the client session to revoke.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Object>	The Task representing the current operation.

Remarks

This will immediately close the specified client session.

If the identified session was revoked, the Task will complete successfully. The result type is an object rather than void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.

Since 6.12.

Exceptions

Type	Condition
System.ArgumentNullException	The sessionId is null.
System.ArgumentException	The sessionId is an invalid identifier.
NoSuchSessionException	The identified session did not exist or was closed before the response was delivered. Thrown by the returned task.
SessionSecurityException	The calling session does not have the MODIFY_SESSION and AUTHENTICATE permissions. Thrown by the returned Task.
SessionClosedException	The calling session is closed. Thrown by the returned Task.

SetAuthenticationHandlerAsync(String, IControlAuthenticator)

Registers an authenticator for client authentication events.

Declaration

Task<IRegistration> SetAuthenticationHandlerAsync(string name, IControlAuthenticator authenticator)

Parameters

Type	Name	Description
System.String	name	The authenticator name which must match an entry in the server's security configuration.
IControlAuthenticator	authenticator	The authenticator.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	The Task representing the current operation.

Remarks

If the task completes successfully, then the authenticator has been registered and the Task result will be IRegistration which can be used to unregister the authenticator.

Exceptions

Type	Condition
System.ArgumentNullException	The name or authenticator is null.
SessionException	The server configuration does not contain a control-authentication-handler element with the given name. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the REGISTER_HANDLER and AUTHENTICATE permissions. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.

SetAuthenticationHandlerAsync(String, IControlAuthenticator, CancellationToken)

Registers an authenticator for client authentication events.

Declaration

Task<IRegistration> SetAuthenticationHandlerAsync(string name, IControlAuthenticator authenticator, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	name	The authenticator name which must match an entry in the server's security configuration.
IControlAuthenticator	authenticator	The authenticator.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<IRegistration>	The Task representing the current operation.

Remarks

If the task completes successfully, then the authenticator has been registered and the Task result will be IRegistration which can be used to unregister the authenticator.

Exceptions

Type	Condition
System.ArgumentNullException	The name or authenticator is null.
SessionException	The server configuration does not contain a control-authentication-handler element with the given name. Thrown by the returned Task.
SessionSecurityException	The calling session does not have the REGISTER_HANDLER and AUTHENTICATE permissions. Thrown by the returned Task.
SessionClosedException	The session is closed. Thrown by the returned Task.