Interface ISecurity

This feature provides a client session with the ability to re-authenticate the session, as well as to query permissions assigned to it.

Inherited Members

IFeature.Session

Namespace: PushTechnology.ClientInterface.Client.Features

Assembly: Diffusion.Client.dll

Syntax

public interface ISecurity : IFeature

Remarks

Access control

There are no permissions requirements associated with this feature. The client provides credentials that authenticate the new principal.

Accessing the feature

This feature may be obtained from an ISession as follows:

var security = session.Security;

Added in version 5.0.

Methods

ChangePrincipalAsync(String, ICredentials)

Changes the security principal associated with the session.

Declaration

[Obsolete("Use the new ReauthenticateAsync in preference, whichallows user proposed session properties to be supplied.This method will be removed in a future release.", false)]
Task<bool> ChangePrincipalAsync(string principal, ICredentials credentials)

Parameters

Type	Name	Description
System.String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.

Returns

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

Remarks

If the operation completes successfully, the Task result will be a System.Boolean value. true indicates that the authentication succeeded and the session principal has been changed to the given principal. false indicates that the authentication failed because the given principal was unknown or the given credentials were invalid, the session's principal has not changed.

This method is the same as calling ChangePrincipalAsync(String, ICredentials, CancellationToken) with System.Threading.CancellationToken.None.

Caution

Deprecated since 6.12. Use the new ReauthenticateAsync(String, ICredentials, IReadOnlyDictionary<String, String>) in preference, which allows user proposed session properties to be supplied. This method will be removed in a future release.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.

ChangePrincipalAsync(String, ICredentials, CancellationToken)

Changes the security principal associated with the session.

Declaration

[Obsolete("Use the new ReauthenticateAsync in preference, whichallows user proposed session properties to be supplied.This method will be removed in a future release.", false)]
Task<bool> ChangePrincipalAsync(string principal, ICredentials credentials, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	principal	The new principal for the calling session.
ICredentials	credentials	The credentials authenticating the new principal.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

If the operation completes successfully, the Task result will be a System.Boolean value. true indicates that the authentication succeeded and the session principal has been changed to the given principal. false indicates that the authentication failed because the given principal was unknown or the given credentials were invalid, the session's principal has not changed.

Caution

Deprecated since 6.12. Use the new ReauthenticateAsync(String, ICredentials, IReadOnlyDictionary<String, String>) in preference, which allows user proposed session properties to be supplied. This method will be removed in a future release.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.

GetGlobalPermissionsAsync()

Queries the global permissions assigned to the calling session.

Declaration

Task<IReadOnlyCollection<GlobalPermission>> GetGlobalPermissionsAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<GlobalPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's global permissions.

GetGlobalPermissionsAsync(CancellationToken)

Queries the global permissions assigned to the calling session.

Declaration

Task<IReadOnlyCollection<GlobalPermission>> GetGlobalPermissionsAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<GlobalPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's global permissions.

GetPermissionsForPathAsync(String)

Queries the path permissions assigned to the calling session on a given path.

Declaration

Task<IReadOnlyCollection<PathPermission>> GetPermissionsForPathAsync(string path)

Parameters

Type	Name	Description
System.String	path	The topic path to query for permissions.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<PathPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's permissions for path.

Added in 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	The path is null.

GetPermissionsForPathAsync(String, CancellationToken)

Queries the path permissions assigned to the calling session on a given path.

Declaration

Task<IReadOnlyCollection<PathPermission>> GetPermissionsForPathAsync(string path, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	path	The topic path to query for permissions.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

Type	Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<PathPermission>>	The Task representing the current operation.

Remarks

If the operation completes succesfully, the Task result will be a collection containing the session's permissions for path.

Added in 6.5.

Exceptions

Type	Condition
System.ArgumentNullException	The path is null.

ReauthenticateAsync(String, ICredentials, IReadOnlyDictionary<String, String>)

Re-authenticates the session.

Declaration

Task<bool> ReauthenticateAsync(string principal, ICredentials credentials, IReadOnlyDictionary<string, string> properties)

Parameters

Type	Name	Description
System.String	principal	The principal name. This may be the same principal as supplied when the session was originally opened, or it may be an entirely different principal.
ICredentials	credentials	The credentials authenticating the principal.
System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>	properties	A dictionary of the proposed user session properties. The supplied properties will be validated during authentication and may be discarded or changed. If no user properties are required, an empty dictionary should be supplied.

Returns

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

Remarks

This may be used to change the principal for the session, or to re-authenticate the session before it expires.

A session may determine when it is due to expire by querying the value of the EXPIRY_TIME session property using GetSessionPropertiesAsync(). If this property is not present the session will not expire and there is no need to re-authenticate unless the principal in use is to be changed.

If authentication succeeded, the Task will complete successfully with a System.Boolean value of true.

If authentication failed because the principal was unknown or the credentials were invalid, the session will not have been re-authenticated and the Task will complete successfully with a System.Boolean value of false.

This method is the same as calling with System.Threading.CancellationToken.None.

Since 6.12.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.

ReauthenticateAsync(String, ICredentials, IReadOnlyDictionary<String, String>, CancellationToken)

Re-authenticates the session.

Declaration

Task<bool> ReauthenticateAsync(string principal, ICredentials credentials, IReadOnlyDictionary<string, string> properties, CancellationToken cancellationToken)

Parameters

Type	Name	Description
System.String	principal	The principal name. This may be the same principal as supplied when the session was originally opened, or it may be an entirely different principal.
ICredentials	credentials	The credentials authenticating the principal.
System.Collections.Generic.IReadOnlyDictionary<System.String, System.String>	properties	A dictionary of the proposed user session properties. The supplied properties will be validated during authentication and may be discarded or changed. If no user properties are required, an empty dictionary should be supplied.
System.Threading.CancellationToken	cancellationToken	The cancellation token used to cancel the current operation.

Returns

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

Remarks

This may be used to change the principal for the session, or to re-authenticate the session before it expires.

A session may determine when it is due to expire by querying the value of the EXPIRY_TIME session property using GetSessionPropertiesAsync(). If this property is not present the session will not expire and there is no need to re-authenticate unless the principal in use is to be changed.

If authentication succeeded, the Task will complete successfully with a System.Boolean value of true.

If authentication failed because the principal was unknown or the credentials were invalid, the session will not have been re-authenticated and the Task will complete successfully with a System.Boolean value of false.

Since 6.12.

Exceptions

Type	Condition
SessionClosedException	The calling session is closed. Thrown by the returned Task.