AuthManager

This service provides several helper functions commonly useful on managing authentication and authorization at runtime.

FYI

Due to supporting both parts, the name is reduced to common prefix Auth by intention.

Properties

adminRole

This property commonly exposes name of role implicitly granting access to any resource without regards to existing authorization rules in runtime configuration or in local database. The resulting name depends on current runtime environment and runtime configuration.

Methods

asUser()

Signature: async asUser( user, [ createIfMissing ] ): User

This wrapper is meant to assure that provided user is actually an instance of model User existing in local database.

It takes a user's name, ...

const user = await AuthManager.asUser( "john.doe" );

... an object with property name selecting desired user (ignoring any other property in that object) ...

const user = await AuthManager.asUser( { name: "john.doe", foo: "bar" } );

... or the user's existing instance as input.

const user = await AuthManager.asUser( new User( uuid ) );

It retrieves instance of user selected either way. Due to accepting instances of User, it can be safely used multiple times.

Optional boolean parameter createIfMissing must be set true to implicitly create selected user in local database if missing. Otherwise, the method throws an error causing promised result to be rejected.

asRole()

Signature: async asRole( role, [ createIfMissing ] ): Role

This is the counterpart to asUser() for simplifying access on roles. The same semantics apply.

listRolesOfUser()

Signature: async listRolesOfUser( user, [ createIfMissing ], [ uuidsOnly ] ): Roles[]

The method takes a user and qualifies it via asUser() before fetching list of user's associated roles. Argument for optional createIfMissing is forwarded to asUser() and false by default. Argument for optional uuidsOnly must be set explicitly to prevent listed instances of Role to implicitly load their records from database.

listUsersOfRole()

Signature: async listUsersOfRole( role, [ createIfMissing ], [ uuidsOnly ] ): User[]

This method is the counterpart to listRolesOfUser(): it is querying local database for users associated with a given role. Provided role is qualified via asRole() with argument createIfMissing being forwarded.

Optional boolean parameter uuidsOnly must be set to prevent implicit retrieval of either listed user's record from database.

grantRoleToUser()

Signature: async grantRoleToUser( role, user, [ createIfMissing] ): void

This helper is provided for conveniently associating a user with a role. Provided arguments for role and user are qualified with asRole() and asUser(). Optional argument for createIfMissing is forwarded to either method internally.

revokeRoleFromUser()

Signature: async revokeRoleFromUser( role, user, [ createIfMissing] ): void

This helper is provided for conveniently removing any existing association between a user and a role. Provided arguments for role and user are qualified with asRole() and asUser(). Optional argument for createIfMissing is forwarded to either method internally.

createAdminIfMissing()

Signature: async createAdminIfMissing(): void

This method is used during bootstrap to make sure there is always a user associated with configured administrator role preventing any authorization management from locking out all existing users.