**Role-Based Access Control (RBAC)** is a powerful security mechanism that allows you to manage who can access and modify your Weaviate instance. In this tutorial, you'll learn how to set up RBAC in Weaviate by defining roles with tailored permissions and assigning them to users. This enables granular control over operations, from reading and writing data to managing collections and tenants, ensuring that only authorized users can perform specific actions. In the steps that follow, we’ll cover: 1. **Connecting to Weaviate**\ Ensure you're authenticated with a user who has the necessary role management permissions. 2. **Creating custom roles**\ Define roles with specific permissions, such as read, write, tenant management, etc. 3. **Assigning roles to new users**\ Apply these roles to a new user and limit their access across different resources. ![RBAC Tutorial Diagram](/assets/docs/weaviate/tutorials/_includes/rbac-tutorial-diagram.png) By the end of this guide, you’ll have a clear roadmap for implementing RBAC in your Weaviate deployment, adding an essential layer of security to your AI powered applications. *** We are going to create the following roles: - **[Read and write permissions](#read-and-write-permissions):** `rw_role`\ Learn how to create a custom role that grants read and write access to collections and data, and assign it to a user. - **[Viewer permissions](#viewer-permissions):** `viewer_role`\ Set up a role that restricts users to read-only access for specific collections. - **[Tenant permissions](#tenant-permissions):** `tenant_manager`\ Configure roles with permissions to manage tenants, including creating, reading, and updating tenant information. ## Prerequisites Before starting this tutorial, ensure you have: - Docker for running a local Weaviate instance. - A preferred Weaviate [client library](../client-libraries/index.md) installed. ### Local instance - `root` user In order to follow the rest of the tutorial we will need to connect to Weaviate with a user who has the `root` role assigned. This will allow us to manage roles and permissions. Create a Docker Compose file (`docker-compose.yml`) and copy the following configuration: :::callout{intent="info" title="The environment variables in this configuration will:"} - Enable RBAC. - Configure `root-user` as a user with built-in root/admin permissions. ::: ```yaml --- services: weaviate: command: - --host - 0.0.0.0 - --port - '8080' - --scheme - http image: cr.weaviate.io/semitechnologies/weaviate:1.38.2 ports: - 8080:8080 - 50051:50051 volumes: - weaviate_data:/var/lib/weaviate restart: on-failure:0 environment: QUERY_DEFAULTS_LIMIT: 25 PERSISTENCE_DATA_PATH: '/var/lib/weaviate' CLUSTER_HOSTNAME: 'node1' AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false' AUTHORIZATION_ENABLE_RBAC: 'true' AUTHORIZATION_RBAC_ROOT_USERS: 'root-user' AUTHENTICATION_DB_USERS_ENABLED: 'true' AUTHENTICATION_APIKEY_ENABLED: 'true' AUTHENTICATION_APIKEY_USERS: 'root-user' AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'root-user-key' volumes: weaviate_data: ``` ::::callout{intent="info"} :::accordion{title="RBAC specific environment variables"} - `AUTHORIZATION_ENABLE_RBAC`: Enable RBAC to be used. - `AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED`: Enable/disable anonymous users from accessing your Weaviate instance. - `AUTHENTICATION_DB_USERS_ENABLED`: Enable/disable runtime user management. - `AUTHENTICATION_APIKEY_ENABLED`: Enable API key-based authentication. - `AUTHENTICATION_APIKEY_USERS`: The API-key based identities that correspond to the `AUTHENTICATION_APIKEY_ENABLED` variable. - `AUTHENTICATION_APIKEY_ALLOWED_KEYS`: The allowed API keys, they correspond to a specific user identity. - `AUTHORIZATION_RBAC_ROOT_USERS`: Define your root/admin user(s). More environment variables can be found [here](../database-configuration/overview.md). ::: :::: We will connect to Weaviate with `root-user`, and once we create a new role, we will also create a new user `custom-user` and assign the role to it. ## Read and write permissions ### Step 1: Connecting to Weaviate Ensure you are connected to Weaviate with a user possessing sufficient permissions to manage roles. You can achieve this by either using the predefined `root` role during [Weaviate configuration](../authorization-and-authentication/deploy-configuration-configuring-rbac.md) or by granting a user the [`manage_roles` permission](../authorization-and-authentication/weaviate-configuration-rbac-manage-roles.md#create-a-role-with-role-management-permissions). :::code-group{sync="languages"} ```python title="Python" import weaviate from weaviate.classes.init import Auth # Connect to Weaviate as root user client = weaviate.connect_to_local( ``` ```typescript title="JavaScript/TypeScript" import weaviate, { WeaviateClient } from 'weaviate-client' // Connect to Weaviate as root user const client: WeaviateClient = await weaviate.connectToLocal({ ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 2: Creating a new role with custom permissions This grants read and write permissions for collections starting with `TargetCollection`, and read permissions to nodes and cluster metadata. :::code-group{sync="languages"} ```python title="Python" from weaviate.classes.rbac import Permissions # Define permissions (example confers read+write rights to collections starting with "TargetCollection") permissions = [ # Collection level permissions Permissions.collections( collection="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 ), # Collection data level permissions Permissions.data( collection="TargetCollection*", create=True, # Allow data inserts read=True, # Allow query and fetch operations update=True, # Allow data updates delete=False, # Allow data deletes ), Permissions.backup(collection="TargetCollection*", manage=True), Permissions.Nodes.verbose(collection="TargetCollection*", read=True), Permissions.cluster(read=True), ] # Create a new role client.roles.create(role_name="rw_role", permissions=permissions) ``` ```typescript title="JavaScript/TypeScript" const { permissions } = weaviate ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 3: Assigning the role to a new user First, let's create the new user `custom-user`: :::code-group{sync="languages"} ```python title="Python" user_api_key = client.users.db.create(user_id="custom-user") print(user_api_key) ``` ```ts title="JavaScript/TypeScript" // TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: Now, you can assign the role `rw_role` to `custom-user`: :::code-group{sync="languages"} ```python title="Python" # Assign the role to a user client.users.db.assign_roles(user_id="custom-user", role_names=["rw_role"]) ``` ```typescript title="JavaScript/TypeScript" // Assign the role to a user await client.users.assignRoles(["rw_role"], "user-b",) ``` ```go title="Go" // Go support coming soon ``` ::: ## Viewer permissions ### Step 1: Connecing to Weaviate Ensure you are connected to Weaviate with a user possessing sufficient permissions to manage roles. You can achieve this by either using the predefined `root` role during [Weaviate configuration](../authorization-and-authentication/deploy-configuration-configuring-rbac.md) or by granting a user the [`manage_roles` permission](../authorization-and-authentication/weaviate-configuration-rbac-manage-roles.md#role-management). :::code-group{sync="languages"} ```python title="Python" import weaviate from weaviate.classes.init import Auth # Connect to Weaviate as root user client = weaviate.connect_to_local( ``` ```typescript title="JavaScript/TypeScript" import weaviate, { WeaviateClient } from 'weaviate-client' // Connect to Weaviate as root user const client: WeaviateClient = await weaviate.connectToLocal({ ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 2: Creating a new role with custom permissions This grants viewer permissions for collections starting with `TargetCollection`. :::code-group{sync="languages"} ```python title="Python" from weaviate.classes.rbac import Permissions # Define permissions (example confers viewer rights to collections starting with "TargetCollection") permissions = [ Permissions.collections( collection="TargetCollection*", read_config=True, ), Permissions.data(collection="TargetCollection*", read=True), ] # Create a new role client.roles.create(role_name="viewer_role", permissions=permissions) ``` ```typescript title="JavaScript/TypeScript" // Define permissions (example confers viewer rights to collections starting with "TargetCollection") const newPermissions = [ permissions.collections({ collection: "TargetCollection*", read_config: true, }), permissions.data({ collection: "TargetCollection*", read: true}), ] // Create a new role await client.roles.create("viewer_role", newPermissions) ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 3: Assigning the role to a new user First, let's create the new user `custom-user`: :::code-group{sync="languages"} ```python title="Python" user_api_key = client.users.db.create(user_id="custom-user") print(user_api_key) ``` ```ts title="JavaScript/TypeScript" // TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: Now, you can assign the role `viewer_role` to `custom-user`: :::code-group{sync="languages"} ```python title="Python" # Assign the role to a user client.users.db.assign_roles(user_id="custom-user", role_names="viewer_role") ``` ```typescript title="JavaScript/TypeScript" // Assign the role to a user await client.users.assignRoles("user-b", "viewer_role") ``` ```go title="Go" // Go support coming soon ``` ::: ## Tenant permissions ### Step 1: Connecting to Weaviate Ensure you are connected to Weaviate with a user possessing sufficient permissions to manage roles. You can achieve this by either using the predefined `root` role during [Weaviate configuration](../authorization-and-authentication/deploy-configuration-configuring-rbac.md) or by granting a user the [`manage_roles` permission](../authorization-and-authentication/weaviate-configuration-rbac-manage-roles.md#create-a-role-with-role-management-permissions). :::code-group{sync="languages"} ```python title="Python" import weaviate from weaviate.classes.init import Auth # Connect to Weaviate as root user client = weaviate.connect_to_local( ``` ```typescript title="JavaScript/TypeScript" import weaviate, { WeaviateClient } from 'weaviate-client' // Connect to Weaviate as root user const client: WeaviateClient = await weaviate.connectToLocal({ ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 2: Creating a new role with custom permissions This grants permissions to: - Completely manage tenants starting with `TargetTenant` in collections starting with `TargetCollection`. - Create, read, update and delete data for tenants starting with `TargetTenant` in collections starting with `TargetCollection`. :::code-group{sync="languages"} ```python title="Python" from weaviate.classes.rbac import Permissions permissions = [ Permissions.tenants( collection="TargetCollection*", # Applies to all collections starting with "TargetCollection" tenant="TargetTenant*", # Applies to all tenants starting with "TargetTenant" create=True, # Allow creating new tenants read=True, # Allow reading tenant info/metadata update=True, # Allow updating tenant states delete=True, # Allow deleting tenants ), Permissions.data( collection="TargetCollection*", # Applies to all collections starting with "TargetCollection" tenant="TargetTenant*", # Applies to all tenants starting with "TargetTenant" create=True, # Allow data inserts read=True, # Allow query and fetch operations update=True, # Allow data updates delete=True, # Allow data deletes ), ] # Create a new role client.roles.create(role_name="tenant_manager", permissions=permissions) ``` ```typescript title="JavaScript/TypeScript" const { permissions } = weaviate ``` ```go title="Go" // Go support coming soon ``` ::: ### Step 3: Assigning the role to a new user First, let's create the new user `custom-user`: :::code-group{sync="languages"} ```python title="Python" user_api_key = client.users.db.create(user_id="custom-user") print(user_api_key) ``` ```ts title="JavaScript/TypeScript" // TS support coming soon ``` ```go title="Go" // Go support coming soon ``` ::: Now, you can assign the role `tenant_manager` to `custom-user`: :::code-group{sync="languages"} ```python title="Python" # Assign the role to a user client.users.db.assign_roles(user_id="custom-user", role_names="tenant_manager") ``` ```typescript title="JavaScript/TypeScript" // Assign the role to a user client.users.assignRoles("user-b", "tenant_manager") ``` ```go title="Go" // Go support coming soon ``` ::: ## Summary This tutorial provides a comprehensive guide to configuring RBAC in Weaviate, helping you secure your vector database by managing user access with tailored roles and permissions. It walks you through connecting to Weaviate using a user with role management capabilities, then demonstrates how to create custom roles for different access levels. You’ll learn how to set up roles with read and write permissions to manage collections and data, configure viewer permissions for read-only access, and establish tenant permissions for managing tenant operations. ## Additional resources - [RBAC: Configuration](../authorization-and-authentication/deploy-configuration-configuring-rbac.md) - [RBAC: Manage roles](../authorization-and-authentication/weaviate-configuration-rbac-manage-roles.md) - [RBAC: Manage users](../authorization-and-authentication/weaviate-configuration-rbac-manage-users.md) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: :::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=