---
sidebar_position: 3
title: "🔑 Roles"
---

Open WebUI implements a structured role-based access control system with three primary user roles:

| **Role**      | **Description**                                   | **Default Creation**             |
|---------------|---------------------------------------------------|----------------------------------|
| Administrator | System administrator with full control            | First user account               |
| Regular User  | Standard user with limited permissions            | Subsequent approved users        | 
| Pending       | Unapproved user awaiting administrator activation | New registrations (configurable) |

### Role Assignment

* **First User:** The first account created on a new Open WebUI instance automatically receives Administrator
  privileges.
* **Subsequent Users:** New user registrations are assigned a default role based on the `DEFAULT_USER_ROLE`
  configuration.

The default role for new registrations can be configured using the `DEFAULT_USER_ROLE` environment variable:

```.dotenv
DEFAULT_USER_ROLE=pending  # Options: pending, user, admin
```

When set to "pending", new users must be manually approved by an administrator before gaining access to the system.

## User Groups

Groups allow administrators to
* assign permissions to multiple users at once, simplifying access management
* limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to 
specific groups
* Group access to a resource can be set as "read" or "write"

### Group Structure

Each group in Open WebUI contains:

* A unique identifier
* Name and description
* Owner/creator reference
* List of member user IDs
* Permission configuration
* Additional metadata

### Group Management

Groups can be:

* **Created manually** by administrators through the user interface
* **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled
* **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION`
  are enabled

### OAuth Group Integration

When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims:

* Users are added to Open WebUI groups that match their OAuth claims
* Users are removed from groups not present in their OAuth claims
* With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically
  created