Guides

Setup Single Sign-On (SSO)

This guide describes how to configure Single Sign-On (SSO) for RegScale using industry-standard authentication protocols. It includes setup instructions for OAuth (including Azure AD and Okta) and SAML configurations. SSO allows users to sign in to RegScale using credentials from a centralized Identity and Access Management (IAM) solution. This enables centralized user management, support for Multi-Factor Authentication (MFA), integration with enterprise authentication monitoring tools, and improved security through adaptive authentication methods. RegScale supports both OAuth 2.0 and SAML for SSO.

Suggest Edits

Overview

RegScale supports Single Sign-On through industry-standard authentication protocols. Two options are available: OAuth 2.0 / OpenID Connect (OIDC) — recommended — and SAML 2.0. Only one method (OAuth or SAML) can be active per tenant at a time.

When a user signs in via SSO for the first time, RegScale automatically creates their account — this is called thin provisioning. The user name, email, first name, and last name are populated from the claims in the SSO token at the moment the account is created, so your identity provider (IdP) must be configured to send all required claims before users begin logging in.

Throughout this guide, <your-regscale-domain> is your RegScale URL. For SaaS customers this follows the pattern https://<customer>.regscale.io; for self-hosted deployments it is the domain configured for your instance.

📘

Required claims — configure all of these in your IdP

RegScale fieldOAuth / OIDC claim (in the ID token)SAML attribute (exact name)
User Namepreferred_username (fallback: upn, email)nameID (email format)
EmailemailEmail
First Namegiven_nameFirstName
Last Namefamily_nameLastName
Roles / groups (optional)roles—

For OAuth/OIDC, RegScale reads these claims from the ID token — a claim that is only available from your IdP's userinfo endpoint will not be seen. See the provider sections below for how to guarantee the claims land in the ID token.

If a user is provisioned while name claims are missing, RegScale creates the account without a first/last name, records a warning in the system log, and emails your tenant's System Administrators with correction steps. Once the IdP configuration is fixed, RegScale automatically backfills the missing names the next time each affected user signs in — no manual cleanup is needed. Names that are already set (including manually entered ones) are never overwritten by SSO claims.

Where SSO is configured in RegScale

  1. Log in to RegScale as an Administrator
  2. Open the profile menu (top-right) and select Setup
  3. In the left sidebar, select Users (Identity and Access Management)
  4. Open the Single Sign-On (SSO) tab
  5. Choose the SSO Type: OAuth or SAML

All configuration described below happens on this tab.

OAuth / OIDC Configuration

Step 1: Register RegScale in your IdP

  1. Register a new application (Single-Page Application / SPA type) in your IdP
  2. Set the sign-in redirect URI to https://<your-regscale-domain>/login
  3. Enable the Authorization Code and Refresh Token grant types
  4. Grant the application the openid, profile, email, and offline_access scopes — RegScale requests exactly these
  5. Confirm the ID token will include all required claims (see the table above and the provider-specific sections below)
  6. Record the Client ID and the Authority URI (the issuer, e.g. https://dev-123456.okta.com/oauth2/default)

Step 2: Configure RegScale

On the Single Sign-On (SSO) tab with SSO Type OAuth selected:

  1. Check Enable OAuth Single Sign On (SSO)?
  2. Enter:
    • Client ID — from your IdP application
    • Authority — your IdP's issuer URI
    • Redirect URI — https://<your-regscale-domain>/login (must exactly match the redirect URI registered in the IdP)
  3. Click Save

Step 3: Test with one user before rolling out

  1. From the RegScale login page, click Single Sign On (SSO). If more than one SSO-enabled tenant exists on the instance, the user selects their tenant first.
  2. Sign in as a net-new test user
  3. In Setup > Users, confirm the new account has its first name, last name, and email populated

If the name fields are blank, do not proceed with bulk onboarding — see Troubleshooting below. Fixing the IdP first avoids provisioning an entire organization of nameless accounts (though RegScale will backfill them on their next login once fixed).

Configure Microsoft Entra ID

  1. Log in to the Azure Portal

  2. Navigate to Microsoft Entra ID > App Registrations

  3. Click + New Registration and configure:

    • Name: RegScale
    • Supported account type: Accounts in this organizational directory only
    • Redirect URI: select Single-page application (SPA) and enter https://<your-regscale-domain>/login

  4. Go to Token Configuration > + Add optional claim, choose token type ID, and add:

    • given_name
    • family_name
    • email
    • preferred_username

    These must be added as ID token claims (not access token) — RegScale reads user names from the ID token when it provisions the account.

  5. Record for RegScale:

    • Client ID — the Application (client) ID
    • Authority — https://login.microsoftonline.com/<directory-tenant-id>/v2.0/

👍

A configured claim is still empty if the underlying directory attribute is blank. Users must have First name and Last name populated on their Entra ID profile.

Entra Role / Group Mapping (optional)

  1. Under your app registration, go to App Roles and create roles whose values follow the RegScale conventions described in Role claims below (e.g. RegScale-TenantAdmin, or a role name matching a RegScale group)
  2. Under Enterprise Applications > RegScale > Users and Groups, assign users/groups to those roles
  3. Entra will emit the assigned values in the roles claim of the ID token

Configure Okta

  1. Log in to the Okta Admin Console
  2. Go to Applications > Create App Integration
  3. Choose OIDC - OpenID Connect and application type Single-Page Application
  4. Configure:
    • Name: RegScale
    • Grant types: Authorization Code and Refresh Token
    • Sign-in redirect URI: https://<your-regscale-domain>/login
    • Assignments: the users/groups who should access RegScale
  5. Record for RegScale:
    • Client ID
    • Authority — your authorization server issuer, e.g. https://dev-123456.okta.com/oauth2/default

Verify the ID token contains ALL required claims

🚧

This is the most common cause of users being provisioned without names.

Okta can issue a "thin" ID token that omits profile claims when an access token is returned in the same flow, publishing them only at the userinfo endpoint. RegScale reads claims from the ID token, so users can be created with blank names even though their Okta profile is complete.

Use a custom authorization server (such as default — the Authority ends in /oauth2/default; this requires the Okta API Access Management feature) and pin the claims to the ID token:

  1. Go to Security > API > Authorization Servers and select the server RegScale uses (e.g. default)

  2. Open the Claims tab and add (or verify) each of the following, with Include in token type = ID Token, Always:

    Claim nameValue (Okta Expression Language)
    given_nameuser.firstName
    family_nameuser.lastName
    emailuser.email
    preferred_usernameuser.login

  3. Open the Token Preview tab, select the RegScale app, grant type Authorization Code, and a test user — confirm all four claims (plus roles, if configured) appear in the ID token preview

Do not point the Authority at the Okta org authorization server (an Authority without /oauth2/<id>) — it does not allow custom ID token claims, so the name claims cannot be guaranteed.

Okta Role / Group Mapping (optional)

  1. On the same authorization server's Claims tab, add a claim named roles, included in the ID Token, Always
  2. Set its value to a groups expression or filter (e.g. value type Groups, filter Starts with RegScale-)
  3. Name your Okta groups using the RegScale conventions described in Role claims below

SAML Configuration

RegScale recommends OAuth but supports SAML where organizationally required. RegScale implements SP-initiated SAML login.

Step 1: Configure your IdP

Create a SAML 2.0 application in your IdP with:

  • Single sign-on URL / ACS URL: https://<your-regscale-domain>/api/AuthSaml/AssertionConsumerService (e.g. https://acme.regscale.io/api/AuthSaml/AssertionConsumerService for a SaaS customer)

  • NameID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress — the NameID value becomes the RegScale user name

  • Attribute statements with these exact, case-sensitive names:

    Attribute nameValue
    FirstNamethe user's first/given name
    LastNamethe user's last/family name
    Emailthe user's email address

🚧

The attribute names must match exactly. Standard SAML attribute URIs (e.g. .../claims/givenname, .../claims/surname) and variants like firstName or first_name are not recognized — users would be provisioned without names. Most IdPs (Okta, Entra ID, Ping, ADFS) let you set the attribute/claim name explicitly; set them to the literal strings FirstName, LastName, and Email.

Step 2: Configure RegScale

On the Single Sign-On (SSO) tab with SSO Type SAML selected:

  1. Check Enable SAML Single Sign On (SSO)?
  2. Paste your configuration into SAML Configuration (JSON):
{
  "IdPMetadata": "https://dev-08722230.okta.com/app/exkdg7dgikWTfuRYX5d7/sso/saml/metadata",
  "Issuer": "Okta_SAML_Example",
  "SignatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  "CertificateValidationMode": "ChainTrust",
  "RevocationMode": "NoCheck"
}
  • IdPMetadata: your IdP's SAML metadata URL
  • Issuer: must match the issuer/entity ID your IdP expects
  1. Click Save

Note for SaaS customers: if two-way encryption is required, contact RegScale to exchange certificates.

Step 3: Test with one user

Same as OAuth — sign in as one net-new user via the Single Sign On (SSO) button and confirm in Setup > Users that first name, last name, and email populated before onboarding in bulk.

Role claims (optional)

When the SSO token includes a roles claim, RegScale applies each value at login:

  • Group membership — a value of RegScale-GroupId:<id> adds the user to the RegScale group with that numeric ID. Values that match a group's migrated role name are also honored.
  • Session roles — role values are attached to the user's RegScale session; a value of Administrator grants administrator rights for that session.
  • Persistent admin provisioning — with Sync Tenant Admin and App Admin from SSO claims enabled on the SSO tab, the claims RegScale-TenantAdmin and RegScale-AppAdmin:<appId> grant the corresponding admin rights durably. The companion option Revoke admin rights when SSO claims are absent removes those rights at login when the IdP stops sending the claim.

🚧

Before enabling revoke-on-absence, ensure a non-SSO break-glass administrator account exists — otherwise a misconfigured IdP could lock every administrator out.

Troubleshooting

Users created without first or last name

Symptom: SSO-provisioned users appear in Setup > Users with a user name and email but blank first/last name. Tenant System Administrators receive an email titled "Action Required: RegScale SSO is not sending user name claims," and the system log records an SSO misconfiguration warning identifying the affected user.

Cause: the token RegScale received at provisioning time did not include name claims:

  • OAuth/OIDC — the ID token is missing given_name / family_name. Most common reasons: the profile scope is not granted; the claims are not configured as ID token claims (Okta thin tokens — see the Okta section; Entra optional claims set on the wrong token type); or the user's directory profile has no name populated.
  • SAML — the assertion's attribute statements are not named exactly FirstName / LastName.

Resolution:

  1. Correct the IdP configuration using the provider steps above
  2. Verify with your IdP's token preview / test tooling that the claims now appear in the ID token (or SAML assertion)
  3. Have affected users sign in again — RegScale backfills their first and last names automatically from the corrected claims on their next SSO login
  4. Alternatively, an administrator can enter names manually in Setup > Users (manually entered names are never overwritten by SSO claims)

SSO login fails or the SSO button does nothing

  • Confirm the Redirect URI in RegScale exactly matches the redirect URI registered in the IdP (scheme, host, and /login path)
  • Confirm the Authority is the issuer URI (for Okta, including the /oauth2/<id> authorization-server segment)
  • Confirm the IdP application grants the openid profile email offline_access scopes and the Authorization Code + Refresh Token grant types
  • Check whether the browser blocked the sign-in popup; RegScale falls back to a full redirect if the popup fails

"This user has been de-activated" on SSO login

The account exists in RegScale but was deactivated by an administrator. Reactivate it in Setup > Users.

Roles or groups not applied at login

  • Confirm the token contains a claim named roles and that it is included in the ID token
  • Confirm the values follow the patterns in Role claims (RegScale-GroupId:<id>, RegScale-TenantAdmin, RegScale-AppAdmin:<appId>, or a matching group role name)
  • For persistent admin rights, confirm Sync Tenant Admin and App Admin from SSO claims is enabled on the SSO tab

Additional Resources

Updated 1 day ago

Did this page help you?