SSO and OAuth Authentication

Overview

Open WebUI supports OAuth 2.0 and OpenID Connect for Single Sign-On (SSO) with multiple identity providers. Enable seamless authentication with Google, Microsoft, GitHub, Feishu, or any OIDC-compliant provider.

Supported Providers

Google

Google OAuth 2.0 authentication

Microsoft

Azure AD / Microsoft Entra ID

GitHub

GitHub OAuth Apps

Generic OIDC

Okta, Auth0, Keycloak, etc.

Feishu

Lark/Feishu authentication

Trusted Headers

Proxy-based authentication

Quick Start

Choose Provider

Select your identity provider (Google, Microsoft, etc.)

Create OAuth app in your provider’s console

Configure Open WebUI

Set environment variables with client ID and secret

Enable OAuth Signup

Allow user registration via OAuth

Google OAuth

Setup

Create OAuth Client

Go to Google Cloud Console
Navigate to APIs & Services > Credentials
Create OAuth 2.0 Client ID (Web application)
Add authorized redirect URI: https://your-domain.com/oauth/google/callback

Configure Open WebUI

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
GOOGLE_REDIRECT_URI=https://your-domain.com/oauth/google/callback
GOOGLE_OAUTH_SCOPE="openid email profile"

# Enable OAuth features
ENABLE_OAUTH_SIGNUP=True

File: backend/open_webui/config.py:351

Configuration Options

GOOGLE_OAUTH_SCOPE="openid email profile"  # Default scopes
OAUTH_TIMEOUT=30000  # Timeout in milliseconds

Microsoft OAuth

Setup

Go to Azure Portal
Navigate to Azure Active Directory > App registrations
Create new registration
Add redirect URI: https://your-domain.com/oauth/microsoft/callback
Create a client secret under Certificates & secrets

Configure Open WebUI

MICROSOFT_CLIENT_ID=your-application-id
MICROSOFT_CLIENT_SECRET=your-client-secret
MICROSOFT_CLIENT_TENANT_ID=your-tenant-id  # or "common" for multi-tenant
MICROSOFT_REDIRECT_URI=https://your-domain.com/oauth/microsoft/callback
MICROSOFT_OAUTH_SCOPE="openid email profile"

ENABLE_OAUTH_SIGNUP=True

File: backend/open_webui/config.py:376

Advanced Configuration

# Custom photo endpoint
MICROSOFT_CLIENT_PICTURE_URL=https://graph.microsoft.com/v1.0/me/photo/$value

# Azure Government Cloud
MICROSOFT_CLIENT_LOGIN_BASE_URL=https://login.microsoftonline.us

File: backend/open_webui/config.py:402

GitHub OAuth

Setup

Create OAuth App

Go to GitHub Settings > Developer settings > OAuth Apps
Click “New OAuth App”
Set Homepage URL: https://your-domain.com
Set Authorization callback URL: https://your-domain.com/oauth/github/callback

Configure Open WebUI

GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
GITHUB_CLIENT_SCOPE="user:email"
GITHUB_CLIENT_REDIRECT_URI=https://your-domain.com/oauth/github/callback

ENABLE_OAUTH_SIGNUP=True

File: backend/open_webui/config.py:424

Generic OIDC Provider

Connect to any OpenID Connect provider (Okta, Auth0, Keycloak, etc.).

Configuration

OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OPENID_PROVIDER_URL=https://your-domain.okta.com/.well-known/openid-configuration
OPENID_REDIRECT_URI=https://your-domain.com/oauth/oidc/callback
OAUTH_SCOPES="openid email profile"
OAUTH_PROVIDER_NAME="Okta"

ENABLE_OAUTH_SIGNUP=True

File: backend/open_webui/config.py:448

Advanced OIDC Options

# Custom token endpoint authentication
OAUTH_TOKEN_ENDPOINT_AUTH_METHOD=client_secret_post  # or client_secret_basic

# PKCE support
OAUTH_CODE_CHALLENGE_METHOD=S256

# Custom audience claim
OAUTH_AUDIENCE=https://api.example.com

# Request timeout
OAUTH_TIMEOUT=30000

File: backend/open_webui/config.py:484

Role and Group Management

Role Mapping

Map OAuth roles to Open WebUI roles:

ENABLE_OAUTH_ROLE_MANAGEMENT=True
OAUTH_ROLES_CLAIM=roles  # Claim containing roles
OAUTH_ALLOWED_ROLES="user,admin"  # Allowed roles
OAUTH_ADMIN_ROLES="admin,administrator"  # Admin roles
OAUTH_ROLES_SEPARATOR=","  # Role separator in claim

File: backend/open_webui/config.py:557

Group Management

Automatically sync OAuth groups to Open WebUI:

ENABLE_OAUTH_GROUP_MANAGEMENT=True
ENABLE_OAUTH_GROUP_CREATION=True  # Auto-create missing groups
OAUTH_GROUPS_CLAIM=groups  # Claim containing groups
OAUTH_GROUPS_SEPARATOR=";"
OAUTH_GROUP_DEFAULT_SHARE=True  # or "members"

# Block specific groups
OAUTH_BLOCKED_GROUPS='["blocked-group-1", "blocked-group-2"]'

File: backend/open_webui/config.py:563

Domain Restrictions

Restrict access to specific email domains:

OAUTH_ALLOWED_DOMAINS="example.com,company.org"  # Comma-separated
# Or allow all:
OAUTH_ALLOWED_DOMAINS="*"

File: backend/open_webui/config.py:630

Claim Mapping

Customize which JWT claims to use for user attributes:

# Default claim mappings
OAUTH_SUB_CLAIM=sub  # User ID claim
OAUTH_USERNAME_CLAIM=name  # Display name
OAUTH_EMAIL_CLAIM=email  # Email address
OAUTH_PICTURE_CLAIM=picture  # Avatar URL
OAUTH_ROLES_CLAIM=roles  # User roles
OAUTH_GROUPS_CLAIM=groups  # User groups

File: backend/open_webui/config.py:502

Custom Claims Example

# For providers with non-standard claims
OAUTH_SUB_CLAIM=user_id
OAUTH_USERNAME_CLAIM=display_name
OAUTH_EMAIL_CLAIM=mail
OAUTH_PICTURE_CLAIM=avatar_url

User Profile Updates

Control whether OAuth updates user profiles on login:

OAUTH_UPDATE_NAME_ON_LOGIN=True  # Update name from OAuth
OAUTH_UPDATE_EMAIL_ON_LOGIN=False  # Keep existing email
OAUTH_UPDATE_PICTURE_ON_LOGIN=True  # Update avatar

File: backend/open_webui/config.py:639

Account Merging

Merge OAuth accounts with existing email-based accounts:

OAUTH_MERGE_ACCOUNTS_BY_EMAIL=True

Enabling account merging allows OAuth users to take over existing accounts with matching emails. Only enable if you trust your OAuth provider’s email verification.

File: backend/open_webui/config.py:343

Session Management

# Enable ID token cookie for logout
ENABLE_OAUTH_ID_TOKEN_COOKIE=True

# Maximum concurrent sessions per user
OAUTH_MAX_SESSIONS_PER_USER=10

# Enable token exchange
ENABLE_OAUTH_TOKEN_EXCHANGE=False

File: backend/open_webui/env.py:593

LDAP Integration

Open WebUI includes LDAP support for enterprise directory services.

# LDAP library included in requirements.txt
ldap3==2.9.1

File: backend/requirements.txt:140

LDAP configuration is typically handled through custom authentication pipelines or enterprise features.

Multiple Provider Setup

Enable multiple OAuth providers simultaneously:

# Google
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Microsoft
MICROSOFT_CLIENT_ID=...
MICROSOFT_CLIENT_SECRET=...
MICROSOFT_CLIENT_TENANT_ID=...

# GitHub
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

# Generic OIDC
OAUTH_CLIENT_ID=...
OAUTH_CLIENT_SECRET=...
OPENID_PROVIDER_URL=...

# Common settings
ENABLE_OAUTH_SIGNUP=True

Users will see all configured providers on the login page. File: backend/open_webui/utils/oauth.py:939

Troubleshooting

Redirect URI Mismatch

Error: redirect_uri_mismatchSolution:

Verify redirect URI in OAuth provider matches exactly
Include protocol (https://)
Check for trailing slashes
Ensure callback path is correct:
- Google: /oauth/google/callback
- Microsoft: /oauth/microsoft/callback
- GitHub: /oauth/github/callback
- OIDC: /oauth/oidc/callback

User Not Created

OAuth succeeds but no user account created.Solution:

Enable ENABLE_OAUTH_SIGNUP=True
Check domain restrictions in OAUTH_ALLOWED_DOMAINS
Verify required claims are present (email, name)
Review role restrictions in OAUTH_ALLOWED_ROLES
Check logs for detailed error messages

Logout Not Working

Users not properly logged out.Solution:

ENABLE_OAUTH_ID_TOKEN_COOKIE=True
OPENID_PROVIDER_URL=https://...  # Must be set

The OPENID_PROVIDER_URL is required for proper logout functionality.

Role/Group Sync Failing

OAuth roles or groups not syncing.Solution:

Verify claim names match provider (check JWT)
Check separator configuration
Enable group creation if needed
Review OAUTH_BLOCKED_GROUPS configuration
Ensure claims are included in token response

Security Best Practices

Use HTTPS

Always use HTTPS for production OAuth

Secure Secrets

Store client secrets in environment variables or secrets manager

Validate Emails

Only enable account merging with trusted email verification

Limit Sessions

Configure OAUTH_MAX_SESSIONS_PER_USER

Domain Restrictions

Use OAUTH_ALLOWED_DOMAINS to restrict access

Audit Logging

Enable logging for OAuth authentication events

Advanced Features

Persistent OAuth Config

Enable database-backed OAuth configuration:

ENABLE_OAUTH_PERSISTENT_CONFIG=True

This allows OAuth settings to be managed through the admin panel. File: backend/open_webui/config.py:332

Email Fallback

Allow OAuth signup even without email in claims:

ENABLE_OAUTH_EMAIL_FALLBACK=True

File: backend/open_webui/env.py:589

Client Info Encryption

Encrypt OAuth client information:

OAUTH_CLIENT_INFO_ENCRYPTION_KEY=your-32-byte-key

File: backend/open_webui/env.py:597

Testing OAuth Configuration

Test Provider Connection:
- Visit login page
- Click OAuth provider button
- Verify redirect to provider
Test User Creation:
- Complete OAuth flow
- Check if user is created
- Verify role/group assignment
Test Claims:
- Decode JWT token
- Verify required claims present
- Check claim values
Test Logout:
- Log in via OAuth
- Log out
- Verify session cleared

References

OAuth 2.0: oauth.net
OpenID Connect: openid.net/connect
Google OAuth: developers.google.com/identity
Microsoft Identity: docs.microsoft.com/azure/active-directory
GitHub OAuth: docs.github.com/apps/oauth-apps

Getting Started

Core Features

Advanced Features

Integrations

Enterprise

Deployment

Development

Help

​Overview

​Supported Providers

Google

Microsoft

GitHub

Generic OIDC

Feishu

Trusted Headers

​Quick Start

​Google OAuth

​Setup

​Configuration Options

​Microsoft OAuth

​Setup

​Advanced Configuration

​GitHub OAuth

​Setup

​Generic OIDC Provider

​Configuration

​Advanced OIDC Options

​Role and Group Management

​Role Mapping

​Group Management

​Domain Restrictions

​Claim Mapping

​Custom Claims Example

​User Profile Updates

​Account Merging

​Session Management

​LDAP Integration

​Multiple Provider Setup

​Troubleshooting

​Security Best Practices

Use HTTPS

Secure Secrets

Validate Emails

Limit Sessions

Domain Restrictions

Audit Logging

​Advanced Features

​Persistent OAuth Config

​Email Fallback

​Client Info Encryption

​Testing OAuth Configuration

​References

Build docs developers (and LLMs) love

Overview

Supported Providers

Quick Start

Google OAuth

Setup

Configuration Options

Microsoft OAuth

Setup

Advanced Configuration

GitHub OAuth

Setup

Generic OIDC Provider

Configuration

Advanced OIDC Options

Role and Group Management

Role Mapping

Group Management

Domain Restrictions

Claim Mapping

Custom Claims Example

User Profile Updates

Account Merging

Session Management

LDAP Integration

Multiple Provider Setup

Troubleshooting

Security Best Practices

Advanced Features

Persistent OAuth Config

Email Fallback

Client Info Encryption

Testing OAuth Configuration

References