Add OIDC to Open WebUI: Setup Guide

Open WebUI natively supports OpenID Connect (OIDC), the industry standard for delegated authentication. By configuring OIDC, you replace password login with centralized single sign-on: your team signs in via Azure AD, Keycloak, Okta, or Google Workspace. Access control is automatic--roles and group membership flow from your identity provider into Open WebUI without manual user provisioning.

This guide walks you through configuring OIDC end-to-end: registering Open WebUI as an OAuth app, setting environment variables, mapping IdP claims to user roles, and fixing the most common breakage points (PKCE errors in Entra ID, email claim mismatches, redirect URI case sensitivity).

What Is OIDC and Why Use It in Open WebUI?

OIDC (OpenID Connect) is a layer on top of OAuth 2.0 that adds authentication. Instead of Open WebUI storing and validating passwords, it trusts a remote identity provider (IdP) to verify users, then accepts a signed token in return.

Why switch from passwords? First, centralized account control: when a team member leaves, deactivate them in your IdP, and they lose access everywhere simultaneously--no need to delete them from Open WebUI separately. Second, audit trails: your IdP logs who logged in when and from where. Third, group-based access: your IdP's organizational structure (departments, teams, roles) becomes Open WebUI's permission model. Fourth, enterprise compliance: many IdPs (Okta, Azure AD, Keycloak) support MFA, conditional access, and audit logs that satisfy governance requirements.

OIDC is particularly valuable for Open WebUI deployments serving teams. The self-hosted AI chatbot is often used internally as a research tool or RAG interface. Adding OIDC means your team accesses it the same way they access Slack or Jira--through a single corporate login. Open WebUI (with 158.5K GitHub stars) was designed for self-hosting, and OIDC integration reflects its maturity in enterprise settings.

Prerequisites: What You Need Before Starting

OIDC support is stable in Open WebUI v0.6 and later. If you are running an older version, upgrade first.

You need an identity provider. The most common choices are:

• Azure AD (Entra ID): Part of Microsoft 365. Free tier supports up to 500 applications. Commonly deployed in enterprises already using Office 365.
• Keycloak: Open-source IdP with 37.8K GitHub stars and Apache 2.0 license. Self-hosted on your infrastructure. No licensing cost; you manage the servers.
• Authentik: Another open-source IdP, lighter-weight than Keycloak. Growing adoption in self-hosted communities.
• Okta: Commercial SaaS IdP. Expensive, but integrates with many legacy systems and has strong compliance certifications.
• Google Workspace: If your team uses Google for email and calendar, Google Workspace provides a simple OIDC provider. Free tier does not include SSO; requires Business Standard or higher.

You also need Open WebUI itself, either running in Docker or as a standalone binary. Make a note of the fully qualified domain where Open WebUI will live--the redirect URI must match exactly (e.g., your-domain.com with the callback path appended).

Step 1: Register Open WebUI as an Application in Your IdP

Every identity provider uses similar terminology, though the UI differs. This step creates a record that says "Open WebUI is an application that users can log into via this IdP."

For Keycloak:

1. Log into the Keycloak admin console (typically on port 8080 of your Keycloak server).
2. Select your realm or create a new one.
3. Navigate to Clients, then "Create."
4. Set Name to "Open WebUI" and Client Type to "OpenID Connect."
5. Enable "Client authentication." Click Save.
6. Under the "Access" tab, set "Root URL" to your Open WebUI domain.
7. Go to "Redirect URIs" and add your domain with the path /oauth/callback appended.
8. Save and copy the Client ID and Client Secret from the "Credentials" tab. You'll need these shortly.

For Azure AD / Entra ID:

1. Go to Azure Portal, then "Azure Active Directory" > "App registrations" > "New registration."
2. Name it "Open WebUI."
3. Under Redirect URI, select "Single-page application (SPA)" (important: not "Web").
4. Set the URI to your Open WebUI domain with /oauth/callback appended.
5. Register the app. Copy the "Application (client) ID"--this is your Client ID.
6. Go to "Certificates & Secrets" > "Client Secrets" > "New client secret." Copy the value immediately; you cannot retrieve it again.
7. Go to "Token configuration." Click "Add optional claim." Select "email" as both ID token and Access token. This ensures the email claim is present in the token (Open WebUI requires it by default).

For Google Workspace:

1. Go to Google Cloud Console and create a new project.
2. Enable the "Google+ API."
3. Go to "Credentials" > "Create OAuth 2.0 Client ID."
4. Choose "Web application."
5. Add your Open WebUI domain with /oauth/callback as an "Authorized redirect URI."
6. Copy the Client ID and Client Secret.

Common mistake: Redirect URI case sensitivity and trailing slashes. Open WebUI expects an exact match. If you register a different case (example: uppercase domain) or add a trailing slash where none exists, login will fail with a cryptic error. Double-check the exact case and format.

Step 2: Configure Open WebUI Environment Variables

Open WebUI reads OIDC settings from environment variables at startup. There are two approaches: the newer OAUTH_CONFIG JSON method (recommended) or individual OAUTH_* variables (legacy, still functional).

Using OAUTH_CONFIG (Recommended for v0.8+):

Create a JSON object and pass it as a single environment variable. Replace placeholder values with your actual IdP credentials:

OAUTH_CONFIG='{"provider_name":"Keycloak","client_id":"open-webui-client","client_secret":"your-secret-here","server_metadata_url":"<your-keycloak-domain>/realms/master/.well-known/openid-configuration","scopes":["openid","profile","email"]}'

Break down each field:

• provider_name: Display name shown on the login button (e.g., "Sign in with Keycloak").
• client_id and client_secret: From your IdP's app registration.
• server_metadata_url: The OIDC discovery URL. This tells Open WebUI how to authenticate and where to find the IdP's public key. Format varies by IdP:
  • Keycloak: your Keycloak domain with /realms/{realm-name}/.well-known/openid-configuration
  • Azure AD: login.microsoftonline.com with your tenant ID and /v2.0/.well-known/openid-configuration
  • Google: accounts.google.com/.well-known/openid-configuration
• scopes: Always include openid and profile. Add email if you want the email claim.

Using Individual OAUTH_ Variables (for v0.6-v0.8 or if JSON is problematic):*

OAUTH_CLIENT_ID=open-webui-client
OAUTH_CLIENT_SECRET=your-secret-here
OAUTH_OPENID_PROVIDER_URL=<your-keycloak-domain>/realms/master
OAUTH_SCOPES=openid,profile,email

Note: The provider URL is the realm root, not the full .well-known path; Open WebUI appends that automatically.

In Docker Compose:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    environment:
      OAUTH_CONFIG: '{"provider_name":"Keycloak","client_id":"open-webui-client","client_secret":"your-secret","server_metadata_url":"<your-keycloak-domain>/realms/master/.well-known/openid-configuration","scopes":["openid","profile","email"]}'
      ENABLE_SIGNUP: "false"
    ports:
      - "8080:8080"

Restart the container after setting env vars. Open WebUI reads them at startup, not dynamically.

Step 3: Configure User Groups and Role Mapping

Once OIDC is working, users can log in with their IdP credentials. However, you often want to restrict access or assign admin roles based on IdP group membership.

Open WebUI has two related settings:

• OAUTH_EMAIL_CLAIM: Which token claim contains the user's email. Default is email. If your IdP uses a different claim name (e.g., mail), set this explicitly.
• OAUTH_ALLOWED_ROLES: A comma-separated list of role/group names from your IdP. Users belonging to these roles can access Open WebUI. Everyone else is denied at login.

Example: Only admins can access Open WebUI

OAUTH_ALLOWED_ROLES=open-webui-admins,developers

In your IdP, create a group called "open-webui-admins" and assign users to it. At login, Open WebUI checks if the user's token includes a roles claim containing "open-webui-admins." If not, login fails.

The format of the roles claim varies by IdP. In Keycloak, add a "role" mapper under the client; in Azure AD, roles are configured in the app registration token settings.

Optional: Auto-promote users to admin based on IdP role

Open WebUI does not natively support this. You must manually promote users to admin in the Open WebUI UI, even if their IdP account is an administrator. This is a limitation; if managing group-to-admin mappings is critical, you may need to run a cron job that calls the Open WebUI API to synchronize roles, or consider a managed Open WebUI provider.

Optional: OAUTH_MERGE_ACCOUNTS_BY_EMAIL

If a user already has an Open WebUI account (created with password login) and then logs in via OIDC with the same email, this setting merges them into one account. Without this, two separate accounts are created, which is confusing. Set it to true if you are migrating from password login to OIDC.

OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true

Step 4: Disable Password Login and Enforce OIDC-Only Access

With OIDC working, you likely want to remove the password login form. Users should see only the OIDC button.

Set these variables:

ENABLE_PASSWORD_AUTH=false
ENABLE_LOGIN_FORM=false

• ENABLE_PASSWORD_AUTH=false: Disables password login on the API level. Users cannot authenticate with username and password.
• ENABLE_LOGIN_FORM=false: Hides the login form on the frontend. Only the OIDC button appears.

Once set, password login is unavailable. If you ever need to recover access (e.g., all IdP accounts are locked out), you can append ?form=true to your Open WebUI login page. This temporarily shows the password form for emergency access.

Security consideration: Keep a single local admin account with a strong password, stored securely offline. In a crisis, you can use the login page with ?form=true appended to access your emergency admin account.

Troubleshooting Common OIDC Setup Errors

OIDC configuration is fragile. Small mismatches break silently. Here are the most frequent issues and fixes.

Error: AADSTS9002325 (Azure AD / Entra ID PKCE error)

Symptom: Azure AD rejects the login request with error code 9002325 or "Proof Key for Public Clients is required."

Cause: Entra ID enforces PKCE (Proof Key for Code Exchange), a security extension. Older Open WebUI versions do not support it.

Solution: Upgrade to Open WebUI v0.9.0 or later, which includes PKCE support. If you cannot upgrade, a workaround is to set your Entra ID app registration to not require PKCE (not recommended for production). Go to "Authentication" > "Advanced settings" > "Treat application as public client" > toggle to "Yes."

Error: Email claim missing, user creation fails

Symptom: User clicks the OIDC login button, authenticates successfully, but then sees "User creation failed" or is not logged in.

Cause: Open WebUI expects the OIDC token to include an email claim. If your IdP does not include it by default, the login chain breaks.

Fix: Check your IdP config:

• Keycloak: Add an email mapper to the client.
• Azure AD: Go to "Token configuration" > "Add optional claim" > select "email" for ID token.
• Google: Google includes email by default; if missing, check that email scope was requested.

Alternatively, if your IdP uses a different claim for the email address, tell Open WebUI:

OAUTH_EMAIL_CLAIM=mail

or

OAUTH_EMAIL_CLAIM=email_address

Error: OIDC login button doesn't appear

Symptom: You set OAUTH_CONFIG, but the login page shows only the password form.

Cause: Container did not restart, or env var was not loaded.

Fix:

1. Restart the Open WebUI container with appropriate Docker or orchestration commands.
2. Wait 5-10 seconds and refresh the login page in your browser.
3. Check container logs for syntax errors. Look for JSON parsing errors in OAUTH_CONFIG.
4. Verify the env var is set in your container configuration.

Error: Redirect URI mismatch

Symptom: IdP rejects the callback with "Redirect URI does not match registration."

Cause: The redirect URI in your request does not exactly match what you registered. Common causes: different scheme (http vs https), different case, trailing slash, or wrong port.

Fix: Check both sides:

• In your IdP app registration, verify the exact redirect URI registered.
• In Open WebUI logs, find the actual redirect URI it is requesting. It should match the IdP registration character-for-character.

Error: "no oauth session found for user"

Symptom: User authenticates successfully, but then Open WebUI returns "no oauth session found for user."

Cause: Open WebUI created a session internally, but then lost track of the JWT token or the session expired. Usually a race condition or session storage corruption.

Fix:

1. Clear browser cookies for your Open WebUI domain and try again.
2. If using Docker, ensure the /data volume is persisted (so session data survives container restarts).
3. Check that Open WebUI has write permissions to its data directory.
4. If the error persists, it may indicate a token format incompatibility; file an issue on GitHub with your IdP type and Open WebUI version.

Error: OAUTH_ALLOWED_ROLES filtering not working

Symptom: You set OAUTH_ALLOWED_ROLES, but users who are not in those roles can still log in.

Cause: The roles claim is missing from the token, or the claim name is wrong.

Fix:

1. Add a role mapper in your IdP to include roles in the ID token.
2. Inspect the token to confirm it contains a roles claim. Use an online JWT decoder to inspect the token from your browser's Network tab.
3. Verify the role names match exactly (case-sensitive).
4. If your IdP uses a different claim name (e.g., groups instead of roles), there may not be a configuration option in Open WebUI; you may need to patch the source or use a different IdP.

Next Steps: Securing and Maintaining OIDC in Open WebUI

OIDC setup is half the battle. Once live, maintain it:

Keep Open WebUI updated. New versions fix OIDC bugs and security issues. Monitor the GitHub releases page.

Monitor SSO failures. When users report login issues, check the container logs. Look for token validation errors, which often indicate an IdP configuration drift (e.g., IdP rotated signing keys).

Rotate secrets periodically. Every 90 days (or per your security policy), regenerate the OIDC client secret in your IdP, update Open WebUI's env var, and restart the container.

Test emergency password access. Monthly, verify that your emergency login access still works with your offline-stored admin password. Do not rely on memory.

Audit access. Periodically review who has access to Open WebUI. Check your IdP's user directory; disable accounts that should not have access.

If managing OIDC configuration yourself becomes a burden--updating containers, coordinating with your IdP team, handling version compatibility--consider a managed Open WebUI hosting provider. Opsily handles OIDC setup, updates, SSL certificates, and scaling, so your team can focus on using Open WebUI rather than maintaining it.

Frequently Asked Questions

Can I use multiple OIDC providers at once?

Not natively. Open WebUI accepts one OIDC_CONFIG at a time. If you need multiple IdPs (e.g., corporate Entra ID and a contractor's Okta), you would need to run multiple Open WebUI instances or patch the source code. A simpler approach: use a single IdP and configure it to federate with other IdPs (many enterprise IdPs support this).

What if my IdP doesn't issue an email claim?

Open WebUI requires an email to identify the user. If your IdP lacks an email field, you can specify an alternative claim using OAUTH_EMAIL_CLAIM (set it to whatever claim contains a unique identifier, e.g., preferred_username or sub). However, this can cause confusion if the identifier is not human-readable.

How do I sync IdP group membership to Open WebUI admin roles?

Open WebUI does not automatically promote IdP admins to Open WebUI admins. You must manually promote users in the Open WebUI UI. For automation, you could write a script that calls the Open WebUI API to sync roles, but this is custom development.

Does OIDC work with Open WebUI behind a reverse proxy?

Yes, but the redirect URI must still be the external URL (what users see in their browser), not the internal container name. For example, if your NGINX proxy is at your domain and forwards internally, set the redirect URI to your external domain with /oauth/callback appended, not the internal address.

Can I still create local users if OIDC is enabled?

Yes. Setting ENABLE_PASSWORD_AUTH=false and ENABLE_LOGIN_FORM=false removes the password login UI, but the API still exists. Users created via OIDC login, or manually added by admins in the UI, coexist. A common pattern: create one local admin account (stored offline), then have everyone else log in via OIDC.

What if OIDC is down or the IdP is unreachable?

Users cannot log in. There is no fallback. This is why keeping an emergency password-protected admin account is critical. You can still access your login page with ?form=true appended to log in as the local admin and investigate.

The Bottom Line

OIDC is the modern standard for adding corporate SSO to any application, including Open WebUI. Setup is straightforward once you understand the redirect URI, token claims, and environment variables.

Most problems stem from IdP misconfiguration (missing email claims, redirect URI case mismatch, PKCE requirements) or stale container images. Troubleshooting is methodical: verify the env vars are loaded, restart the container, inspect the token with a JWT decoder, and check IdP logs.

If your team is already using Keycloak, Azure AD, or Google Workspace, integrating Open WebUI via OIDC takes an hour and requires almost no code. The payoff is immediate: team members log in once, their access is auditable, and offboarding is automatic.

Ready to add OIDC to a self-hosted Open WebUI instance? Start with our managed hosting option at Opsily--we handle the OIDC configuration, SSL, and updates so you can skip the operational overhead.