Skip to main content

RBAC Roles

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.

Weaviate provides differentiated access through authorization levels, based on the authenticated user identity.

If role-based access control (RBAC) is enabled, access can be further restricted based 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.

Roles and permissions can be managed through Weaviate API (e.g. via REST API directly, or through a client library).

Refer to the client library examples below, or the REST API documentation for concrete examples on how to manage roles and permissions.

Roles​

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

admin and viewer roles 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.

All roles can also be assigned through the Weaviate API, including the predefined roles. The predefined roles cannot be modified, but they can be assigned or revoked from users.

Refer to the authorization page for more information on how to assign predefined roles to users.

Custom roles​

Any authenticated user that is not assigned a predefined role has no roles or permissions by default.

These users' permissions can be modified through Weaviate by those with the appropriate permissions. This allows for the creation of custom roles, which can be assigned to users as needed.

Managing roles​

Role management requires appropriate role resource permissions through a predefined admin role or a role with manage_roles permission.

Permissions​

Permissions in Weaviate define what actions users can perform on specific resources. Each permission consists of:

  • A resource type (e.g., collections, objects)
  • Access levels (read, write, update, delete, manage)
  • Optional resource-specific constraints

Available permissions​

Permissions can be defined for the following resources:

  1. Role Management

    • Read roles
    • Manage roles

  2. Collections (collection definitions only, data object permissions are separate)

    • Create, read, update, and delete collection definitions

  3. Data Objects

    • Read, write, update, and delete objects

  4. Backup

    • Manage backups

  5. Cluster Data Access

    • Read cluster metadata

  6. Node Data Access

    • Read node metadata at a specified verbosity level
Role Management Permissions

Be careful when assigning permissions to roles that manage roles. These permissions can be used to escalate privileges by assigning additional roles to users. Only assign these permissions to trusted users.

Permission behavior​

When defining permissions, setting a permission to False indicates that the permission is not set, rather than explicitly denying access. This means that if a user has multiple roles, and one role grants a permission while another sets it to False, the user will still have that permission through the role that grants it.

For example, if a user has two roles:

  • Role A sets read to False for Collection X
  • Role B sets read to True for Collection X

The user will have read access to Collection X because Role B grants the permission, while Role A's False value simply indicates no permission is set rather than blocking access.

Example permission sets​

Read and write permissions​

This confers read and write permissions for collections starting with TargetCollection_, and read permissions to nodes and cluster metadata.

from weaviate.classes.rbac import Permissions

# Define permissions (example confers read+write rights to collections starting with "TargetCollection_")
admin_permissions = [
    Permissions.collections(
        collection="TargetCollection_*",
        create_collection=True,
        read_config=True,
        update_config=True,
        delete_collection=True,
    ),
    Permissions.data(
        collection="TargetCollection_*",
        create=True,
        read=True,
        update=True,
        delete=True
    ),
    Permissions.backup(collection="TargetCollection_*", manage=True),
    Permissions.nodes(collection="TargetCollection_*", read=True),
    Permissions.cluster(read=True),
]

# Create a new role and assign it to a user
admin_client.roles.create(role_name="rw_role_target_collections", permissions=admin_permissions)
admin_client.roles.assign_to_user(role_names="rw_role_target_collections", user="other-user")
py docs  API docs

Viewer permissions​

This confers viewer permissions for collections starting with TargetCollection_.

from weaviate.classes.rbac import Permissions

# Define permissions (example confers viewer rights to collections starting with "TargetCollection_")
viewer_permissions = [
    Permissions.collections(
        collection="TargetCollection_*",
        read_config=True,
    ),
    Permissions.data(collection="TargetCollection_*", read=True),
]

# Create a new role and assign it to a user
admin_client.roles.create(role_name="viewer_role_target_collections", permissions=viewer_permissions)
admin_client.roles.assign_to_user(role_names="viewer_role_target_collections", user="other-user")
py docs  API docs

Role management​

Role management requires appropriate role resource permissions through a predefined admin role or a role with manage_roles permission.

For more information see the Authentication and Authorization pages.

import weaviate
from weaviate.classes.init import Auth

# Connect to Weaviate as Admin
admin_client = weaviate.connect_to_local(
    auth_credentials=Auth.api_key("admin-key")
)
py docs  API docs

Create an empty role​

This example creates a role called "devrel" without any permissions assigned to it.

admin_client.roles.create(role_name="devrel")
py docs  API docs

Create new role with permissions​

This example creates a role called "devrel" with permissions to:

  • Read all collections starting with "Test_".
  • Delete or create the collection "Test_DevRel"
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.collections(
      collection="Test_*",
      read_config=True,
      create_collection=False,
      delete_collection=False,
  ),
    Permissions.collections(
      collection="Test_DevRel",
      read_config=True,
      create_collection=True,
      delete_collection=True,
  ),
]

admin_client.roles.create(
    role_name="devrel", permissions=permissions
)
py docs  API docs

Grant additional permissions​

Additional permissions can be granted to a role at any time. The role must already exist.

This example grants additional permissions to the "devrel" role to:

  • Read data in all collections that start with "Test_".
  • Create new data in "Test_DevRel".
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.data(collection="Test_DevRel", read=True, create=True),
    Permissions.data(collection="Test_*", read=True, create=False)
]

admin_client.roles.add_permissions(permissions=permissions, role_name="devrel")
py docs  API docs

Remove permissions from a role​

Permissions can be removed from a role at any time. Removing all permissions from a role will not delete the role itself.

This example removes from the "devrel" role permissions to:

  • Read the data from collections that start with "Test_"
  • Create and delete collections called "Test_DevRel"
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.collections(
      collection="Test_DevRel",
      read_config=True,
      create_collection=True,
      delete_collection=True,
  ),
  Permissions.data(collection="Test_*", read=True, create=False)
]

admin_client.roles.remove_permissions(
    role_name="devrel", permissions=permissions
)
py docs  API docs

Assign a role to a user​

A custom user can have any number of roles assigned to them (including none). The role can be a predefined role (e.g. viewer) or a custom role.

This example assigns the custom "devrel" role to "jane-doe".

admin_client.roles.assign_to_user(role_names="devrel", user="jane-doe")
py docs  API docs

Get the current user's roles and permissions​

Retrieve the role and permission information for the currently authenticated user.

print(admin_client.roles.of_current_user())
py docs  API docs

Get a user's roles and permissions​

Retrieve the role and permission information for any user.

user_roles = admin_client.roles.roles.by_user(user="jane-doe")

for role in user_roles:
    print(role)
py docs  API docs

Check if a role exists​

print(admin_client.roles.exists(role_name="role-name"))  # Returns True or False
py docs  API docs

Inspect a role​

View the permissions assigned to a role.

print(admin_client.roles.by_name(role_name="role-name"))
py docs  API docs

List all roles​

View all roles in the system and their permissions.

all_roles = admin_client.roles.list_all()

for role_name, role in all_roles.items():
    print(role_name, role)
py docs  API docs

List users with a role​

assigned_users = admin_client.roles.assigned_users(role_name="role-name")

for user in assigned_users:
    print(user)
py docs  API docs

Delete a role​

Deleting a role will remove it from the system, and revoke the associated permissions from all users had this role.

admin_client.roles.delete(role_name="role-name")
py docs  API docs

Revoke a role from a user​

You can revoke one or more roles from a specific user.

This examples revokes "role-1" and "role-2" from the user "jane-doe".

admin_client.roles.revoke_from_user(role_names=["role-1", "role-2"], user="jane-doe")
py docs  API docs

Further resources​

Questions and feedback​

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