Skip to main content
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.