User Authentication - Open WebUI

Overview

Open WebUI provides enterprise-grade authentication with support for multiple authentication methods, SSO providers, and granular permission controls.

Authentication Methods

Email/Password
OAuth/OIDC
LDAP
Trusted Headers

Traditional credential-based authentication:

Secure password hashing with bcrypt
Password validation rules
Account creation and management
Password reset workflows

User Registration

New users can create accounts through the sign-up flow:

Navigate to Sign Up

Access the registration page at /auth/signup

Provide Details

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd",
  "name": "John Doe",
  "profile_image_url": "/user.png"
}

Account Creation

First user becomes admin automatically
Subsequent users get the default role (configured in settings)
Email validation ensures proper format

Automatic Sign In

Upon successful registration, users are automatically signed in

Password requirements are enforced server-side. Passwords are hashed using bcrypt and never stored in plain text.

Authenticate existing users:

# API endpoint: POST /api/v1/auths/signin
curl -X POST "https://your-instance/api/v1/auths/signin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Response includes:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_at": 1735689600,
  "id": "user-id",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "profile_image_url": "/api/v1/users/user-id/profile/image",
  "permissions": {...}
}

Rate Limiting

Sign-in attempts are rate-limited to prevent brute force attacks:

5 attempts per 3 minutes per email address
Automatically resets after the time window

LDAP Authentication

Integrate with corporate directories.

Configuration

Configure LDAP settings through the admin panel:

# From routers/auths.py:335-353
{
  "LDAP_SERVER_HOST": "ldap.example.com",
  "LDAP_SERVER_PORT": 389,
  "LDAP_USE_TLS": true,
  "LDAP_ATTRIBUTE_FOR_USERNAME": "uid",
  "LDAP_ATTRIBUTE_FOR_MAIL": "mail",
  "LDAP_SEARCH_BASE": "ou=users,dc=example,dc=com",
  "LDAP_SEARCH_FILTERS": "(objectClass=person)",
  "LDAP_APP_DN": "cn=admin,dc=example,dc=com",
  "LDAP_APP_PASSWORD": "admin_password"
}

LDAP Authentication Flow

User Submits Credentials

{
  "user": "jdoe",
  "password": "ldap_password"
}

Directory Lookup

Open WebUI searches LDAP for the user:

Queries using configured search base and filters
Retrieves user attributes (email, name, groups)

Credential Verification

Binds to LDAP using the user’s DN and password to verify credentials

Account Provisioning

Creates local account if it doesn’t exist
First LDAP user becomes admin
Subsequent users get default role

Group Synchronization

If enabled, synchronizes LDAP groups to Open WebUI groups

LDAP Group Management

Automatic group synchronization:

# Configuration
{
  "ENABLE_LDAP_GROUP_MANAGEMENT": true,
  "ENABLE_LDAP_GROUP_CREATION": true,
  "LDAP_ATTRIBUTE_FOR_GROUPS": "memberOf"
}

Features:

Auto-sync: Groups updated on each login
Group creation: Automatically creates missing groups
CN extraction: Extracts group names from DNs
Role preservation: Doesn’t affect admin users

OAuth/SSO Integration

Supported Providers

Configure multiple OAuth providers:

OpenID Connect (OIDC)
Google
GitHub
Microsoft Azure AD
Okta
Custom providers

OAuth Flow

User Initiates Login

Click “Sign in with [Provider]” button

Redirect to Provider

User is redirected to OAuth provider for authentication

Authorization Grant

User approves application access

Token Exchange

Provider returns authorization code, exchanged for access token

User Info Retrieval

Open WebUI fetches user profile from provider

Account Linking

Links OAuth account to existing user (if email matches)
Creates new user if no match found

Token Exchange Endpoint

Exchange external OAuth tokens for Open WebUI JWT:

# API endpoint: POST /api/v1/auths/oauth/{provider}/token/exchange
curl -X POST "https://your-instance/api/v1/auths/oauth/google/token/exchange" \
  -H "Content-Type: application/json" \
  -d '{"token": "external_oauth_token"}'

This endpoint is disabled by default. Set ENABLE_OAUTH_TOKEN_EXCHANGE=true to enable.

Trusted Header Authentication

Integrate with reverse proxy SSO.

Configuration

# Environment variables
WEBUI_AUTH_TRUSTED_EMAIL_HEADER="X-Auth-Email"
WEBUI_AUTH_TRUSTED_NAME_HEADER="X-Auth-Name"
WEBUI_AUTH_TRUSTED_GROUPS_HEADER="X-Auth-Groups"

How It Works

Proxy Authentication

Reverse proxy (Nginx, Traefik, etc.) handles authentication

Header Injection

Proxy adds trusted headers with user information

Account Auto-Creation

Open WebUI:

Reads headers on each request
Creates user if doesn’t exist
Updates name/groups from headers

Automatic Sign-In

User is automatically authenticated without credentials

Security Critical: Only enable trusted headers when Open WebUI is behind a properly configured reverse proxy. Exposed directly to the internet, this allows authentication bypass.

Session Management

JWT Tokens

Open WebUI uses JWT for session management:

{
  "id": "user-id",
  "exp": 1735689600,  // Expiration timestamp
  "iat": 1735603200   // Issued at timestamp
}

Token Configuration

Customize token behavior:

# Admin settings
{
  "JWT_EXPIRES_IN": "30d",  // Duration format: 1d, 12h, 30m
}

Supported formats:

ms: milliseconds
s: seconds
m: minutes
h: hours
d: days
w: weeks
-1: No expiration

# Environment variables
WEBUI_AUTH_COOKIE_SAME_SITE="lax"  # lax, strict, none
WEBUI_AUTH_COOKIE_SECURE="true"    # HTTPS only

Sign Out

Terminate user sessions:

GET /api/v1/auths/signout

Sign-out process:

Invalidates JWT token
Clears browser cookies (token, oui-session, oauth_id_token)
Optionally redirects to OAuth provider logout
Returns to configured redirect URL

OAuth Logout

For OAuth users, sign-out includes:

Retrieval of provider’s end session endpoint
Redirect to provider logout URL
Return to configured WEBUI_AUTH_SIGNOUT_REDIRECT_URL

User Profile Management

Viewing Profile

Get current user information:

GET /api/v1/auths/

Returns:

{
  "id": "user-id",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "profile_image_url": "/api/v1/users/user-id/profile/image",
  "bio": "Software engineer",
  "status_emoji": "💻",
  "status_message": "Coding",
  "permissions": {...}
}

Updating Profile

Modify profile information:

# API endpoint: POST /api/v1/auths/update/profile
{
  "name": "Jane Doe",
  "profile_image_url": "new-image-url",
  "bio": "Updated bio"
}

Changing Password

Submit Request

{
  "password": "current_password",
  "new_password": "new_secure_password"
}

Verification

Current password is verified against stored hash

Validation

New password validated against security requirements

Update

Password hash updated in database

Password changes are not available when using trusted header authentication.

API Keys

Generate API keys for programmatic access.

Creating API Keys

# POST /api/v1/auths/api_key
curl -X POST "https://your-instance/api/v1/auths/api_key" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "api_key": "sk-abc123..."
}

Using API Keys

curl -X GET "https://your-instance/api/v1/chats" \
  -H "Authorization: Bearer sk-abc123..."

Managing API Keys

View Key
Regenerate
Delete

GET /api/v1/auths/api_key

Retrieve your current API key

POST /api/v1/auths/api_key

Creates a new key, invalidating the old one

DELETE /api/v1/auths/api_key

Permanently removes your API key

API Key Restrictions

Optionally restrict API key usage:

# Admin configuration
{
  "ENABLE_API_KEYS": true,
  "ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS": true,
  "API_KEYS_ALLOWED_ENDPOINTS": "/api/v1/chats,/api/v1/models"
}

API key functionality requires the features.api_keys permission for users.

Admin Functions

Adding Users

Admins can create user accounts:

# POST /api/v1/auths/add
{
  "email": "newuser@example.com",
  "password": "temporary_password",
  "name": "New User",
  "role": "user",  // user, admin, pending
  "profile_image_url": "/user.png"
}

Admin Configuration

Manage authentication settings:

# GET/POST /api/v1/auths/admin/config
{
  "ENABLE_SIGNUP": true,
  "DEFAULT_USER_ROLE": "user",
  "DEFAULT_GROUP_ID": "default-group",
  "JWT_EXPIRES_IN": "30d",
  "ENABLE_API_KEYS": true,
  "SHOW_ADMIN_DETAILS": true,
  "ADMIN_EMAIL": "admin@example.com"
}

Admin Contact Display

Show admin contact information to users:

GET /api/v1/auths/admin/details

Enable SHOW_ADMIN_DETAILS to display admin contact on the UI for user support.

Security Best Practices

Strong Passwords

Minimum length requirements
Complexity validation
Bcrypt hashing with salt
72-byte maximum for bcrypt compatibility

Rate Limiting

Sign-in attempt throttling
Redis-backed rate limiter
Configurable time windows

Secure Cookies

HttpOnly flag set
SameSite protection
Secure flag for HTTPS
Proper expiration

Token Security

JWT signed with secret
Expiration enforcement
Token invalidation on logout
Secure storage recommendations

Troubleshooting

Common Issues

Failed LDAP Authentication

Check:

LDAP server connectivity and port
TLS/SSL certificate validation
Search base and filter syntax
App DN credentials
User attribute mappings

OAuth Login Fails

Trusted Headers Not Working

Ensure:

Headers are properly configured in proxy
Header names match environment variables
Open WebUI not directly exposed
Headers properly URL-encoded

API Key Not Accepted

Confirm:

API keys are enabled in settings
User has features.api_keys permission
Key not expired or deleted
Endpoint restrictions allow the request

​Overview

​Authentication Methods

​Sign Up & Sign In

​User Registration

​Sign In Process

​Rate Limiting

​LDAP Authentication

​Configuration

​LDAP Authentication Flow

​LDAP Group Management

​OAuth/SSO Integration

​Supported Providers

​OAuth Flow

​Token Exchange Endpoint

​Trusted Header Authentication

​Configuration

​How It Works

​Session Management

​JWT Tokens

​Token Configuration

​Cookie Settings

​Sign Out

​OAuth Logout

​User Profile Management

​Viewing Profile

​Updating Profile

​Changing Password

​API Keys

​Creating API Keys

​Using API Keys

​Managing API Keys

​API Key Restrictions

​Admin Functions

​Adding Users

​Admin Configuration

​Admin Contact Display

​Security Best Practices

Strong Passwords

Rate Limiting

Secure Cookies

Token Security

​Troubleshooting

​Common Issues

Overview

Authentication Methods

Sign Up & Sign In

User Registration

Sign In Process

Rate Limiting

LDAP Authentication

Configuration

LDAP Authentication Flow

LDAP Group Management

OAuth/SSO Integration

Supported Providers

OAuth Flow

Token Exchange Endpoint

Trusted Header Authentication

Configuration

How It Works

Session Management

JWT Tokens

Token Configuration

Cookie Settings

Sign Out

OAuth Logout

User Profile Management

Viewing Profile

Updating Profile

Changing Password

API Keys

Creating API Keys

Using API Keys

Managing API Keys

API Key Restrictions

Admin Functions

Adding Users

Admin Configuration

Admin Contact Display

Security Best Practices

Troubleshooting

Common Issues