Skip to content

Single Sign-On (SSO) Configuration

Overview

Validaitor supports Single Sign-On (SSO) authentication using Microsoft Entra ID (formerly Azure Active Directory). 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 Microsoft 365 / Azure AD credentials
  • 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

Authentication Workflows

SSO Login Flow

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│              │    │              │    │   Microsoft  │    │              │
│    User      │───▶│  Validaitor  │───▶│   Entra ID   │───▶│  Validaitor  │
│              │    │  Login Page  │    │    Login     │    │  Dashboard   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │                   │
       │  1. Click SSO     │  2. Redirect to   │  3. Authenticate  │
       │     Login         │     Microsoft     │     with Azure    │
       │                   │                   │                   │
       │                   │                   │  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 Microsoft Entra ID
  2. Validaitor creates a new user account using their email and name from Entra ID
  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 Microsoft Entra ID
  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:

  • [ ] Azure AD admin access - Permissions to create App Registrations in Microsoft Entra ID
  • [ ] 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)

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

Azure App Registration 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://app.validaitor.ai/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

  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"

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

Validaitor SSO Configuration

Accessing SSO Settings

  1. Log in to Validaitor as an Organization Admin
  2. Navigate to Organization Settings > Single Sign-On

Configuring SSO

  1. Enter Azure Credentials:
  2. Provider: Microsoft Entra ID
  3. Tenant ID: Your Azure AD tenant ID
  4. Client ID: Application (client) ID from App Registration
  5. Client Secret: Secret value created in Azure

  6. Secret Expiration Date (optional): Set a reminder for secret rotation

  7. Test Connection:

  8. Click Test Connection
  9. Verify the connection is successful

  10. If it fails, verify your Tenant ID, Client ID, and Client Secret

  11. Configure Email Domains:

  12. Add your company email domains (e.g., acme.com, acme.co.uk)
  13. Each domain can only belong to one organization

  14. Users with these email domains can use SSO to access your organization

  15. Select Default Team:

  16. Choose the team that new SSO users will be assigned to
  17. This team should have minimal permissions

  18. Organization admins can assign additional teams after user creation

  19. Enable SSO:

  20. Toggle Enable SSO to activate
  21. 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://app.validaitor.ai/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
Email email or upn claim from Entra ID
First Name given_name claim from Entra ID
Last Name family_name claim from Entra ID
Organization Determined by SSO configuration
Default Team 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 Entra ID identity
  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

Before enabling SSO, verify:

  • [ ] At least one admin has password login enabled (backup access)
  • [ ] Azure App Registration is created
  • [ ] Redirect URI is correctly set to https://app.validaitor.ai/sso/callback
  • [ ] API permissions are granted (openid, profile, email, User.Read)
  • [ ] Admin consent is granted for API permissions
  • [ ] Test Connection succeeds in Validaitor
  • [ ] At least one email domain is configured
  • [ ] Default team is selected

Troubleshooting

Common Errors and Solutions

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 Tenant ID, Client ID, and Client Secret
"AADSTS50011: Reply URL mismatch" Wrong redirect URI in Azure Set redirect URI to https://app.validaitor.ai/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
"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 Tenant ID: Ensure it matches your Azure AD directory
  2. Verify Client ID: Application (client) ID from App Registration
  3. Verify Client Secret: Ensure the secret hasn't expired
  4. Check Network: Ensure Validaitor can reach login.microsoftonline.com

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

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

Session Management

  • SSO tokens are short-lived and refresh automatically
  • Logging out of Validaitor does not log you out of Microsoft
  • For complete logout, users should also sign out of their Microsoft account

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 Azure AD tenants? A: Each organization can only connect to one Azure AD tenant. For multi-tenant access, configure your Azure App Registration as multi-tenant.

Q: How do I remove a user's SSO access? A: Remove the user from the allowed email domains in Azure AD, 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.