Authorization

LabShare Auth OAuth Client Authorization

As an Authorization Server, LabShare Auth provides layered authorization options for OAuth Clients, Resource Servers (APIs), and Users registered to the system.

User Groups and AD Groups

Each LabShare Auth Tenant can define User Groups and assign/remove Users and/or OAuth2 Clients to each one . When a User Group is assigned to an OAuth Client, access to the OAuth Client will be restricted to the User(s) within the User Group(s) assigned to the Client(s).

How to restrict Client access with User Groups configured via the Auth UI

Initial steps

• Login to the Auth UI
• View/create a Tenant

Adding Users to a Tenant

Users assigned to a LabShare Auth Tenant can be added to the Tenant’s User Groups.

• Go to the Users dashboard via the left navigation menu
• Click the Add User button
• Add Users to the Tenant by email address

Note: New Users will only display an email address in the Users dashboard columns until they login for the first time. This is due to Labshare Auth brokering identities from third parties like Google rather than storing them in its own database.

Creating a User Group

• Go to the User Groups dashboard via the left navigation menu
• Click the Add Group button
• Specify the group name and description. Existing users can be assigned to the group before it is created.

Assigning/removing User Groups to OAuth Clients

• Go to the Applications Dashboard via the left navigation menu
• Select an existing OAuth Client
• In the edit dialog for the OAuth Client, go to the Groups tab
• Assign/remove User Groups to the OAuth Client

How to restrict OAuth Client access by AD Group membership (EXPERIMENTAL)

One or more Active Directory groups can be assigned to OAuth Clients in order to restrict access to members of the AD Group(s). Currently, it is only possible to obtain AD Group information when logging in with specific Identity Providers. For example, the Google OAuth and Azure OIDC IdP does not provide AD Group information.

Assigning AD Groups to SAML2 OAuth Clients (EXPERIMENTAL)

• Go to the Applications Dashboard via the left navigation menu
• Select an existing saml2 application or create a new one
• In the configuration editor, provide the adGroups attribute with a list of one or more AD Groups.

Example

{
  "adGroups": ["My AD Group", "My Second AD Group"]
}

Assigning AD Groups to SPA OAuth Clients

• Go to the Applications Dashboard via the left navigation menu
• Select an existing web or native application or create a new one
• In the configuration editor, fill in the AD Group text box a list of one or more AD Groups separated by commas or newlines.

API Authorization

Registering an API (Resource Server)

• Go to the APIs Dashboard via the left navigation menu
• Click the “Add API” button
• Specify the name and unique identifier (the API’s audience)
• Optionally authorize Clients to access the API. The list of Clients authorized to access the API can be changed after the API is registered.

Resource Server Client Grants

Authorize OAuth Clients to access a specific API (Resource Server).

• Go to the APIs Dashboard via the left navigation menu
• Select an existing API
• In the edit dialog for the API, go to the Clients tab
• Assign/remove Clients to the API

Example Integrations

Node.js

See: @labshare/services-auth

Role Based Access Control

A Role is a grouping of a set of permissions (Resource Scopes). Roles can be assigned to one or more User Groups and each Role can be assigned one or more Permissions. Permissions define granular, API-level access control. For example: facility.users.createFacility. These will be populated in authenticated User's Bearer tokens under the scope claim. The scope claim can then be verified by the service receiving a request.

Use Roles to group low-level Permissions into reusable mappings. Similarly, use User Groups to group Roles into reusable mappings for a set of users.

Identity Assurance Levels

When authorizing, the acr_values query parameter can be used to request additional levels of identity assurance when authenticating the user. Currently, LabShare Auth supports the following ACR values:

The list of supported acr_values can also be viewed at the OIDC Discovery URL for each tenant under the acr_values_supported attribute.

Example

/_api/auth/<tenant>/authorize?acr_values=mod-mf&...

When providing the mod-mf query parameter, the user will be prompted for multi-factor authentication even if the application or identity provider does not already require it. This functionally can be used to provide an additional layer of security for more sensitive sections in an application.

After successfully authenticating with MFA, the user’s id_token and user profile will contain additional claims specifying the type of authentication used (AMR values). See: AMR specifiction.

For example, if the user used both username/password and MFA to authenticate, then the amr claim would be ['pwd', 'mfa'].