Enterprise SSO

Single Sign-On Configuration Guide

Connect your identity provider to VeriSwarm for seamless, secure authentication.

Overview

VeriSwarm Enterprise SSO allows your team to authenticate using your organization's existing identity provider via OpenID Connect (OIDC). Once configured, your users never need a separate VeriSwarm password.

  • Corporate identity — Users sign in with their existing credentials from Entra ID, Google Workspace, Okta, or any OIDC-compatible provider.
  • Email-based discovery — Users enter their email and VeriSwarm automatically detects their SSO provider. No special URLs or bookmarks required.
  • Auto-provisioning — New users from verified domains are automatically added to your workspace with a viewer role.
  • Optional enforcement — Admins can require SSO-only login, disabling password-based authentication for their entire workspace.

Supported Providers

Microsoft Entra ID

formerly Azure AD

Google Workspace

Google Cloud Identity

Okta

Okta Identity Cloud

Custom OIDC

Any OpenID Connect provider

Prerequisites

Before starting SSO configuration, ensure you have:

  • Admin or owner role in your VeriSwarm workspace
  • Identity provider admin access — ability to create application registrations and OAuth clients in your IdP console
  • DNS management access — ability to create TXT records for domain verification

Step-by-Step Setup

Step 1: Navigate to SSO Settings

Go to Account > SSO tab in your VeriSwarm dashboard. The SSO configuration panel is available to workspace admins and owners.

Step 2: Select Your Identity Provider

Choose your identity provider from the dropdown: Entra ID, Google, Okta, or Custom OIDC.

Step 3: Configure OIDC Connection

Follow the instructions for your chosen provider. In all cases, the redirect URI is:

https://api.veriswarm.ai/api/veriswarm/v1/auth/sso/callback
Microsoft Entra ID
  1. In the Azure Portal, go to Entra ID > App registrations > New registration.
  2. Set the redirect URI to https://api.veriswarm.ai/api/veriswarm/v1/auth/sso/callback.
  3. Under Certificates & secrets, create a new client secret and copy it immediately.
  4. Copy the Application (client) ID from the app overview page.
  5. In VeriSwarm, enter your Azure Tenant ID (found in Overview > Directory (tenant) ID).
  6. Enter the Client ID and Client Secret.
Google Workspace
  1. Go to Google Cloud Console > APIs & Services > Credentials.
  2. Create an OAuth 2.0 Client ID with application type set to Web application.
  3. Add https://api.veriswarm.ai/api/veriswarm/v1/auth/sso/callback as an authorized redirect URI.
  4. Copy the Client ID and Client Secret.
  5. In VeriSwarm, enter the Client ID and Client Secret. The issuer URL is pre-configured for Google.
Okta
  1. In the Okta Admin Console, go to Applications > Create App Integration.
  2. Select OIDC - OpenID Connect, then Web Application.
  3. Set the sign-in redirect URI to https://api.veriswarm.ai/api/veriswarm/v1/auth/sso/callback.
  4. Copy the Client ID and Client Secret.
  5. In VeriSwarm, enter your Okta domain (e.g., dev-12345) and the Client ID/Secret.
Custom OIDC
  1. Register VeriSwarm as a client application in your OIDC provider.
  2. Set the redirect URI to https://api.veriswarm.ai/api/veriswarm/v1/auth/sso/callback.
  3. Ensure your provider supports the openid email profile scopes.
  4. In VeriSwarm, enter the full Issuer URL (must serve /.well-known/openid-configuration).
  5. Enter the Client ID and Client Secret.

Step 4: Test Connection

Click Test Connection to verify VeriSwarm can reach your identity provider. This fetches the OIDC discovery document and confirms the client credentials are valid.

Step 5: Add and Verify Your Domain

  1. Click Add Domain and enter your company domain (e.g., company.com).
  2. VeriSwarm generates a DNS TXT record you need to create:
    Host: _veriswarm.company.com
    Value: veriswarm-verify=vs_xxxxxxxxxxxx
  3. Create this TXT record in your DNS provider (Cloudflare, Route 53, GoDaddy, etc.).
  4. Wait for DNS propagation (usually 1–5 minutes, can take up to 48 hours).
  5. Click Verify — VeriSwarm checks for the TXT record and marks the domain as verified.

Step 6: Enable SSO

Toggle Enable SSO to activate. Users with verified domain emails will now see a Sign in with {Provider} button on the login page.

Optional: Enforce SSO Only

  • Toggle Enforce SSO Only to require SSO for all users in your workspace.
  • When enabled, password login returns a 403 with instructions to use SSO instead.
  • Password reset is also blocked for SSO-enforced workspaces.
Warning: Ensure all users can access the identity provider before enabling enforcement. Users without IdP access will be locked out.

How It Works (User Experience)

VeriSwarm uses an email-first login flow for SSO discovery:

  1. User enters their email on the login page and clicks Continue.
  2. VeriSwarm checks if the email domain has an SSO configuration.
  3. If yes, the login page displays a Sign in with {Provider} button.
  4. The user clicks the button and is redirected to their identity provider to authenticate.
  5. After successful authentication, the user is redirected back to VeriSwarm with an active session.
  6. New users from verified domains are auto-provisioned with the viewer role.

Auto-Provisioning

  • New users who sign in via SSO from a verified domain are automatically created in your workspace.
  • They receive the viewer role — they can see the workspace exists but have no data access until promoted.
  • An admin must promote them to member, admin, or owner for full access.
  • Existing users with matching email addresses are automatically linked to SSO — no duplicate accounts are created.

Frequently Asked Questions

Can users still use passwords after SSO is configured?

Yes, unless Enforce SSO Only is enabled. With enforcement off, users can choose either password or SSO login.

What happens if I remove SSO?

Users who previously set a password can still log in with it. SSO-only users (those who never set a password) can use the password reset flow to create one.

Can I configure multiple identity providers?

Currently, one provider per workspace is supported. If you need multi-provider SSO, contact [email protected] to discuss your requirements.

What if DNS verification fails?

DNS propagation can take up to 48 hours. You can check propagation status with:

dig TXT _veriswarm.yourdomain.com
Does VeriSwarm handle MFA?

MFA is handled entirely by your identity provider. VeriSwarm trusts the authentication result from your IdP, including any MFA challenges it enforces.

Security

  • OIDC Authorization Code flow with PKCE (S256) — prevents authorization code interception attacks.
  • Client secrets encrypted at rest using Fernet symmetric encryption.
  • Session state stored in encrypted, HttpOnly, SameSite cookies with 5-minute TTL.
  • JWKS cached with 1-hour TTL, auto-refreshed on key rotation.
  • Domain verification prevents unauthorized SSO configurations for your domain.
  • Rate limiting applied on all SSO endpoints to prevent abuse.

Support

Need help configuring SSO? Our team is available to assist with provider setup, domain verification, and troubleshooting.

Open Support Ticket[email protected]