Skip to content

Single Sign-On (SSO) Configuration

Overview

Validaitor supports Single Sign-On (SSO) authentication using Microsoft Entra ID (formerly Azure Active Directory) and Generic OIDC (OpenID Connect) providers such as Keycloak, Okta, Auth0, Google Workspace, and others. SSO allows your organization's users to authenticate using their corporate credentials, streamlining access management and improving security.

Key Features

  • Enterprise Authentication: Users log in with their corporate identity provider credentials
  • Multiple Provider Support: Choose between Microsoft Entra ID or any standards-compliant OIDC provider
  • Automatic User Provisioning: New users are automatically created on first SSO login
  • Domain-Based Access: Configure allowed email domains for your organization
  • Multi-Organization Support: Users can belong to multiple organizations with different SSO configurations
  • Dual Authentication: Users can have both SSO and password authentication enabled

Supported Providers

Provider Type Discovery Notes
Microsoft Entra ID Built-in Automatic via Tenant ID Full Microsoft Graph integration
Keycloak Generic OIDC Automatic via Issuer URL Self-hosted identity provider
Okta Generic OIDC Automatic via Issuer URL Cloud identity provider
Auth0 Generic OIDC Automatic via Issuer URL Cloud identity provider
Google Workspace Generic OIDC Automatic via Issuer URL Use https://accounts.google.com as issuer
Other OIDC providers Generic OIDC Automatic or Manual Any OpenID Connect compliant provider

Authentication Workflows

SSO Login Flow

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│              │    │              │    │   Identity   │    │              │
│    User      │───▶│  Validaitor  │───▶│   Provider   │───▶│  Validaitor  │
│              │    │  Login Page  │    │    Login     │    │  Dashboard   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │                   │
       │  1. Click SSO     │  2. Redirect to   │  3. Authenticate  │
       │     Login         │     IdP           │     with IdP      │
       │                   │                   │                   │
       │                   │                   │  4. Return auth   │
       │                   │                   │     code          │
       │                   │                   │                   │
       │                   │  5. Exchange code │                   │
       │                   │     for tokens    │                   │
       │                   │                   │                   │
       │                   │  6. Create/update │                   │
       │                   │     user account  │                   │
       └───────────────────┴───────────────────┴───────────────────┘

New User Flow

When a user logs in via SSO for the first time:

  1. User is authenticated via the configured identity provider (Entra ID or OIDC)
  2. Validaitor creates a new user account using their email and name from the identity provider
  3. User is added to the organization and assigned to the default team
  4. User receives minimal permissions through the default team
  5. Organization admin can then assign additional team memberships as needed

Existing User Flow

When an existing user (created via invitation) logs in via SSO:

  1. User is authenticated via the identity provider
  2. Validaitor links their existing account to the SSO provider
  3. User retains all existing team memberships and permissions
  4. User can now login via either SSO or password (if password was set)

Prerequisites

Before configuring SSO, ensure you have:

  • [ ] Validaitor Organization Admin access — Member of the Organization Management Team
  • [ ] Backup admin account — At least one admin user that can log in via email/password (critical for recovery if SSO is misconfigured)
  • [ ] Identity provider admin access — For Microsoft Entra ID: Azure AD admin; for generic OIDC: admin access to your identity provider

⚠️ Important: Before enabling SSO, ensure you have a backup admin account with password login enabled. This is your recovery path if SSO becomes misconfigured.

Option A: Microsoft Entra ID Setup

Step 1: Create App Registration

  1. Navigate to Azure Portal
  2. Go to Microsoft Entra ID > App registrations
  3. Click New registration
  4. Configure the registration:
  5. Name: Validaitor SSO (or your preferred name)
  6. Supported account types: Select based on your organization:
    • Single tenant - Only users from your Azure AD tenant
    • Multi-tenant - Users from any Azure AD tenant
  7. Redirect URI:
    • Platform: Web
    • URI: https://platform.validaitor.com/sso/callback
  8. Click Register

Step 2: Configure Token Claims

  1. In your app registration, go to Token configuration
  2. Click Add optional claim
  3. Select ID token type
  4. Add the following claims:
  5. email - User's email address
  6. upn - User Principal Name (for user identification)
  7. When prompted, check Turn on the Microsoft Graph profile permission
  8. Click Add

Step 3: Configure API Permissions

This is an app-level integration (client credentials flow). Add Application permissions—not Delegated permissions. Application permissions allow the app to access Microsoft Graph on behalf of itself, without a signed-in user.

  1. Go to API permissions
  2. Click Add a permission
  3. Select Microsoft Graph > Application permissions (not Delegated)
  4. Add the following permissions:
  5. Application.Read.All - Required for listing enterprise applications (service principals)
  6. Directory.Read.All - Required for directory data
  7. AuditLog.Read.All - Optional, for sign-in logs and usage insights
  8. Click Grant admin consent for [Your Organization]
  9. Verify all permissions show a green checkmark under "Status"

Step 3b: SSO Login Permissions (Optional)

If you use SSO Login (users signing in with Microsoft), add these Delegated permissions in addition to the Application permissions above:

  1. Go to API permissions
  2. Click Add a permission
  3. Select Microsoft Graph > Delegated permissions
  4. Add the following permissions:
  5. openid
  6. profile
  7. email
  8. User.Read
  9. Click Grant admin consent for [Your Organization]
  10. Verify all permissions show a green checkmark under "Status"

⚠️ Important: If you reconfigure or recreate the app registration, you must re-add all permissions and grant admin consent again. Without Application permissions, SaaS Discovery sync will fail with "Insufficient privileges to complete the operation."

Step 4: Create Client Secret

  1. Go to Certificates & secrets
  2. Click New client secret
  3. Configure:
  4. Description: Validaitor SSO Secret
  5. Expires: Select an appropriate duration (recommended: 12-24 months)
  6. Click Add
  7. Copy the secret value immediately - it will only be shown once!

⚠️ Important: Set a calendar reminder to rotate the secret before expiration. Expired secrets will break SSO login.

Step 5: Note Your Configuration Values

Collect the following values from your App Registration:

Value Location
Tenant ID Overview page > Directory (tenant) ID
Client ID Overview page > Application (client) ID
Client Secret Just created in Step 4

Step 6: Configure in Validaitor

  1. Log in to Validaitor as an Organization Admin
  2. Navigate to Organization Settings > Single Sign-On
  3. Select Microsoft Entra ID as the provider
  4. Enter your Azure credentials:
  5. Tenant ID: Your Azure AD tenant ID
  6. Client ID: Application (client) ID from App Registration
  7. Client Secret: Secret value created in Azure (required for initial setup; optional when editing an existing config — only enter if rotating the secret)
  8. Secret Expiration Date (optional): Set a reminder for secret rotation
  9. Click Test Connection to verify the configuration
  10. Continue to Common Configuration below

Option B: Generic OIDC Provider Setup

Generic OIDC support allows you to connect any OpenID Connect compliant identity provider to Validaitor.

Step 1: Create an OIDC Client in Your Identity Provider

The exact steps vary by provider. In general you need to:

  1. Create a new OIDC / OAuth 2.0 client (sometimes called an "application" or "relying party")
  2. Set the client type to "Confidential" (server-side)
  3. Set the allowed grant type to "Authorization Code"
  4. Configure the redirect URI: https://platform.validaitor.com/sso/callback
  5. Ensure the following scopes are available:
  6. openid
  7. profile
  8. email
  9. Note down the Client ID and Client Secret

Provider-Specific Examples

Keycloak 1. Go to the Keycloak Admin Console 2. Select your realm 3. Navigate to **Clients** > **Create client** 4. Set **Client type** to "OpenID Connect" 5. Enter a **Client ID** (e.g., `validaitor`) 6. Enable **Client authentication** (confidential access type) 7. Under **Valid redirect URIs**, add: `https://platform.validaitor.com/sso/callback` 8. Save and go to the **Credentials** tab to copy the client secret 9. Your **Issuer URL** is: `https://your-keycloak.example.com/realms/your-realm`
Okta 1. Go to the Okta Admin Console 2. Navigate to **Applications** > **Create App Integration** 3. Select **OIDC - OpenID Connect** and **Web Application** 4. Set the **Sign-in redirect URI** to: `https://platform.validaitor.com/sso/callback` 5. Under **Assignments**, configure who can access the app 6. Copy the **Client ID** and **Client Secret** 7. Your **Issuer URL** is: `https://your-org.okta.com` (or `https://your-org.okta.com/oauth2/default` for the default authorization server)
Auth0 1. Go to the Auth0 Dashboard 2. Navigate to **Applications** > **Create Application** 3. Select **Regular Web Applications** 4. In **Settings**, add the callback URL: `https://platform.validaitor.com/sso/callback` 5. Copy the **Client ID** and **Client Secret** from the Settings tab 6. Your **Issuer URL** is: `https://your-tenant.auth0.com`

Step 2: Note Your Configuration Values

Collect the following values from your identity provider:

Value Description
Issuer URL The base URL of your OIDC provider (e.g., https://idp.example.com/realms/my-realm)
Client ID The OAuth 2.0 client identifier
Client Secret The OAuth 2.0 client secret

The Issuer URL is used to automatically discover the provider's endpoints via the .well-known/openid-configuration document.

Step 3: Configure in Validaitor

  1. Log in to Validaitor as an Organization Admin
  2. Navigate to Organization Settings > Single Sign-On
  3. Select Generic OIDC as the provider
  4. Enter your OIDC credentials:
  5. Client ID: Your OIDC client identifier
  6. Client Secret: Your OIDC client secret (required for initial setup; optional when editing an existing config — only enter if rotating the secret)
  7. Issuer URL: The base URL of your identity provider
  8. Click Discover Endpoints — Validaitor will automatically fetch:
  9. Authorization endpoint
  10. Token endpoint
  11. UserInfo endpoint
  12. JWKS URI (for token signature verification)
  13. If automatic discovery fails, you can manually enter the endpoints
  14. Click Test Connection to verify the configuration
  15. Continue to Common Configuration below

Manual Endpoint Configuration

If your OIDC provider does not support .well-known/openid-configuration discovery, you can manually enter the endpoints:

Endpoint Example Description
Authorization Endpoint https://idp.example.com/authorize Where users are redirected to log in
Token Endpoint https://idp.example.com/oauth/token Where authorization codes are exchanged for tokens
UserInfo Endpoint https://idp.example.com/userinfo Where user profile information is fetched
JWKS URI https://idp.example.com/.well-known/jwks.json URI for fetching the JSON Web Key Set used to verify JWT signatures

Note: Validaitor performs JWT signature verification only when a JWKS URI is provided. If omitted, tokens cannot be signature-verified and the fallback uses unverified decoding. When automatic discovery is unavailable, always supply the JWKS URI to ensure token integrity.

Common Configuration

After connecting your identity provider (Entra ID or OIDC), complete the following steps:

Configure Email Domains

  1. Add your company email domains (e.g., acme.com, acme.co.uk)
  2. Each domain can only belong to one organization
  3. Users with these email domains can use SSO to access your organization

Select Default Team

  1. Choose the team that new SSO users will be assigned to
  2. This team should have minimal permissions
  3. Organization admins can assign additional teams after user creation

Enable SSO

  1. Toggle Enable SSO to activate
  2. Click Save

Multi-Organization Access

How Multi-Organization Login Works

Users can belong to multiple Validaitor organizations, each with their own SSO configuration:

  • When logging in, users may need to select which organization to access
  • Each organization maintains separate permissions and team memberships
  • SSO sessions are organization-specific

Direct Organization Login

To bypass organization selection, users can use a direct login URL:

https://platform.validaitor.com/auth/login?org=<public-identifier>

The organization's public identifier can be found in Organization Settings.

Cross-Organization User Behavior

Scenario Behavior
User belongs to Org A, logs into Org B via SSO User is added to Org B, assigned to default team
User has password in Org A, uses SSO in Org B Password login still works for Org A
User removed from Org A via SCIM User still has access to Org B

User Provisioning

Automatic User Creation

When SSO is enabled, users are automatically provisioned:

User Info Source (Entra ID) Source (Generic OIDC)
Email email or upn claim email claim from ID token or UserInfo
First Name given_name claim given_name claim
Last Name family_name claim family_name claim
Organization Determined by SSO configuration Determined by SSO configuration
Default Team As configured in SSO settings As configured in SSO settings

Existing User Linking

When an existing Validaitor user logs in via SSO for the first time:

  1. Validaitor matches the user by email address (case-insensitive)
  2. An SSO link is created connecting the Validaitor account to the identity provider
  3. The user retains their existing password (if set) for backup access
  4. Subsequent SSO logins recognize the user via the SSO link

Password vs SSO-Only Users

User Type Can Login with Password Can Login with SSO
Created via invitation (with password) ✅ ✅ (after first SSO login)
Created via SSO (new user) ❌ ✅
SSO user with password later set ✅ ✅

Pre-SSO Checklist

For Microsoft Entra ID

  • [ ] At least one admin has password login enabled (backup access)
  • [ ] Azure App Registration is created
  • [ ] Redirect URI is correctly set to https://platform.validaitor.com/sso/callback
  • [ ] Application permissions are added and admin consent granted (Application.Read.All, Directory.Read.All)
  • [ ] (Optional) Delegated permissions for SSO Login are added and admin consent granted (openid, profile, email, User.Read)
  • [ ] Test Connection succeeds in Validaitor
  • [ ] At least one email domain is configured
  • [ ] Default team is selected

For Generic OIDC

  • [ ] At least one admin has password login enabled (backup access)
  • [ ] OIDC client is created in your identity provider
  • [ ] Client type is set to "Confidential"
  • [ ] Redirect URI is correctly set to https://platform.validaitor.com/sso/callback
  • [ ] Required scopes are enabled: openid, profile, email
  • [ ] Issuer URL is correct and discoverable (or endpoints manually configured)
  • [ ] Test Connection succeeds in Validaitor
  • [ ] At least one email domain is configured
  • [ ] Default team is selected

Troubleshooting

Common Errors and Solutions

Microsoft Entra ID Errors

Error Cause Solution
"AADSTS50011: Reply URL mismatch" Wrong redirect URI in Azure Set redirect URI to https://platform.validaitor.com/sso/callback
"AADSTS7000215: Invalid client secret" Expired or incorrect secret Create new secret in Azure, update in Validaitor
"AADSTS700016: Application not found" Wrong Tenant ID Verify Tenant ID matches your Azure directory
"AADSTS65001: User needs to consent" Admin consent not granted Grant admin consent in Azure Portal > API permissions
"Insufficient privileges" / "Graph API request failed: /servicePrincipals" SaaS Discovery: missing Application permissions Add Application.Read.All and Directory.Read.All as Application permissions, then grant admin consent

Generic OIDC Errors

Error Cause Solution
"Failed to discover OIDC endpoints" Issuer URL is incorrect or unreachable Verify the Issuer URL and ensure the /.well-known/openid-configuration endpoint is accessible
"Token signature verification failed" JWKS mismatch or key rotation Re-run endpoint discovery to refresh the JWKS URI; check provider key configuration
"Invalid redirect URI" Redirect URI not registered Add https://platform.validaitor.com/sso/callback to your OIDC client's allowed redirect URIs
"invalid_client" error on token exchange Wrong client secret or client not confidential Verify client secret; ensure client type is "Confidential" in your IdP
"invalid_scope" error Required scopes not enabled Enable openid, profile, and email scopes for your OIDC client

General Errors

Error Cause Solution
"SSO not available for this domain" Email domain not registered Add the domain in SSO Settings
"Connection test failed" Invalid credentials Verify Client ID and Client Secret
"Please select an organization" User belongs to multiple orgs Select organization or use direct org login URL
User created but no permissions Expected behavior Admin assigns appropriate teams to new user
Locked out of admin account SSO misconfigured Use backup email/password login to recover

Connection Test Failures

If the Test Connection fails:

  1. Verify Client ID: Ensure the Client ID matches your identity provider configuration
  2. Verify Client Secret: Ensure the secret hasn't expired
  3. Verify Provider URL: For Entra ID, check the Tenant ID; for OIDC, check the Issuer URL
  4. Check Network: Ensure Validaitor can reach your identity provider

User Not Being Created

If users aren't being created on SSO login:

  1. Verify the user's email domain is in the allowed domains list
  2. Check that SSO is enabled for the organization
  3. Verify the default team is configured
  4. For OIDC providers: ensure the email claim is included in the ID token or available via the UserInfo endpoint

Password Login Not Working After SSO

If a user can't log in with password after using SSO:

  1. If user was created via SSO, they have no password set (by design)
  2. Admin can send a password reset email to enable password login

Security Considerations

Best Practices

  1. Backup Admin Account: Always maintain at least one admin with password access
  2. Secret Rotation: Set calendar reminders to rotate client secrets before expiration
  3. Domain Verification: Only add email domains you control
  4. Minimal Default Permissions: Configure the default team with minimal permissions
  5. Regular Audits: Periodically review SSO user access and team memberships
  6. HTTPS Only: Ensure your OIDC provider's Issuer URL uses HTTPS in production

Session Management

  • Access tokens are short-lived (15-minute lifetime) and are refreshed automatically on API requests after expiration when a 401 is received
  • Logging out of Validaitor does not log you out of your identity provider
  • For complete logout, users should also sign out of their identity provider

FAQ

Q: Can users have both SSO and password login? A: Yes. Users created via invitation can use both methods. Users created via SSO initially have no password, but an admin can enable password login by sending a password reset email.

Q: What happens if I disable SSO? A: Users who only have SSO access will be unable to log in until SSO is re-enabled or they're given password access.

Q: Can I use SSO with multiple identity providers in one organization? A: Each organization can connect to one identity provider at a time — either Microsoft Entra ID or a Generic OIDC provider. To switch providers, update the SSO configuration in Organization Settings.

Q: Can I switch from Entra ID to a Generic OIDC provider (or vice versa)? A: Yes. Update the provider type and credentials in SSO Settings. Existing users who logged in via the previous provider will be re-linked on their next SSO login (matched by email).

Q: What OIDC scopes are required? A: Validaitor requires openid, profile, and email scopes. The email claim must be available either in the ID token or via the UserInfo endpoint.

Q: How do I remove a user's SSO access? A: Remove the user from your identity provider, remove their email domain from SSO settings, or disable/delete their account in Validaitor.

Q: What permissions do new SSO users get? A: New users are assigned to the default team configured in SSO settings. This team should have minimal permissions; admins can assign additional access as needed.

Q: Does Validaitor verify JWT signatures from OIDC providers? A: Yes. When a JWKS URI is available (discovered automatically or from the provider configuration), Validaitor verifies token signatures. This ensures tokens are authentic and haven't been tampered with.