Interface ISecurity

Namespace

PushTechnology.ClientInterface.Client.Features

Assembly

Diffusion.Client.dll

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

public interface ISecurity : IFeature

Inherited Members

IFeature.Session

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.

[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

principal string

The new principal for the calling session.

credentials ICredentials

The credentials authenticating the new principal.

Returns

Task<bool>

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

SessionClosedException

The calling session is closed. Thrown by the returned Task.

ChangePrincipalAsync(string, ICredentials, CancellationToken)

Changes the security principal associated with the session.

[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

principal string

The new principal for the calling session.

credentials ICredentials

The credentials authenticating the new principal.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<bool>

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

SessionClosedException

The calling session is closed. Thrown by the returned Task.

GetGlobalPermissionsAsync()

Queries the global permissions assigned to the calling session.

Task<IReadOnlyCollection<GlobalPermission>> GetGlobalPermissionsAsync()

Returns

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

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

Parameters

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

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

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

Parameters

path string

The topic path to query for permissions.

Returns

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

ArgumentNullException

The path is null.

GetPermissionsForPathAsync(string, CancellationToken)

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

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

Parameters

path string

The topic path to query for permissions.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

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

ArgumentNullException

The path is null.

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

Re-authenticates the session.

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

Parameters

principal string

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.

credentials ICredentials

The credentials authenticating the principal.

properties IReadOnlyDictionary<string, string>

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

Task<bool>

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 ISession.EXPIRY_TIME 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 ReauthenticateAsync(string, ICredentials, IDictionary<string, string>, CancellationToken) with System.Threading.CancellationToken.None.

Since 6.12.

Exceptions

SessionClosedException

The calling session is closed. Thrown by the returned Task.

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

Re-authenticates the session.

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

Parameters

principal string

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.

credentials ICredentials

The credentials authenticating the principal.

properties IReadOnlyDictionary<string, string>

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.

cancellationToken CancellationToken

The cancellation token used to cancel the current operation.

Returns

Task<bool>

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 ISession.EXPIRY_TIME 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

SessionClosedException

The calling session is closed. Thrown by the returned Task.