Authentication Setup¶

This page covers how administrators configure the sign-in options for the VirtualSutra AI console via environment variables. End users sign in via the method their administrator has set up; see Authentication for the user-facing guide.

Note: There is also a self-service Settings > Identity > SSO Provider page (see SSO Configuration) for preparing and validating an OIDC configuration, but it doesn't yet enable sign-in on its own; the environment variables below are still required.

How auth mode is selected¶

The console automatically selects the auth mode based on environment variables set on the ui container:

The built-in admin account exists beside OAuth on every self-hosted deployment (not on SaaS).

OAuth / Single Sign-On¶

Required environment variables (all modes)¶

Google Workspace¶

1. Go to console.cloud.google.com → APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (type: Web application)
3. Add Authorized redirect URI: https://vsutra.yourcompany.com/api/auth/callback/google
4. Set env vars on the ui service:

AUTH_GOOGLE_ID=<client-id>
AUTH_GOOGLE_SECRET=<client-secret>

GitHub¶

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
2. Set Authorization callback URL: https://vsutra.yourcompany.com/api/auth/callback/github
3. Set env vars on the ui service:

AUTH_GITHUB_ID=<client-id>
AUTH_GITHUB_SECRET=<client-secret>

Microsoft 365 / Entra ID¶

1. In Azure Portal → Microsoft Entra ID → App registrations → New registration
2. Add redirect URI: https://vsutra.yourcompany.com/api/auth/callback/microsoft-entra-id
3. Create a client secret under Certificates & secrets
4. Set env vars on the ui service:

AUTH_MICROSOFT_ENTRA_ID=<application-client-id>
AUTH_MICROSOFT_ENTRA_SECRET=<client-secret-value>
AUTH_MICROSOFT_ENTRA_TENANT_ID=<directory-tenant-id>

Generic OIDC - Okta, Auth0, Keycloak, etc¶

1. Register a new application in your IdP
2. Set the callback URL to: https://vsutra.yourcompany.com/api/auth/callback/oidc
3. Set env vars on the ui service:

AUTH_OIDC_ISSUER=https://your-tenant.okta.com
AUTH_OIDC_CLIENT_ID=<client-id>
AUTH_OIDC_CLIENT_SECRET=<client-secret>
AUTH_OIDC_NAME=Okta          # Label shown on the sign-in button

Assigning admin role¶

By default all authenticated users get the operator role. Grant admin by listing email addresses:

AUTH_ADMIN_EMAILS=alice@company.com,bob@company.com

This assigns the admin role to that user's console session at sign-in. It is not itself the server-side gate: the API resolves your role from your user record through the signed actor assertion the console mints, and require_admin_actor() checks that resolved role. Changing this list takes effect at the user's next sign-in.

An operator already holds read, write, schedule:write, findings:write, remediation:approve, schedule:read and reports:read - so cancelling a run and deleting a schedule are not admin-only. What admin adds is tenant configuration and identity management: Settings > Admin (Users, Organizations, API Keys, Service Accounts), SSO configuration, custom frameworks/checks/policies, compliance parameters, LLM Configuration (BYOM), notification channels and billing. A viewer holds read alone.

See the Tier & Scope Matrix for the full per-area breakdown.

The built-in admin account¶

Every self-hosted deployment has one local account, admin, created by the API with an initial password (provided by VirtualSutra support on request) that must be changed at the first sign-in - see Authentication. Nothing configures it on the ui container; it needs only SESSION_SECRET, which signs its session cookie:

openssl rand -hex 32   # at least 32 bytes

Verification¶

After configuring, restart the ui container and navigate to your console URL. You should see the provider button(s) on the sign-in page.

To verify the correct provider is shown: