Skip to main content

Authorization & RBAC

Authentication and authorization

Authentication and authorization are closely related concepts, and sometimes abbreviated as AuthN and AuthZ. Authentication (AuthN) is the process of verifying the identity of a user, while authorization (AuthZ) is the process of determining what permissions the user has.

Weaviate provides differentiated access through authorization levels, based on the user's authentication status. A user can be granted admin permission, read-only permission, or no permission at all. From v1.28.0, Weaviate also supports Role-Based Access Control (RBAC) for more fine-grained control over user permissions.

The following diagram illustrates the flow of a user request through the authentication and authorization process:

Available authorization schemes​

The following authorization schemes are available in Weaviate:

In the Admin list authorization scheme, anonymous users can be granted permissions.

The way to configure authorization differs by your deployment method, depending on whether you are running Weaviate in Docker or Kubernetes. Below, we provide examples for both.

What about Weaviate Cloud (WCD)?

For Weaviate Cloud (WCD) instances, authorization is pre-configured with Admin list access. You can authenticate against Weaviate with your WCD credentials using OIDC, or with admin or read-only API keys.


RBAC access will be available in WCD in a future release.

Role-Based Access Control (RBAC)​

RBAC technical preview

Role-based access control (RBAC) is added v1.28 as a technical preview. This means that the feature is still under development and may change in future releases, including potential breaking changes. We do not recommend using this feature in production environments at this time.


We appreciate your feedback on this feature.

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:

  • admin: The admin role has full access to all resources in Weaviate.
  • viewer: The viewer role has read-only access to all resources in Weaviate.

They are assigned to users based on the Weaviate configuration file. Once a user is assigned a predefined role, their permissions are set accordingly. These roles cannot be modified, and these users cannot have additional roles assigned to them.

For more information on roles and permissions, see this page.

At least one admin user required

When using RBAC, you must specify at least one user with the build-in admin role. This user will have full permissions to perform all actions in Weaviate. Otherwise, Weaviate will not start.

Discussions: 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 set up and use case. In our internal testing, the most significant performance impact was seen for object creation operations.

We did not observe additional performance penalities 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

RBAC: 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: 'viewer-key,admin-key,other-key'
      AUTHENTICATION_APIKEY_USERS: 'viewer-user,admin-user,other-user'

      # Authorization configuration
      # Enable RBAC
      AUTHORIZATION_ENABLE_RBAC: 'true'

      # Provide pre-configured roles to users
      # This assumes that the relevant user has been authenticated and identified
      #
      # You MUST define at least one admin user
      AUTHORIZATION_ADMIN_USERS: 'admin-user'
      AUTHORIZATION_VIEWER_USERS: 'viewer-user'

This configuration:

  • Enables RBAC
  • Configures admin-user as a user with built-in admin permissions
  • Configures viewer-user as a user with built-in viewer permissions
  • Configures other-user as a user with no built-in permissions

The other-user can now be assigned custom roles and permissions using the RBAC Roles API.

RBAC: 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:
      - admin-key
      - viewer-key
      - other-key
    users:
      - admin-user
      - viewer-user
      - other-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 admin user
    admins:
    - admin-user
    viewers:
    - viewer-user

This configuration:

  • Enables RBAC
  • Configures admin-user as a user with built-in admin permissions
  • Configures viewer-user as a user with built-in viewer permissions
  • Configures other-user as a user with no built-in permissions

The other-user can now be assigned custom roles and permissions using the RBAC Roles API.

Admin list​

The "Admin list" authorization scheme allows you to specify a list of admin users with full permissions to perform all actions in Weaviate, and a list of read-only users with permissions to perform only read operations.

These permissions cannot be customized or extended. For more fine-grained control over user permissions, use RBAC instead.

Admin list authorization scheme cannot be used in combination with RBAC.

Admin list: Docker​

Admin list 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: 'viewer-key,admin-key,other-key'
      AUTHENTICATION_APIKEY_USERS: 'viewer-user,admin-user,other-user'

      # Authorization configuration
      # Enable admin list
      AUTHORIZATION_ADMINLIST_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 admin user
      AUTHORIZATION_ADMINLIST_USERS: 'admin-user'
      AUTHORIZATION_ADMINLIST_READONLY_USERS: 'viewer-user'

This configuration:

  • Enables Admin list authorization
  • Configures admin-user as a user with built-in admin permissions
  • Configures viewer-user as a user with built-in viewer permissions

Note that in this configuration, other-user has no permissions.

Admin list: 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:
      - admin-key
      - viewer-key
      - other-key
    users:
      - admin-user
      - viewer-user
      - other-user

# Authorization configuration
authorization:
  admin_list:
    # Enable admin list
    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 admin user
    users:
    - admin-user
    read_only_users:
    - viewer-user

Anonymous users​

Anonymous users are identified as anonymous in Weaviate. In the Admin list authorization scheme, you can apply permissions to anonymous users. The RBAC authorization scheme is not compatible with anonymous users.

To confer permissions to anonymous users in the Admin list scheme, you can use the anonymous keyword in the configuration as shown below.

services:
  weaviate:
    ...
    environment:
      ...
      # Enable anonymous access
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'

      # Configure admin user API key
      AUTHORIZATION_ADMINLIST_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'admin-key'
      AUTHENTICATION_APIKEY_USERS: 'admin-user'

      # Enable admin list and provide admin access to "admin-user" only
      AUTHORIZATION_ADMINLIST_USERS: 'admin-user'
      # Provide read-only access to anonymous users
      AUTHORIZATION_ADMINLIST_READONLY_USERS: 'anonymous'

Undifferentiated access​

Weaviate can be configured to provide undifferentiated access, by disabling authentication for example and enabling anonymous access. This configuration is strongly discouraged except for development or evaluation purposes.

Further resources​

Questions and feedback​

If you have any questions or feedback, let us know in the user forum.