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

# User Authentication

> Secure user authentication with multiple providers and enterprise SSO support

## Overview

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

## Authentication Methods

<Tabs>
  <Tab title="Email/Password">
    Traditional credential-based authentication:

    * Secure password hashing with bcrypt
    * Password validation rules
    * Account creation and management
    * Password reset workflows
  </Tab>

  <Tab title="OAuth/OIDC">
    Single Sign-On with popular providers:

    * OpenID Connect support
    * OAuth 2.0 integration
    * Multiple provider configuration
    * Account merging by email
  </Tab>

  <Tab title="LDAP">
    Active Directory integration:

    * LDAP/AD authentication
    * Group synchronization
    * TLS/SSL support
    * Custom attribute mapping
  </Tab>

  <Tab title="Trusted Headers">
    Proxy-based authentication:

    * Reverse proxy integration
    * Header-based SSO
    * Automatic account creation
    * Group assignment from headers
  </Tab>
</Tabs>

## Sign Up & Sign In

### User Registration

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

<Steps>
  <Step title="Navigate to Sign Up">
    Access the registration page at `/auth/signup`
  </Step>

  <Step title="Provide Details">
    ```json theme={null}
    {
      "email": "user@example.com",
      "password": "SecureP@ssw0rd",
      "name": "John Doe",
      "profile_image_url": "/user.png"
    }
    ```
  </Step>

  <Step title="Account Creation">
    * First user becomes admin automatically
    * Subsequent users get the default role (configured in settings)
    * Email validation ensures proper format
  </Step>

  <Step title="Automatic Sign In">
    Upon successful registration, users are automatically signed in
  </Step>
</Steps>

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

### Sign In Process

Authenticate existing users:

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

```json theme={null}
{
  "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

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

## LDAP Authentication

Integrate with corporate directories.

### Configuration

Configure LDAP settings through the admin panel:

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

<Steps>
  <Step title="User Submits Credentials">
    ```json theme={null}
    {
      "user": "jdoe",
      "password": "ldap_password"
    }
    ```
  </Step>

  <Step title="Directory Lookup">
    Open WebUI searches LDAP for the user:

    * Queries using configured search base and filters
    * Retrieves user attributes (email, name, groups)
  </Step>

  <Step title="Credential Verification">
    Binds to LDAP using the user's DN and password to verify credentials
  </Step>

  <Step title="Account Provisioning">
    * Creates local account if it doesn't exist
    * First LDAP user becomes admin
    * Subsequent users get default role
  </Step>

  <Step title="Group Synchronization">
    If enabled, synchronizes LDAP groups to Open WebUI groups
  </Step>
</Steps>

### LDAP Group Management

Automatic group synchronization:

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

<Steps>
  <Step title="User Initiates Login">
    Click "Sign in with \[Provider]" button
  </Step>

  <Step title="Redirect to Provider">
    User is redirected to OAuth provider for authentication
  </Step>

  <Step title="Authorization Grant">
    User approves application access
  </Step>

  <Step title="Token Exchange">
    Provider returns authorization code, exchanged for access token
  </Step>

  <Step title="User Info Retrieval">
    Open WebUI fetches user profile from provider
  </Step>

  <Step title="Account Linking">
    * Links OAuth account to existing user (if email matches)
    * Creates new user if no match found
  </Step>
</Steps>

### Token Exchange Endpoint

Exchange external OAuth tokens for Open WebUI JWT:

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

<Note>
  This endpoint is disabled by default. Set `ENABLE_OAUTH_TOKEN_EXCHANGE=true` to enable.
</Note>

## Trusted Header Authentication

Integrate with reverse proxy SSO.

### Configuration

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

<Steps>
  <Step title="Proxy Authentication">
    Reverse proxy (Nginx, Traefik, etc.) handles authentication
  </Step>

  <Step title="Header Injection">
    Proxy adds trusted headers with user information
  </Step>

  <Step title="Account Auto-Creation">
    Open WebUI:

    * Reads headers on each request
    * Creates user if doesn't exist
    * Updates name/groups from headers
  </Step>

  <Step title="Automatic Sign-In">
    User is automatically authenticated without credentials
  </Step>
</Steps>

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

## Session Management

### JWT Tokens

Open WebUI uses JWT for session management:

```json theme={null}
{
  "id": "user-id",
  "exp": 1735689600,  // Expiration timestamp
  "iat": 1735603200   // Issued at timestamp
}
```

### Token Configuration

Customize token behavior:

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

### Cookie Settings

```bash theme={null}
# Environment variables
WEBUI_AUTH_COOKIE_SAME_SITE="lax"  # lax, strict, none
WEBUI_AUTH_COOKIE_SECURE="true"    # HTTPS only
```

## Sign Out

Terminate user sessions:

```bash theme={null}
GET /api/v1/auths/signout
```

Sign-out process:

1. Invalidates JWT token
2. Clears browser cookies (`token`, `oui-session`, `oauth_id_token`)
3. Optionally redirects to OAuth provider logout
4. 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:

```bash theme={null}
GET /api/v1/auths/
```

Returns:

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

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

### Changing Password

<Steps>
  <Step title="Submit Request">
    ```json theme={null}
    {
      "password": "current_password",
      "new_password": "new_secure_password"
    }
    ```
  </Step>

  <Step title="Verification">
    Current password is verified against stored hash
  </Step>

  <Step title="Validation">
    New password validated against security requirements
  </Step>

  <Step title="Update">
    Password hash updated in database
  </Step>
</Steps>

<Warning>
  Password changes are not available when using trusted header authentication.
</Warning>

## API Keys

Generate API keys for programmatic access.

### Creating API Keys

```bash theme={null}
# POST /api/v1/auths/api_key
curl -X POST "https://your-instance/api/v1/auths/api_key" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Response:

```json theme={null}
{
  "api_key": "sk-abc123..."
}
```

### Using API Keys

```bash theme={null}
curl -X GET "https://your-instance/api/v1/chats" \
  -H "Authorization: Bearer sk-abc123..."
```

### Managing API Keys

<Tabs>
  <Tab title="View Key">
    ```bash theme={null}
    GET /api/v1/auths/api_key
    ```

    Retrieve your current API key
  </Tab>

  <Tab title="Regenerate">
    ```bash theme={null}
    POST /api/v1/auths/api_key
    ```

    Creates a new key, invalidating the old one
  </Tab>

  <Tab title="Delete">
    ```bash theme={null}
    DELETE /api/v1/auths/api_key
    ```

    Permanently removes your API key
  </Tab>
</Tabs>

### API Key Restrictions

Optionally restrict API key usage:

```python theme={null}
# Admin configuration
{
  "ENABLE_API_KEYS": true,
  "ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS": true,
  "API_KEYS_ALLOWED_ENDPOINTS": "/api/v1/chats,/api/v1/models"
}
```

<Note>
  API key functionality requires the `features.api_keys` permission for users.
</Note>

## Admin Functions

### Adding Users

Admins can create user accounts:

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

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

```bash theme={null}
GET /api/v1/auths/admin/details
```

<Tip>
  Enable `SHOW_ADMIN_DETAILS` to display admin contact on the UI for user support.
</Tip>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Strong Passwords" icon="key">
    * Minimum length requirements
    * Complexity validation
    * Bcrypt hashing with salt
    * 72-byte maximum for bcrypt compatibility
  </Card>

  <Card title="Rate Limiting" icon="shield">
    * Sign-in attempt throttling
    * Redis-backed rate limiter
    * Configurable time windows
  </Card>

  <Card title="Secure Cookies" icon="cookie">
    * HttpOnly flag set
    * SameSite protection
    * Secure flag for HTTPS
    * Proper expiration
  </Card>

  <Card title="Token Security" icon="lock">
    * JWT signed with secret
    * Expiration enforcement
    * Token invalidation on logout
    * Secure storage recommendations
  </Card>
</CardGroup>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Failed LDAP Authentication">
    Check:

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

  <Accordion title="OAuth Login Fails">
    Verify:

    * Redirect URI matches OAuth app config
    * Client ID and secret are correct
    * OAuth scopes include email
    * Provider allows account merging
  </Accordion>

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

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