Federated Authentication Support

Open WebUI supports several forms of federated authentication:

OAuth2
1. Google
2. Microsoft
3. Github
4. OIDC
Trusted Header

info

For more information about all environment variables, check out the environment variable docs page. It is highly recommended to check the environment variable page, to get more details about how to set the variable and what values are expected.

tip

Need help with troubleshooting your SSO setup? Check out our troubleshooting guide

danger

Right now, you can only configure one OAUTH provider at a time. You cannot have Microsoft and Google as providers simultaneously.

OAuth Configuration Overview

Environment Variable	Default	Description
`WEBUI_URL`	—	Required. Your public WebUI address, e.g., `http://localhost:8080`.
`ENABLE_OAUTH_PERSISTENT_CONFIG`	`true`	Persist OAuth config to the database; set to `false` for stateless/containerized environments.
`ENABLE_OAUTH_SIGNUP`	`false`	Allows account creation upon OAuth login (separate from `ENABLE_SIGNUP`).
`OAUTH_MERGE_ACCOUNTS_BY_EMAIL`	`false`	Merge OAuth logins based on matching email (⚠️ caution: can be insecure if provider doesn't verify emails).
`OAUTH_UPDATE_PICTURE_ON_LOGIN`	`true`	Update user profile pictures from OAuth provider with each login.
`OAUTH_PICTURE_CLAIM`	`picture`	Field in the claim containing the profile picture. Set to empty string to disable picture updates (users receive default icon).
`WEBUI_AUTH_SIGNOUT_REDIRECT_URL`	empty	Redirect users to this URL after signout. E.g., `https://your-company.com/logout-success`
`OAUTH_SESSION_TOKEN_ENCRYPTION_KEY`	`WEBUI_SECRET_KEY`	Required. A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster.
`ENABLE_OAUTH_ID_TOKEN_COOKIE`	`true`	For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`.

warning

Critical Configuration Notes:

WEBUI_URL Must Be Set First: Configure WEBUI_URL in the Admin Panel before enabling OAuth, as it's used for redirect URIs.
Persistent Config Behavior: When ENABLE_OAUTH_PERSISTENT_CONFIG=true (default), OAuth settings are stored in the database after first launch. To change environment variables after initial setup, either:
- Set ENABLE_OAUTH_PERSISTENT_CONFIG=false to always read from environment variables
- Update settings through the Admin Panel instead of environment variables
Required Variables: Always verify you're using the exact variable names from the environment configuration documentation. Common mistakes include using non-existent variables like OIDC_CONFIG.

Server-Side OAuth Session Management

To solve issues related to large tokens (e.g., with AD FS group claims exceeding cookie size limits) and to enable automatic token refreshing, Open WebUI now supports a robust server-side session management system.

How It Works:

Server-Side Storage: Instead of storing large access_token and id_token values in browser cookies, the entire token payload is now encrypted and stored securely in the Open WebUI database in a new oauth_session table.
Secure Session Cookie: The user's browser is sent a single, small, and secure httponly cookie named oauth_session_id. This cookie acts as an opaque identifier, containing no sensitive information itself.
Automatic Refresh: When a token is required by a downstream service (like a tool or an OpenAI-compatible endpoint), the backend uses the oauth_session_id to retrieve the tokens. If the tokens are expired or close to expiring, the system automatically uses the stored refresh_token to fetch new ones from the provider before forwarding them. This ensures services always receive a valid token and prevents silent failures.
Clean Token Access: This architecture provides a clean and reliable way for internal tools and other services to access user tokens without fragile cookie-scraping.

This system is enabled by default but can be fine-tuned with the environment variables detailed above.

For more information, check out the environment variable docs page.

Google

To configure a Google OAuth client, please refer to Google's documentation on how to create a Google OAuth client for a web application. The allowed redirect URI should include <open-webui>/oauth/google/callback.

The following environment variables are required:

GOOGLE_CLIENT_ID - Google OAuth client ID
GOOGLE_CLIENT_SECRET - Google OAuth client secret
OPENID_PROVIDER_URL - Must be set for logout to work properly. (Usually to https://accounts.google.com/.well-known/openid-configuration)

Microsoft

To configure a Microsoft OAuth client, please refer to Microsoft's documentation on how to create a Microsoft OAuth client for a web application. The allowed redirect URI should include <open-webui>/oauth/microsoft/callback. This value should be used for the MICROSOFT_REDIRECT_URI environment variable.

Support for Microsoft OAuth is currently limited to a single tenant, that is a single Entra organization or personal Microsoft accounts.

The following environment variables are required:

MICROSOFT_CLIENT_ID - Microsoft OAuth client ID
MICROSOFT_CLIENT_SECRET - Microsoft OAuth client secret
MICROSOFT_CLIENT_TENANT_ID - Microsoft tenant ID - use 9188040d-6c67-4c5b-b112-36a304b66dad for personal accounts
MICROSOFT_REDIRECT_URI - The redirect URI configured in your Microsoft OAuth application. This must be set to <open-webui>/oauth/microsoft/callback.
OPENID_PROVIDER_URL - Must be set for logout to work properly.

Github

To configure a Github OAuth Client, please refer to Github's documentation on how to create a OAuth App or Github App for a web application. The allowed redirect URI should include <open-webui>/oauth/github/callback.

The following environment variables are required:

GITHUB_CLIENT_ID - Github OAuth App Client ID
GITHUB_CLIENT_SECRET - Github OAuth App Client Secret

OIDC

Any authentication provider that supports OIDC can be configured. The email claim is required. name and picture claims are used if available. The allowed redirect URI should include <open-webui>/oauth/oidc/callback.

The following environment variables are used:

OAUTH_CLIENT_ID - OIDC client ID
OAUTH_CLIENT_SECRET - OIDC client secret
OPENID_PROVIDER_URL - Required. OIDC well known URL, for example https://accounts.google.com/.well-known/openid-configuration
OAUTH_PROVIDER_NAME - Name of the provider to show on the UI, defaults to SSO
OAUTH_SCOPES - Scopes to request. Defaults to openid email profile
OPENID_REDIRECT_URI - The redirect URI configured in your OIDC application. This must be set to <open-webui>/oauth/oidc/callback.

warning

Common OIDC Mistakes:

Using non-existent environment variables like OIDC_CONFIG or WEBUI_OIDC_CLIENT_ID
Forgetting to set OPENID_PROVIDER_URL (this is mandatory for OIDC)
Using incorrect redirect URI format - must be exactly <your-domain>/oauth/oidc/callback

OAuth Role Management

Any OAuth provider that can be configured to return roles in the access token can be used to manage roles in Open WebUI. To use this feature set ENABLE_OAUTH_ROLE_MANAGEMENT to true. You can configure the following environment variables to match the roles returned by the OAuth provider:

OAUTH_ROLES_CLAIM - The claim that contains the roles. Defaults to roles. Can also be nested, for example user.roles.
OAUTH_ALLOWED_ROLES - A comma-separated list of roles that are allowed to log in (receive open webui role user).
OAUTH_ADMIN_ROLES - A comma-separated list of roles that are allowed to log in as an admin (receive open webui role admin).

info

If changing the role of a logged in user, they will need to log out and log back in to receive the new role.

OAuth Group Management

Any OAuth provider that can be configured to return groups in the access token can be used to manage user groups in Open WebUI upon user login. To enable this synchronization, set ENABLE_OAUTH_GROUP_MANAGEMENT to true.

You can configure the following environment variables:

OAUTH_GROUP_CLAIM - The claim in the ID/access token containing the user's group memberships. Defaults to groups. Can also be nested, for example user.memberOf. Required if ENABLE_OAUTH_GROUP_MANAGEMENT is true.
ENABLE_OAUTH_GROUP_CREATION - If true (and ENABLE_OAUTH_GROUP_MANAGEMENT is also true), Open WebUI will perform Just-in-Time (JIT) group creation. This means it will automatically create groups during OAuth login if they are present in the user's OAuth claims but do not yet exist in the system. Defaults to false. If false, only memberships in existing Open WebUI groups will be managed.

Strict Group Synchronization

When ENABLE_OAUTH_GROUP_MANAGEMENT is set to true, a user's group memberships in Open WebUI are strictly synchronized with the groups received in their OAuth claims upon each login.

Users will be added to Open WebUI groups that match their OAuth claims.
Users will be removed from any Open WebUI groups (including those manually created or assigned within Open WebUI) if those groups are not present in their OAuth claims for that login session.

Ensure all necessary groups are correctly configured in your OAuth provider and included in the group claim (OAUTH_GROUP_CLAIM).

Admin Users

Admin users' group memberships are not automatically updated via OAuth group management.

If a user's groups change in the OAuth provider, they will need to log out of Open WebUI and log back in for the changes to be reflected.

Trusted Header

Open WebUI is able to delegate authentication to an authenticating reverse proxy that passes in the user's details in HTTP headers. There are several example configurations that are provided in this page.

danger

Incorrect configuration can allow users to authenticate as any user on your Open WebUI instance. Make sure to allow only the authenticating proxy access to Open WebUI, such as setting HOST=127.0.0.1 to only listen on the loopback interface.

Generic Configuration

When the WEBUI_AUTH_TRUSTED_EMAIL_HEADER environment variable is set, Open WebUI will use the value of the header specified as the email address of the user, handling automatic registration and login.

For example, setting WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email and passing a HTTP header of X-User-Email: example@example.com would authenticate the request with the email example@example.com.

Optionally, you can also define the WEBUI_AUTH_TRUSTED_NAME_HEADER to determine the name of any user being created using trusted headers. This has no effect if the user already exists. If WEBUI_AUTH_TRUSTED_NAME_HEADER is not set, the email address is used as user name.

Group Management

You can use the WEBUI_AUTH_TRUSTED_GROUPS_HEADER environment variable to synchronize user groups in Open WebUI. Set this variable to the name of the HTTP header that will contain a comma-separated list of group names for the authenticated user.

When a request is authenticated via WEBUI_AUTH_TRUSTED_EMAIL_HEADER, and the trusted groups header is set and present, Open WebUI will update the user's group memberships to match the groups listed in the header.

The header value must be a comma-separated list of group names (e.g., X-User-Groups: admins,editors,users).
If the header is not present or empty, the user's group memberships will not be updated.
User will be unassigned from groups not present in the header.
Group creation via trusted header is not automatic; only existing groups in Open WebUI will be assigned.

Tailscale Serve

Tailscale Serve allows you to share a service within your tailnet, and Tailscale will set the header Tailscale-User-Login with the email address of the requester.

Below is an example serve config with a corresponding Docker Compose file that starts a Tailscale sidecar, exposing Open WebUI to the tailnet with the tag open-webui and hostname open-webui, and can be reachable at https://open-webui.TAILNET_NAME.ts.net. You will need to create an OAuth client with device write permission to pass into the Tailscale container as TS_AUTHKEY.

tailscale/serve.json
{
    "TCP": {
        "443": {
            "HTTPS": true
        }
    },
    "Web": {
        "${TS_CERT_DOMAIN}:443": {
            "Handlers": {
                "/": {
                    "Proxy": "http://open-webui:8080"
                }
            }
        }
    }
}

docker-compose.yaml
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - HOST=127.0.0.1
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
      - WEBUI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
    restart: unless-stopped
  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTH_ONCE=true
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_EXTRA_ARGS=--advertise-tags=tag:open-webui
      - TS_SERVE_CONFIG=/config/serve.json
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_HOSTNAME=open-webui
    volumes:
      - tailscale:/var/lib/tailscale
      - ./tailscale:/config
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  open-webui: {}
  tailscale: {}

warning

If you run Tailscale in the same network context as Open WebUI, then by default users will be able to directly reach out to Open WebUI without going through the Serve proxy. You will need use Tailscale's ACLs to restrict access to only port 443.

Cloudflare Tunnel with Cloudflare Access

Cloudflare Tunnel can be used with Cloudflare Access to protect Open WebUI with SSO. This is barely documented by Cloudflare, but Cf-Access-Authenticated-User-Email is set with the email address of the authenticated user.

Below is an example Docker Compose file that sets up a Cloudflare sidecar. Configuration is done via the dashboard. From the dashboard, get a tunnel token, set the tunnel backend to http://open-webui:8080, and ensure that "Protect with Access" is checked and configured.

docker-compose.yaml
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - HOST=127.0.0.1
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Cf-Access-Authenticated-User-Email
    restart: unless-stopped
  cloudflared:
    image: cloudflare/cloudflared:latest
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    command: tunnel run
    restart: unless-stopped

volumes:
  open-webui: {}

oauth2-proxy

oauth2-proxy is an authenticating reverse proxy that implements social OAuth providers and OIDC support.

Given the large number of potential configurations, below is an example of a potential setup with Google OAuth. Please refer to oauth2-proxy's documentation for detailed setup and any potential security gotchas.

docker-compose.yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - 'HOST=127.0.0.1'
      - 'WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email'
      - 'WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User'
    restart: unless-stopped
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
    environment:
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
      OAUTH2_PROXY_UPSTREAMS: http://open-webui:8080/
      OAUTH2_PROXY_PROVIDER: google
      OAUTH2_PROXY_CLIENT_ID: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_CLIENT_SECRET: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_EMAIL_DOMAINS: REPLACEME_ALLOWED_EMAIL_DOMAINS
      OAUTH2_PROXY_REDIRECT_URL: REPLACEME_OAUTH_CALLBACK_URL
      OAUTH2_PROXY_COOKIE_SECRET: REPLACEME_COOKIE_SECRET
      OAUTH2_PROXY_COOKIE_SECURE: "false"
    restart: unless-stopped
    ports:
      - 4180:4180/tcp

Authentik

To configure a Authentik OAuth client, please refer to documentation on how to create an application and OAuth2/OpenID Provider. The allowed redirect URI should include <open-webui>/oauth/oidc/callback.

While creating provider, please note App-name, Client-ID and Client-Secret and use it for open-webui environment variables:

      - 'ENABLE_OAUTH_SIGNUP=true'
      - 'OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true'
      - 'OAUTH_PROVIDER_NAME=Authentik'
      - 'OPENID_PROVIDER_URL=https://<authentik-url>/application/o/<App-name>/.well-known/openid-configuration'
      - 'OAUTH_CLIENT_ID=<Client-ID>'
      - 'OAUTH_CLIENT_SECRET=<Client-Secret>'
      - 'OAUTH_SCOPES=openid email profile'
      - 'OPENID_REDIRECT_URI=https://<open-webui>/oauth/oidc/callback'

Authelia

Authelia can be configured to return a header for use with trusted header authentication. Documentation is available here.

No example configs are provided due to the complexity of deploying Authelia.

OAuth Configuration Overview​

Server-Side OAuth Session Management​

Google​

Microsoft​

Github​

OIDC​

OAuth Role Management​

OAuth Group Management​

Trusted Header​

Generic Configuration​

Group Management​

Tailscale Serve​

Cloudflare Tunnel with Cloudflare Access​

oauth2-proxy​

Authentik​

Authelia​

OAuth Configuration Overview

Server-Side OAuth Session Management

Google

Microsoft

Github

OIDC

OAuth Role Management

OAuth Group Management

Trusted Header

Generic Configuration

Group Management

Tailscale Serve

Cloudflare Tunnel with Cloudflare Access

oauth2-proxy

Authentik

Authelia