Skip to main content
Verified against OpenWebUI open-webui:0.6.5. If you upgrade the image version in compose.yaml, re-verify env var names against the new version before enabling SSO — variable names can change between releases. Check the OpenWebUI changelog and update this doc accordingly.
mAItion inherits OpenWebUI’s SSO support. Authentication is configured via environment variables in your .env file (copied from .env.openwebui.example). No application code changes are needed. Supported providers: Google OAuth2, Microsoft/Azure AD, GitHub, any generic OIDC provider (Okta, Keycloak, Auth0, etc.), and trusted header SSO.

​
Quick Start (Google OAuth2)

The fastest path to working SSO — under 5 minutes. Step 1 — Create OAuth2 credentials In Google Cloud Console, create an OAuth 2.0 Client ID (application type: Web). Add your authorized redirect URI:
For local development: http://localhost:3000/oauth/google/callback Step 2 — Add vars to .env
Step 3 — Restart
Step 4 — Verify Visit http://localhost:3000. A Continue with Google button should appear on the login page. Step 5 — Harden (optional) Once SSO is confirmed working, you can disable new local account signups:
Do not set ENABLE_LOGIN_FORM=False until you have read the Safe Bootstrap Sequence.

​
Google OAuth2

​
Prerequisites

  • A Google Cloud project with the OAuth consent screen configured
  • Authorized redirect URI: https://your-domain/oauth/google/callback

​
Environment Variables

​
Microsoft / Azure AD

​
Prerequisites

  • An Azure AD app registration with redirect URI: https://your-domain/oauth/microsoft/callback
  • Client secret generated under Certificates & Secrets
  • Tenant ID from the Azure portal (use common for multi-tenant apps)

​
Environment Variables

​
GitHub OAuth

​
Prerequisites

  • A GitHub OAuth App registered at Settings → Developer settings → OAuth Apps
  • Authorization callback URL: https://your-domain/oauth/github/callback

​
Environment Variables

​
Generic OIDC Provider

Works with any OIDC-compliant provider: Okta, Keycloak, Auth0, Authentik, Dex, etc.

​
Prerequisites

  • OIDC discovery endpoint (usually https://your-idp.example.com/.well-known/openid-configuration)
  • Client ID and secret from your IdP
  • Redirect URI registered with your IdP: https://your-domain/oauth/oidc/callback

​
Environment Variables

​
Trusted Header SSO

Security risk — read before enabling.Trusted header SSO authenticates users based on HTTP headers forwarded by a reverse proxy (e.g., nginx, Traefik, Authelia). If port 3000 is reachable directly — bypassing the proxy — any client can forge these headers and authenticate as any user, including admins. This is an account-takeover vector.Only enable trusted header SSO if:
  • Port 3000 is firewalled and not reachable from the public internet
  • Your reverse proxy strips these headers from all inbound public requests
  • Headers are set exclusively by the internal proxy, never by the client
When in doubt, use OAuth2/OIDC instead.

​
Environment Variables

The header names must match exactly what your reverse proxy sets. If the header is missing or misnamed, users will see a generic login error with no indication of the cause. To diagnose: docker compose logs openwebui | grep -i header

​
Safe Bootstrap Sequence

SSO configuration involves variables that can lock you out of your own instance if applied in the wrong order. Follow this sequence:
  1. Enable SSO vars — add your chosen provider’s variables to .env
  2. Keep ENABLE_LOGIN_FORM=True and ENABLE_SIGNUP=True during initial setup
  3. Restart: docker compose up -d openwebui
  4. Verify SSO works — log in successfully via the SSO button at least once
  5. Optionally set ENABLE_SIGNUP=False to block new local-account signups
  6. Only then consider setting ENABLE_LOGIN_FORM=False if you want SSO-only login
Setting ENABLE_LOGIN_FORM=False hides the username/password form in the UI and also blocks the local account sign-up endpoint (POST /api/v1/auths/signup), but does not disable password authentication at the backend level — the /signin endpoint remains accessible. If SSO is misconfigured at this point, the admin can still log in via password if they know the URL. Note: ENABLE_PASSWORD_AUTH (available in newer OpenWebUI versions) fully disables backend password auth; it does not exist in open-webui:0.6.5.Recovery: Set ENABLE_LOGIN_FORM=True in .env and restart:

​
Configuration Reference

All variables verified against open-webui:0.6.5.

​
Troubleshooting

SSO button doesn’t appear Verify the client ID variable is uncommented and set correctly in .env. Then check logs:
Redirect URI mismatch error from IdP Each provider has its own callback path — register the correct one in your IdP:
  • Google: https://your-domain/oauth/google/callback
  • GitHub: https://your-domain/oauth/github/callback
  • Microsoft: https://your-domain/oauth/microsoft/callback
  • Keycloak/Okta/other OIDC: https://your-domain/oauth/oidc/callback
No trailing slashes. For non-standard deployments, set OPENID_REDIRECT_URI explicitly. New users can’t sign in for the first time ENABLE_OAUTH_SIGNUP=True must be set for a user’s first OAuth login — it controls whether new accounts can be created via OAuth. ENABLE_SIGNUP only gates local account creation via the sign-up form and has no effect on OAuth login. SSO silently fails / no error shown Wrong client ID/secret causes a silent failure at the OAuth callback stage. Check:
Locked out — can’t log in Add ENABLE_LOGIN_FORM=True to .env and restart:
Trusted header SSO not working Verify the header name matches exactly (case-sensitive in some proxies). Check what headers OpenWebUI is receiving:

​
Common Gotchas

ENABLE_SIGNUP vs ENABLE_OAUTH_SIGNUP These are two separate variables with different scopes:
  • ENABLE_SIGNUP — controls whether new local accounts can be created via the sign-up form. Default: True
  • ENABLE_OAUTH_SIGNUP — controls whether new accounts can be created via OAuth login. Default: False
For a new user’s first SSO login, only ENABLE_OAUTH_SIGNUP=True is required. ENABLE_SIGNUP has no effect on OAuth — set it to False to block local sign-up form registrations while keeping ENABLE_OAUTH_SIGNUP=True for continued SSO registration. OAUTH_MERGE_ACCOUNTS_BY_EMAIL is a one-way door Once enabled and a user logs in via OAuth, their OAuth identity is linked to any existing local account with the same email. Disabling this variable later does not un-link accounts already merged. Plan accordingly before enabling in production. Disabling the login form ENABLE_LOGIN_FORM=False hides the username/password form in the UI and blocks the local sign-up endpoint (POST /api/v1/auths/signup), but does not disable backend password authentication — the /signin endpoint remains accessible. Only set this after you have confirmed SSO works end-to-end. See Safe Bootstrap Sequence. Reverse proxy and cookie domains If mAItion is behind a reverse proxy, ensure your proxy passes the Host header correctly and that WEBUI_URL in .env matches the public URL. Cookie domain mismatches cause sessions to drop silently after login.