> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO and OAuth Authentication

> Configure Single Sign-On with OAuth providers (Google, Microsoft, GitHub, OIDC)

## 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

<CardGroup cols={2}>
  <Card title="Google" icon="google">
    Google OAuth 2.0 authentication
  </Card>

  <Card title="Microsoft" icon="microsoft">
    Azure AD / Microsoft Entra ID
  </Card>

  <Card title="GitHub" icon="github">
    GitHub OAuth Apps
  </Card>

  <Card title="Generic OIDC" icon="key">
    Okta, Auth0, Keycloak, etc.
  </Card>

  <Card title="Feishu" icon="comment">
    Lark/Feishu authentication
  </Card>

  <Card title="Trusted Headers" icon="shield">
    Proxy-based authentication
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Choose Provider">
    Select your identity provider (Google, Microsoft, etc.)
  </Step>

  <Step title="Register OAuth Application">
    Create OAuth app in your provider's console
  </Step>

  <Step title="Configure Open WebUI">
    Set environment variables with client ID and secret
  </Step>

  <Step title="Enable OAuth Signup">
    Allow user registration via OAuth
  </Step>
</Steps>

## Google OAuth

### Setup

<Steps>
  <Step title="Create OAuth Client">
    1. Go to [Google Cloud Console](https://console.cloud.google.com/)
    2. Navigate to APIs & Services > Credentials
    3. Create OAuth 2.0 Client ID (Web application)
    4. Add authorized redirect URI: `https://your-domain.com/oauth/google/callback`
  </Step>

  <Step title="Configure Open WebUI">
    <CodeGroup>
      ```bash Environment Variables theme={null}
      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
      ```

      ```bash Docker theme={null}
      docker run -d -p 3000:8080 \
        -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
        -e GOOGLE_CLIENT_SECRET=GOCSPX-... \
        -e GOOGLE_REDIRECT_URI=https://your-domain.com/oauth/google/callback \
        -e ENABLE_OAUTH_SIGNUP=True \
        -v open-webui:/app/backend/data \
        ghcr.io/open-webui/open-webui:main
      ```
    </CodeGroup>
  </Step>
</Steps>

*File: backend/open\_webui/config.py:351*

### Configuration Options

```bash theme={null}
GOOGLE_OAUTH_SCOPE="openid email profile"  # Default scopes
OAUTH_TIMEOUT=30000  # Timeout in milliseconds
```

## Microsoft OAuth

### Setup

<Steps>
  <Step title="Register Application">
    1. Go to [Azure Portal](https://portal.azure.com/)
    2. Navigate to Azure Active Directory > App registrations
    3. Create new registration
    4. Add redirect URI: `https://your-domain.com/oauth/microsoft/callback`
    5. Create a client secret under Certificates & secrets
  </Step>

  <Step title="Configure Open WebUI">
    <CodeGroup>
      ```bash Environment Variables theme={null}
      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
      ```

      ```bash Multi-Tenant theme={null}
      MICROSOFT_CLIENT_TENANT_ID=common
      # Allows any Microsoft account or organizational account
      ```

      ```bash Azure Government theme={null}
      MICROSOFT_CLIENT_LOGIN_BASE_URL=https://login.microsoftonline.us
      ```
    </CodeGroup>
  </Step>
</Steps>

*File: backend/open\_webui/config.py:376*

### Advanced Configuration

```bash theme={null}
# 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

<Steps>
  <Step title="Create OAuth App">
    1. Go to GitHub Settings > Developer settings > OAuth Apps
    2. Click "New OAuth App"
    3. Set Homepage URL: `https://your-domain.com`
    4. Set Authorization callback URL: `https://your-domain.com/oauth/github/callback`
  </Step>

  <Step title="Configure Open WebUI">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

*File: backend/open\_webui/config.py:424*

## Generic OIDC Provider

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

### Configuration

<CodeGroup>
  ```bash Okta theme={null}
  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
  ```

  ```bash Auth0 theme={null}
  OAUTH_CLIENT_ID=your-client-id
  OAUTH_CLIENT_SECRET=your-client-secret
  OPENID_PROVIDER_URL=https://your-domain.auth0.com/.well-known/openid-configuration
  OPENID_REDIRECT_URI=https://your-domain.com/oauth/oidc/callback
  OAUTH_PROVIDER_NAME="Auth0"
  ```

  ```bash Keycloak theme={null}
  OAUTH_CLIENT_ID=open-webui
  OAUTH_CLIENT_SECRET=your-client-secret
  OPENID_PROVIDER_URL=https://keycloak.example.com/realms/master/.well-known/openid-configuration
  OPENID_REDIRECT_URI=https://your-domain.com/oauth/oidc/callback
  OAUTH_PROVIDER_NAME="Keycloak"
  ```

  ```bash PKCE Flow (Public Clients) theme={null}
  OAUTH_CLIENT_ID=your-client-id
  OAUTH_CODE_CHALLENGE_METHOD=S256
  OPENID_PROVIDER_URL=https://your-provider/.well-known/openid-configuration
  # No client secret needed for PKCE
  ```
</CodeGroup>

*File: backend/open\_webui/config.py:448*

### Advanced OIDC Options

```bash theme={null}
# 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:

<CodeGroup>
  ```bash Environment Variables theme={null}
  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
  ```

  ```json Example Claims theme={null}
  // JWT token claims
  {
    "sub": "user-id",
    "email": "user@example.com",
    "roles": "user,editor"  // Will be parsed with separator
  }
  ```
</CodeGroup>

*File: backend/open\_webui/config.py:557*

### Group Management

Automatically sync OAuth groups to Open WebUI:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
OAUTH_MERGE_ACCOUNTS_BY_EMAIL=True
```

<Warning>
  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.
</Warning>

*File: backend/open\_webui/config.py:343*

## Session Management

```bash theme={null}
# 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

<Note>
  Open WebUI includes LDAP support for enterprise directory services.

  ```bash theme={null}
  # LDAP library included in requirements.txt
  ldap3==2.9.1
  ```

  *File: backend/requirements.txt:140*
</Note>

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

## Multiple Provider Setup

Enable multiple OAuth providers simultaneously:

<CodeGroup>
  ```bash All Providers theme={null}
  # 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
  ```
</CodeGroup>

Users will see all configured providers on the login page.

*File: backend/open\_webui/utils/oauth.py:939*

## Troubleshooting

<AccordionGroup>
  <Accordion title="Redirect URI Mismatch">
    Error: `redirect_uri_mismatch`

    **Solution**:

    1. Verify redirect URI in OAuth provider matches exactly
    2. Include protocol (https\://)
    3. Check for trailing slashes
    4. Ensure callback path is correct:
       * Google: `/oauth/google/callback`
       * Microsoft: `/oauth/microsoft/callback`
       * GitHub: `/oauth/github/callback`
       * OIDC: `/oauth/oidc/callback`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Logout Not Working">
    Users not properly logged out.

    **Solution**:

    ```bash theme={null}
    ENABLE_OAUTH_ID_TOKEN_COOKIE=True
    OPENID_PROVIDER_URL=https://...  # Must be set
    ```

    The `OPENID_PROVIDER_URL` is required for proper logout functionality.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use HTTPS" icon="lock">
    Always use HTTPS for production OAuth
  </Card>

  <Card title="Secure Secrets" icon="key">
    Store client secrets in environment variables or secrets manager
  </Card>

  <Card title="Validate Emails" icon="envelope">
    Only enable account merging with trusted email verification
  </Card>

  <Card title="Limit Sessions" icon="clock">
    Configure OAUTH\_MAX\_SESSIONS\_PER\_USER
  </Card>

  <Card title="Domain Restrictions" icon="shield">
    Use OAUTH\_ALLOWED\_DOMAINS to restrict access
  </Card>

  <Card title="Audit Logging" icon="list">
    Enable logging for OAuth authentication events
  </Card>
</CardGroup>

## Advanced Features

### Persistent OAuth Config

Enable database-backed OAuth configuration:

```bash theme={null}
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:

```bash theme={null}
ENABLE_OAUTH_EMAIL_FALLBACK=True
```

*File: backend/open\_webui/env.py:589*

### Client Info Encryption

Encrypt OAuth client information:

```bash theme={null}
OAUTH_CLIENT_INFO_ENCRYPTION_KEY=your-32-byte-key
```

*File: backend/open\_webui/env.py:597*

## Testing OAuth Configuration

1. **Test Provider Connection**:
   * Visit login page
   * Click OAuth provider button
   * Verify redirect to provider

2. **Test User Creation**:
   * Complete OAuth flow
   * Check if user is created
   * Verify role/group assignment

3. **Test Claims**:
   * Decode JWT token
   * Verify required claims present
   * Check claim values

4. **Test Logout**:
   * Log in via OAuth
   * Log out
   * Verify session cleared

## References

* OAuth 2.0: [oauth.net](https://oauth.net/2/)
* OpenID Connect: [openid.net/connect](https://openid.net/connect/)
* Google OAuth: [developers.google.com/identity](https://developers.google.com/identity)
* Microsoft Identity: [docs.microsoft.com/azure/active-directory](https://docs.microsoft.com/azure/active-directory)
* GitHub OAuth: [docs.github.com/apps/oauth-apps](https://docs.github.com/apps/oauth-apps)