---
title: "Enable and configure RBAC"
description: "Role-based access control (RBAC) is a method of restricting access to resources based on the roles of users. In Weaviate, RBAC allows you to define roles and assign permissions to those roles. Users can then be assigned to roles and inherit the permissions associated with those roles."
url: https://docs.weaviate.io/deploy/configuration/configuring-rbac
---

# Enable and configure RBAC

Role-based access control (RBAC) is a method of restricting access to resources based on the roles of users. In Weaviate, RBAC allows you to **[define roles and assign permissions](https://docs.weaviate.io/weaviate/configuration/rbac/manage-roles)** to those roles. Users can then be assigned to roles and inherit the permissions associated with those roles.

Weaviate comes with a set of predefined roles. These roles are:

- `root`: The root role has full access to all resources in Weaviate.
- `viewer`: The viewer role has read-only access to all resources in Weaviate.
- `operator_metadata_reader`: Added in `v1.39.10`. The metadata reader role can read cluster metadata but never objects or vectors. See [Metadata reader role](https://docs.weaviate.io/deploy/configuration/configuring-rbac#metadata-reader-role).

The `root` role can be assigned through the Weaviate configuration file. A predefined role cannot be modified. The user can, however, be assigned additional roles through the Weaviate API.

> [!TIP]
>
> **Root user requirement in older versions**
>
> In Weaviate versions `v1.30.6` and `v1.31.0` or below, if RBAC is enabled, you must configure at least one user with the built-in root role. Otherwise, Weaviate will not start. This requirement was removed in versions `v1.30.7` and `v1.31.1`.

## Docker

RBAC authorization can be configured using environment variables. In Docker Compose, set them in the configuration file (`docker-compose.yml`) such as in the following example:

```yaml
services:
  weaviate:
    ...
    environment:
      ...
      # Example authentication configuration using API keys
      # OIDC access can also be used with RBAC
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'root-user-key'
      AUTHENTICATION_APIKEY_USERS: 'root-user'

      # Authorization configuration
      # Enable RBAC
      AUTHORIZATION_RBAC_ENABLED: 'true'

      # Provide pre-configured roles to users
      # This assumes that the relevant user has been authenticated and identified

      # You MUST define at least one root user
      AUTHORIZATION_RBAC_ROOT_USERS: 'root-user'
      # Enable the runtime user management
      AUTHENTICATION_DB_USERS_ENABLED: 'true'
```

This configuration:

- Enables RBAC
- Configures `root-user` as a user with built-in admin permissions

You can connect to your instance with the root user in order to [create new users](https://docs.weaviate.io/weaviate/configuration/rbac/manage-users) which can be assigned custom roles and permissions using the [REST API](https://docs.weaviate.io/weaviate/api/rest#tag/authz) or [programmatically using a client library](https://docs.weaviate.io/weaviate/configuration/rbac/manage-roles).

> [!TIP]
>
> **TIP: User management API available from `v1.30`**
>
> Instead of adding additional users via the `AUTHENTICATION_APIKEY_USERS` environment variable, we suggest using the [user management API](https://docs.weaviate.io/weaviate/configuration/rbac/manage-users) which you can use to create and delete users, manage their roles and rotate their API keys.

## Kubernetes

For Kubernetes deployments using Helm, API key authentication can be configured in the `values.yaml` file under the `authorization` section. Here's an example configuration:

```yaml
# Example authentication configuration using API keys
authentication:
  anonymous_access:
    enabled: false
  apikey:
    enabled: true
    allowed_keys:
      - root-user-key
    users:
      - root-user

# Authorization configuration
authorization:
  rbac:
    # Enable RBAC
    enabled: true
    # Provide pre-configured roles to users
    # This assumes that the relevant user has been authenticated and identified
    #
    # You MUST define at least one root user
    root_users:
    - root-user
```

This configuration:

- Enables RBAC
- Configures `root-user` as a user with built-in admin permissions

You can connect to your instance with the root user in order to [create new users](https://docs.weaviate.io/weaviate/configuration/rbac/manage-users) which can be assigned custom roles and permissions using the [REST API](https://docs.weaviate.io/weaviate/api/rest#tag/authz) or [programmatically using a client library](https://docs.weaviate.io/weaviate/configuration/rbac/manage-roles).

## Metadata reader role

> [!NOTE]
>
> **Added in `v1.39.10`**

**Permissions and configuration**

The built-in `operator_metadata_reader` role reads cluster metadata and access-control configuration. It never reads objects or vectors. The role has these permissions:

| Action | Resources |
| - | - |
| `read_collections` | All collections |
| `read_tenants` | All tenants |
| `read_nodes` | All collections, `verbose` |
| `read_cluster` | Cluster metadata |
| `read_aliases` | All aliases |
| `read_replicate` | All collections and shards |
| `read_users` | All users |
| `read_roles` | All roles |
| `read_groups` | All OIDC groups |
| `read_backups` | All collections |

The role does not include `read_data`, `read_mcp` or any action that changes state.

The role appears in role listings, such as `GET /v1/authz/roles`, for any user with `read_roles`. It does nothing until you bind it to OIDC groups.

The only way to bind the role is the `metadata_groups` key under `authorization.rbac` in a configuration file. Pass the file to Weaviate with `--config-file`:

```yaml
authorization:
  rbac:
    enabled: true
    metadata_groups:
    - platform-observers
```

There is no environment variable for this key. The binding applies to OIDC groups only. Deployments that use only API keys cannot use this role.

The role cannot be assigned, revoked, deleted or recreated through the Weaviate API. The binding is reset from the configuration file every time Weaviate starts.

## Authorization audit logging

When RBAC is enabled, Weaviate automatically logs all authorization decisions for audit purposes. These logs capture:

- User making the request
- Action being authorized
- Authorization decision (allowed or denied)
- User groups (if applicable)
- Source IP address (optional)
- Resource being accessed

Audit logs are written at the `info` level for successful authorizations and `error` level for denials. No additional configuration is required - audit logging is automatic when RBAC is enabled.

For details on log format, how to collect and analyze authorization audit logs, and best practices for log retention, see the [Logging configuration page](https://docs.weaviate.io/deploy/configuration/logging#authorization-audit-logging).

## RBAC and performance

RBAC is a powerful feature that allows you to define fine-grained access control policies. However, it can also have an impact on performance as each operation must be checked against the user's permissions.

The exact performance impact will depend on your setup and use case. In our internal testing, the most significant performance impact was seen for object creation operations.

We did not observe additional performance penalties for using custom roles over the built-in roles.

Here are some tips to optimize performance when using RBAC:

- Monitor object creation performance
- Use a high availability (i.e. 3+ nodes) setup to distribute the load

## Further resources

- [RBAC: Overview](https://docs.weaviate.io/weaviate/configuration/rbac)
- [RBAC: Manage roles](https://docs.weaviate.io/weaviate/configuration/rbac/manage-roles)
- [RBAC: Manage users](https://docs.weaviate.io/weaviate/configuration/rbac/manage-users)
- [RBAC: Tutorial](https://docs.weaviate.io/weaviate/tutorials/rbac)
