Manage roles and users
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:
- Step 1. Connect to Weaviate with a user possessing role management permissions.
- Step 2. Grant permissions to a new role or an existing role.
- Step 3. Assign the role to a user.
Requirements for managing roles
Role management requires appropriate role
resource permissions that can be obtained through:
- A predefined
root
role when configuring RBAC. - A role with
Role Management
permissions granted.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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"),
)
import weaviate, { WeaviateClient } from 'weaviate-client'
// Connect to Weaviate as root user
const client: WeaviateClient = await weaviate.connectToLocal({
authCredentials: new weaviate.ApiKey("user-a-key")
})
// Go support coming soon
// Java support coming soon
Role management
Create new roles with permissions
Permissions for these resource types can be assigned to roles:
Collections (collection definitions only, data object permissions are separate)
Create a role with Role Management
permissions
This example creates a role called testRole
with permissions to:
- Manage all roles starting with
testRole*
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const rolePermission = permissions.roles({
role: "testRole",
create: true,
read: true,
update: true,
delete: true,
})
await client.roles.create("testRole", rolePermission)
// Go support coming soon
// Java support coming soon
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const collectionPermissions = [
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
}),
]
await client.roles.create("testRole", collectionPermissions)
// Go support coming soon
// Java support coming soon
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const AddTenantPermissions = [
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
}),
]
await client.roles.create("testRole", AddTenantPermissions)
// Go support coming soon
// Java support coming soon
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const dataPermissions = [
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
}),
]
await client.roles.create("testRole", dataPermissions)
// Go support coming soon
// Java support coming soon
Create a role with Backups
permissions
This example creates a role called testRole
with permissions to:
- Manage backups for collections starting with
TargetCollection
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const backupsPermissions = [
permissions.backup({
collection: "TargetCollection*", // Applies to all collections starting with "TargetCollection"
manage: true, // Allow managing backups
}),
]
await client.roles.create("testRole", backupsPermissions)
// Go support coming soon
// Java support coming soon
Create a role with Cluster Data Access
permissions
This example creates a role called testRole
with permissions to:
- Read cluster metadata.
- Python Client v4
- JS/TS Client v3
- Go
- Java
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.cluster(read=True), # Allow reading cluster data
]
client.roles.create(role_name="testRole", permissions=permissions)
const { permissions } = weaviate
const clusterPermissions = [
permissions.cluster({
read: true // Allow reading cluster data
}),
]
await client.roles.create("testRole", clusterPermissions)
// Go support coming soon
// Java support coming soon
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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`
const { permissions } = weaviate
const verboseNodePermissions = [
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
const minimalNodePermissions = [
permissions.nodes.minimal({
read: true, // Allow reading node metadata
}),
]
await client.roles.create("testRole", verboseNodePermissions) // or `minimalNodePermissions`
// Go support coming soon
// Java support coming soon
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:
- Create new data in collections that start with
TargetCollection
- Python Client v4
- JS/TS Client v3
- Go
- Java
from weaviate.classes.rbac import Permissions
permissions = [
Permissions.data(collection="TargetCollection*", create=True),
]
client.roles.add_permissions(permissions=permissions, role_name="testRole")
const { permissions } = weaviate
const additionalDataPermissions = [
permissions.data({
collection: "TargetCollection*",
read: true,
create: true
}),
permissions.data({
collection: "TargetCollection*",
read: true,
create: false
}),
]
client.roles.addPermissions("testRole", additionalDataPermissions)
// Go support coming soon
// Java support coming soon
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
- Python Client v4
- JS/TS Client v3
- Go
- Java
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)
const { permissions } = weaviate
const permissionsToRemove = [
permissions.collections({
collection: "TargetCollection*",
read_config: true,
create_collection: true,
delete_collection: true,
}),
permissions.data({
collection: "TargetCollection*",
read: true,
create: false
}),
]
await client.roles.removePermissions("testRole", permissionsToRemove)
// Go support coming soon
// Java support coming soon
Check if a role exists
Check if the role testRole
exists:
- Python Client v4
- JS/TS Client v3
- Go
- Java
Inspect a role
View the permissions assigned to a role.
- Python Client v4
- JS/TS Client v3
- Go
- Java
test_role = client.roles.get(role_name="testRole")
print(test_role)
print(test_role.collections_permissions)
print(test_role.data_permissions)
const testRole = await client.roles.byName("testRole")
console.log(testRole)
console.log(testRole?.collectionsPermissions)
console.log(testRole?.dataPermissions)
// Go support coming soon
// Java support coming soon
List all roles
View all roles in the system and their permissions.
- Python Client v4
- JS/TS Client v3
- Go
- Java
List users with a role
List all users who have the role testRole
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
assigned_users = client.roles.get_assigned_user_ids(role_name="testRole")
for user in assigned_users:
print(user)
const assignedUsers = await client.roles.assignedUserIds("testRole")
for (const users of assignedUsers) {
console.log(users)
}
// Go support coming soon
// Java support coming soon
Delete a role
Deleting a role will remove it from the system, and revoke the associated permissions from all users who had this role.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
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
.
- Python Client v4
- JS/TS Client v3
- Go
- Java
Get the current user's roles and permissions
Retrieve the role and permission information for the currently authenticated user.
- Python Client v4
- JS/TS Client v3
- Go
- Java
Get a user's roles and permissions
Retrieve the role and permission information for any user.
- Python Client v4
- JS/TS Client v3
- Go
- Java
Additional resources
Questions and feedback
If you have any questions or feedback, let us know in the user forum.