Interface IAuthenticationControl

Namespace

PushTechnology.ClientInterface.Client.Features.Control.Clients

Assembly

Diffusion.Client.dll

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

public interface IAuthenticationControl : IFeature

Inherited Members

IFeature.Session

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.

Task<object> RevokeAuthenticationAsync(ISessionId sessionId)

Parameters

sessionId ISessionId

Identifies the client session to revoke.

Returns

Task<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

ArgumentNullException

The sessionId is null.

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.

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

Parameters

sessionId ISessionId

Identifies the client session to revoke.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<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

ArgumentNullException

The sessionId is null.

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.

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

Parameters

name string

The authenticator name which must match an entry in the server's security configuration.

authenticator IControlAuthenticator

The authenticator.

Returns

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

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.

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

Parameters

name string

The authenticator name which must match an entry in the server's security configuration.

authenticator IControlAuthenticator

The authenticator.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

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

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.