Table of Contents

Class SecurityService

Namespace
The.Security
Assembly
Instagile.dll

Provides a high-level IPrincipal API over the generalised implementations of authentication and authorisation.

public sealed class SecurityService
Inheritance
SecurityService
Inherited Members

Constructors

SecurityService(IAuthentication, IAuthorisation, bool, Func<string, IPrincipal, IScopedContext>, Func<PermissionSetBuilder>, ILogger, RoleCache?, Func<Task>?) 

public SecurityService(IAuthentication authentication, IAuthorisation authorisation, bool requireTenancySpecification, Func<string, IPrincipal, IScopedContext> createScopedContext, Func<PermissionSetBuilder> createBuilder, ILogger logger, RoleCache? roleCache, Func<Task>? resetCache = null)

Parameters

authentication IAuthentication
authorisation IAuthorisation
requireTenancySpecification bool
createScopedContext Func<string, IPrincipal, IScopedContext>
createBuilder Func<PermissionSetBuilder>
logger ILogger
roleCache RoleCache
resetCache Func<Task>

Properties

CurrentPrincipal

The current user session, set by LoginAsync(Credentials?, CancellationToken?) and LogoutAsync(CancellationToken?), which will be used to create contexts.

public IPrincipal CurrentPrincipal { get; }

Property Value

IPrincipal

Methods

CreateAuthenticatedPrincipalAsync(Identity, IEntityContext, Credentials?, CancellationToken?)

Create a security context for an identity that has already been authenticated by some means the framework doesn't implement, subject to standard authorisation.

public Task<IPrincipal> CreateAuthenticatedPrincipalAsync(Identity identity, IEntityContext scopedContext, Credentials? credentials = null, CancellationToken? cancellationToken = null)

Parameters

identity Identity

The identity to authorise. It is taken as given: IAuthentication is not consulted.

scopedContext IEntityContext

A context with unrestricted read access, used to look the identity's roles up.

credentials Credentials

Optional credentials to carry on the principal, for onward use by RPC.

cancellationToken CancellationToken?

Returns

Task<IPrincipal>

Remarks

For sign-in mechanisms where possession of a secret takes the place of credentials, such as a single-use link. Unlike CreateTrustedPrincipal(string, params string[]), the resulting principal holds only the permissions IAuthorisation grants the identity's roles. Does not set CurrentPrincipal.

CreateLocalPrincipal(Credentials?)

Perform authentication, if doing so doesn't require async I/O, and create a security context.

public IPrincipal CreateLocalPrincipal(Credentials? credentials = null)

Parameters

credentials Credentials

Optional login credentials (required by some authenticators).

Returns

IPrincipal

Remarks

If async is required, an unauthenticated principal will be returned - use CreateStandardPrincipalAsync(Credentials?, CancellationToken?) in that case.

CreateLocalPrincipal(Identity, Credentials?)

Perform authentication, if doing so doesn't require async I/O, and create a security context.

public IPrincipal CreateLocalPrincipal(Identity identity, Credentials? credentials = null)

Parameters

identity Identity

A claimed identity to verify.

credentials Credentials

Optional login credentials (required by some authenticators).

Returns

IPrincipal

Remarks

If async is required, an unauthenticated principal will be returned - use CreateStandardPrincipalAsync(Identity, Credentials?, CancellationToken?) in that case.

CreateStandardPrincipalAsync(Credentials?, CancellationToken?)

Perform authentication and create a security context.

public Task<IPrincipal> CreateStandardPrincipalAsync(Credentials? credentials = null, CancellationToken? cancellationToken = null)

Parameters

credentials Credentials

Optional login credentials (required by some authenticators).

cancellationToken CancellationToken?

Returns

Task<IPrincipal>

Remarks

Does not set CurrentPrincipal; this method is for uncached authentication.

CreateStandardPrincipalAsync(Identity, Credentials?, CancellationToken?)

Perform authentication and create a security context.

public Task<IPrincipal> CreateStandardPrincipalAsync(Identity identity, Credentials? credentials = null, CancellationToken? cancellationToken = null)

Parameters

identity Identity

A claimed identity to verify.

credentials Credentials

Optional login credentials (required by some authenticators).

cancellationToken CancellationToken?

Returns

Task<IPrincipal>

Remarks

Does not set CurrentPrincipal; this method is for uncached authentication.

CreateTrustedPrincipal(string, Action<PermissionSetBuilder>, params string[])

Create a security context which is always considered to be authenticated, using the specified authorisation.

public IPrincipal CreateTrustedPrincipal(string username, Action<PermissionSetBuilder> buildPermissions, params string[] roles)

Parameters

username string
buildPermissions Action<PermissionSetBuilder>
roles string[]

Returns

IPrincipal

CreateTrustedPrincipal(string, params string[])

Create a security context which is always considered to be authenticated and authorised.

public IPrincipal CreateTrustedPrincipal(string username, params string[] roles)

Parameters

username string
roles string[]

Returns

IPrincipal

CreateTrustedPrincipal(string, PermissionSet, params string[])

Create a security context which is always considered to be authenticated, using the specified authorisation.

public IPrincipal CreateTrustedPrincipal(string username, PermissionSet permissions, params string[] roles)

Parameters

username string
permissions PermissionSet
roles string[]

Returns

IPrincipal

CreateUntrustedPrincipal(AuthenticationFailure?)

Create a security context which is never considered to be authenticated or authorised.

public IPrincipal CreateUntrustedPrincipal(AuthenticationFailure? error = null)

Parameters

error AuthenticationFailure

Optional reason the principal is unauthenticated (default: NotLoggedIn).

Returns

IPrincipal

GetRolePermissions(Role) 

public PermissionSet GetRolePermissions(Role role)

Parameters

role Role

Returns

PermissionSet

InvalidateAuthorisation(Identity?)

Invalidate cached roles for an identity, or for all identities if none is specified.

public void InvalidateAuthorisation(Identity? identity = null)

Parameters

identity Identity

Remarks

Useful if you know that permissions have changed and need them to be reloaded at next login.

LoginAsync(Credentials?, CancellationToken?)

Attempt to acquire an authenticated principal, replacing the CurrentPrincipal with the result.

public Task<IPrincipal> LoginAsync(Credentials? credentials = null, CancellationToken? cancellationToken = null)

Parameters

credentials Credentials

Optional login credentials (required by some authenticators).

cancellationToken CancellationToken?

Returns

Task<IPrincipal>

LoginAsync(Identity, Credentials?, CancellationToken?)

Attempt to acquire an authenticated principal, replacing the CurrentPrincipal with the result.

public Task<IPrincipal> LoginAsync(Identity identity, Credentials? credentials = null, CancellationToken? cancellationToken = null)

Parameters

identity Identity

A claimed identity to verify.

credentials Credentials

Optional login credentials (required by some authenticators).

cancellationToken CancellationToken?

Returns

Task<IPrincipal>

LogoutAsync(CancellationToken?)

Deauthenticate the the CurrentPrincipal.

public Task LogoutAsync(CancellationToken? cancellationToken = null)

Parameters

cancellationToken CancellationToken?

Returns

Task

LogoutAsync(AuthenticationFailure, CancellationToken?)

Deauthenticate the the CurrentPrincipal.

public Task LogoutAsync(AuthenticationFailure error, CancellationToken? cancellationToken = null)

Parameters

error AuthenticationFailure

Reason for deauthentication.

cancellationToken CancellationToken?

Returns

Task

QuiesceAsync(CancellationToken?)

Wait for any in-progress principal change to settle: its PrincipalChanged handlers and any session cache reset.

public Task QuiesceAsync(CancellationToken? cancellationToken = null)

Parameters

cancellationToken CancellationToken?

Returns

Task

Remarks

Used by tests to ensure a stable state before assertions.

SpecifyTenancy(Tenancy)

Request some level of tenant access for the current principal. RequireTenancySpecification must be set.

public void SpecifyTenancy(Tenancy requestedTenancy)

Parameters

requestedTenancy Tenancy

Remarks

This method cannot increase the access level beyond what the principal is authorised for; passing UniversalTenancy as an argument just means that you'll get all the permissions returned by IAuthorisation for your roles.

Events

PrincipalChanged

Raised when CurrentPrincipal changes.

public event PrincipalChangedEventHandler? PrincipalChanged

Event Type

PrincipalChangedEventHandler