Open Authorizations (OAUTH)

This document contains instructions for configuring Open Authorization (OAUTH) to allow sign-in to RegScale based upon authentication provided by the customer's OAUTH Identity and Access Management (IAM or IdAM) infrastructure.

Purpose

For enterprise customers, identity is managed by a centralized IAM solution that allows users to authenticate to enterprise applications. Having a centralized IAM solution that manages identity allows "Single Sign On" (SSO) where users authenticate once and then a token is passed behind the scenes to applications like RegScale and a separate account is not needed. The benefits of this approach include:

• Central authentication infrastructure where users can be centrally managed based on onboarding and off-boarding processes (with no orphaned accounts as can occur in forms-based authentication)
• Supports Multi-Factor Authentication (MFA) through external authentication providers
• Provides a central monitoring point for authentication for continuous monitoring
• Integrates with existing security tools for authentication including Adaptive Authentication approaches

Configuration

Customer OAUTH Configuration

Customers should ensure that their IAM solution supports OAUTH v2.

1. Set up a new application in the IAM OAUTH profile
2. Generate a client ID for the provisioning identity store
   NOTE: RegScale requests an "id profile email offline access" scope and expects the family_name, given_name, email, roles (optional), and preferred_username in the authentication token
3. Supply generated client ID and "authority" (Uniform Resource Identifier or URI) to the RegScale administrator
   Example: https//dev-123456.okta.com/oath2/default

RegScale OAUTH Configuration

Each tenant within RegScale must be configured to allow authentication using OAUTH. Each tenant can be bound to different OAUTH infrastructure or groups to provide least privilege and segregation of data based on need-to-know groups. In order to configure OAUTH, do the following:

1. Click the username in the top right corner of the application
2. Select "Setup" then select "Integrations" on the left menu
3. Click "Configure" under the "OAUTH" box
4. Client ID - Enter the ID supplied in the step above
5. Authority - Enter the URI supplied in the step above
   1. For Azure AD Commercial users, enter this string https://login.microsoftonline.com/ + the Directory (tenant) ID + /v2.0/.
      1. Example: https://login.microsoftonline.com/e13c0e09-b138-4de9-b123-75cdbd2e6878/v2.0
   2. For Azure AD Government users, you may need to use an alternate link such as https://login.microsoftonline.us/ + the Directory (tenant) ID + /v2.0/ (standard link for US Government). For a complete list of government links, view the Microsoft National Clouds Guide
6. Redirect URI - Enter: "https://{RegScale Domain}/login"
7. Select "Enable OAUTH Single Sign On (SSO)"

Roles

When a user first logs in via OAUTH, their "preferred_username" is compared to locally created accounts. If there is none, a local account will be registered, but without any roles. To set up enterprise identities with roles, create Roles within the enterprise IAM solution and assign users to those roles (see https://regscale.readme.io/docs/users#role-based-access-control for a list of RegScale Roles). Once enabled, RegScale will read the "role" from the authentication token and register the user with that role.

User Login Experience

Once enabled, users should click "SSO Auth" on the login page rather than entering their credentials. If there are multiple tenants, the list of available configuration will be displayed and the user can select which applies to them. The SSO provider challenge will pop up if they haven't logged in or browser cached credentials will be used. The user will be authenticated to RegScale and be redirected to the application home page.