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

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.

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:

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 which can be assigned custom roles and permissions using the REST API or programmatically using a client library.

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

# 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 which can be assigned custom roles and permissions using the REST API or programmatically using a client library.

Metadata reader role

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:

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.

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
• RBAC: Manage roles
• RBAC: Manage users
• RBAC: Tutorial

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.