Skip to main content

Manage roles and users

Available from v1.29

Role-based access control (RBAC) is generally available in Weaviate from version v1.29.

In Weaviate, Role-based access control (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. On this page, you will find examples of how to manage roles and users with Weaviate client libraries.

Follow these general steps to configure RBAC:

  1. Step 1. Connect to Weaviate with a user possessing role management permissions.
  2. Step 2. Grant permissions to a new role or an existing role.
  3. Step 3. Assign the role to a user.

Requirements for managing roles ​

Role management requires appropriate role resource permissions that can be obtained through:

import weaviate
from weaviate.classes.init import Auth

# Connect to Weaviate as root user
client = weaviate.connect_to_local(
    auth_credentials=Auth.api_key("user-a-key"),
)
py docs  API docs

Role management ​

Create new roles with permissions​

Permissions for these resource types can be assigned to roles:

  1. Role Management

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

  3. Tenants

  4. Data Objects

  5. Backup

  6. Cluster Data Access

  7. Node Data Access

Create a role with Role Management permissions​

This example creates a role called testRole with permissions to:

  • Manage all roles starting with testRole*.
from weaviate.classes.rbac import Permissions, RoleScope

permissions = [
    Permissions.roles(
        role="testRole*",  # Applies to all roles starting with "testRole"
        create=True,  # Allow creating roles
        read=True,  # Allow reading roles
        update=True,  # Allow updating roles
        delete=True,  # Allow deleting roles
        scope=RoleScope.MATCH,  # Only allow role management with the current user's permission level
        # scope=RoleScope.ALL   # Allow role management with all permissions
    )
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Collections permissions​

This example creates a role called testRole with permissions to:

  • Create, read, update and delete all collections starting with TargetCollection.
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.collections(
        collection="TargetCollection*",  # Applies to all collections starting with "TargetCollection"
        create_collection=True,  # Allow creating new collections
        read_config=True,  # Allow reading collection info/metadata
        update_config=True,  # Allow updating collection configuration, i.e. update schema properties, when inserting data with new properties
        delete_collection=True,  # Allow deleting collections
    ),
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Tenant permissions​

This example creates a role called testRole with permissions to:

  • Create and delete tenants in collections starting with TargetCollection.
  • Read tenant metadata (like tenant names and status) in collections starting with TargetCollection.
  • Update tenant status in collections starting with TargetCollection.
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.collections(
        collection="TargetCollection*",
        create_collection=True,
        read_config=True,
        update_config=True,
        delete_collection=True,
    ),
    Permissions.tenants(
        collection="TargetCollection*",  # Applies to all collections starting with "TargetCollection"
        create=True,  # Allow creating new tenants
        read=True,  # Allow reading tenant info/metadata
        update=True,  # Allow updating tenant states
        delete=True,  # Allow deleting tenants
    ),
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Data Objects permissions​

This example creates a role called testRole with permissions to:

  • Create, read, update and delete data from collections starting with TargetCollection.
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.data(
        collection="TargetCollection*",  # Applies to all collections starting with "TargetCollection"
        create=True,  # Allow data inserts
        read=True,  # Allow query and fetch operations
        update=True,  # Allow data updates
        delete=False,  # Allow data deletes
    ),
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Backups permissions​

This example creates a role called testRole with permissions to:

  • Manage backups for collections starting with TargetCollection.
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.backup(
        collection="TargetCollection*",  # Applies to all collections starting with "TargetCollection"
        manage=True,  # Allow managing backups
    ),
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Cluster Data Access permissions​

This example creates a role called testRole with permissions to:

  • Read cluster metadata.
from weaviate.classes.rbac import Permissions

permissions = [
    Permissions.cluster(read=True),  # Allow reading cluster data
]

client.roles.create(role_name="testRole", permissions=permissions)
py docs  API docs

Create a role with Node Data Access permissions​

This example creates a role called testRole with permissions to:

  • Read node metadata at the specified verbosity level for collections starting with TargetCollection.
from weaviate.classes.rbac import Permissions

verbose_permissions = [
    Permissions.Nodes.verbose(
        collection="TargetCollection*",  # Applies to all collections starting with "TargetCollection"
        read=True,  # Allow reading node metadata
    ),
]

# The `minimal` verbosity level applies to all collections unlike
# the `verbose` level where you specify the collection name filter
minimal_permissions = [
    Permissions.Nodes.minimal(
        read=True,  # Allow reading node metadata
    ),
]

client.roles.create(role_name="testRole", permissions=verbose_permissions)  # or `minimal_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 role testRole to:

  • Read data in all collections that start with TargetCollection.
  • Create new data in collections that start withTargetCollection.
from weaviate.classes.rbac import Permissions

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

client.roles.add_permissions(permissions=permissions, role_name="testRole")
py docs  API docs

Remove permissions from a role​

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

This example removes the following permissions from the role testRole:

  • Read the data from collections that start with TargetCollection
  • Create and delete collections that start with TargetCollection
from weaviate.classes.rbac import Permissions

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

client.roles.remove_permissions(role_name="testRole", permissions=permissions)
py docs  API docs

Check if a role exists​

Check if the role testRole exists:

print(client.roles.exists(role_name="testRole"))  # Returns True or False
py docs  API docs

Inspect a role​

View the permissions assigned to a role.

test_role = client.roles.get(role_name="testRole")

print(test_role)
print(test_role.collections_permissions)
print(test_role.data_permissions)
py docs  API docs

List all roles​

View all roles in the system and their permissions.

all_roles = 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​

List all users who have the role testRole.

assigned_users = client.roles.get_assigned_user_ids(role_name="testRole")

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 who had this role.

client.roles.delete(role_name="testRole")
py docs  API docs

User management ​

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 testRole role and predefined viewer role to user-b.

client.users.assign_roles(user_id="user-b", role_names=["testRole", "viewer"])
py docs  API docs

Remove a role from a user​

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

This example removes the role testRole from the user user-b.

client.users.revoke_roles(user_id="user-b", role_names="testRole")
py docs  API docs

Get the current user's roles and permissions​

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

print(client.users.get_my_user())
py docs  API docs

Get a user's roles and permissions​

Retrieve the role and permission information for any user.

user_roles = client.users.get_assigned_roles("user-b")

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

Additional resources​

Questions and feedback​

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