[v1.28] RBAC docs (#2866)

* Update authN doc (#2846) * Draft AuthZ page (#2847) * Draft AuthZ page * Update WCD notes * minor updates * Update examples * Minor update * Add permissions example * roles and permissions examples (#2856) * roles and permissions examples * adding last examples * fixing layout * resolving first comments * fixing code blocks * adding print statements * small fix * Minor edits * Add link to roles page from authz * Add note re RBAC performance * Updates re empty roles * Incorporate DK feedback * Minor change * Update text * minor edit to remove editor --------- Co-authored-by: Tuana Çelik <[email protected]>
weaviate · Dec 11, 2024 · 2a7c18f · 2a7c18f
1 parent c68620d
commit 2a7c18f
Show file tree

Hide file tree

Showing 3 changed files with 56 additions and 25 deletions.
diff --git a/_includes/code/python/howto.configure.rbac.permissions.py b/_includes/code/python/howto.configure.rbac.permissions.py
@@ -15,37 +15,46 @@ def reset_user(user: str):
         admin_client.roles.revoke(role_names=k, user=user)  # revoke all roles
 
 # =================================================================
-# =============== EXAMPLE: ADMIN PERMISSIONS
+# =============== EXAMPLE: READ + WRITE PERMISSIONS
 # =================================================================
 
 # Clean slate
 reset_user("other-user")
-admin_client.roles.delete("admin_role_target_collections")  # delete if exists
+admin_client.roles.delete("rw_role_target_collections")  # delete if exists
 
-# START AdminPermissionDefinition
-# Define permissions (example confers administrative rights to collections starting with "TargetCollection_")
+# START ReadWritePermissionDefinition
+# Define permissions (example confers read+write rights to collections starting with "TargetCollection_")
 admin_permissions = [
     Permissions.collections(
         collection="TargetCollection_*",
-        manage_collection=True,
+        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.data(collection="TargetCollection_*", manage=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="admin_role_target_collections", permissions=admin_permissions)
-admin_client.roles.assign(role_names="admin_role_target_collections", user="other-user")
-# END AdminPermissionDefinition
+admin_client.roles.create(role_name="rw_role_target_collections", permissions=admin_permissions)
+admin_client.roles.assign(role_names="rw_role_target_collections", user="other-user")
+# END ReadWritePermissionDefinition
 
 # ===== TEST ===== basic checks to see if the role was created
 user_permissions = admin_client.roles.by_user("other-user")
 
-assert "admin_role_target_collections" in user_permissions.keys()
-assert user_permissions["admin_role_target_collections"].collections_permissions[0].collection == "TargetCollection_*"
-assert user_permissions["admin_role_target_collections"].name == "admin_role_target_collections"
+assert "rw_role_target_collections" in user_permissions.keys()
+assert user_permissions["rw_role_target_collections"].collections_permissions[0].collection == "TargetCollection_*"
+assert user_permissions["rw_role_target_collections"].name == "rw_role_target_collections"
 
 # =================================================================
 # =============== EXAMPLE: VIEWER PERMISSIONS
@@ -73,7 +82,7 @@ def reset_user(user: str):
 # ===== TEST ===== basic checks to see if the role was created
 user_permissions = admin_client.roles.by_user("other-user")
 
-assert "admin_role_target_collections" in user_permissions.keys()
+assert "viewer_role_target_collections" in user_permissions.keys()
 assert user_permissions["viewer_role_target_collections"].collections_permissions[0].collection == "TargetCollection_*"
 assert user_permissions["viewer_role_target_collections"].name == "viewer_role_target_collections"
 

diff --git a/developers/weaviate/configuration/authorization.md b/developers/weaviate/configuration/authorization.md
@@ -87,8 +87,11 @@ RBAC access will be available in WCD in a future release.
 
 ## Role-Based Access Control (RBAC)
 
-:::info Added in `v1.28` as a preview feature
-Role-Based Access Control (RBAC) is in technical preview in Weaviate `v1.28`. This feature is still under development and may change in future versions.
+:::caution 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.**
+<br/>
+
+We appreciate [your feedback](https://forum.weaviate.io/) 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](./roles.md) and assign permissions to those roles. Users can then be assigned to roles, and inherit the permissions associated with those roles.

diff --git a/developers/weaviate/configuration/roles.md b/developers/weaviate/configuration/roles.md
@@ -10,13 +10,20 @@ import TabItem from '@theme/TabItem';
 import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock';
 import PyCode from '!!raw-loader!/_includes/code/python/howto.configure.rbac.permissions.py';
 
+:::caution 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.**
+<br/>
+
+We appreciate [your feedback](https://forum.weaviate.io/) on this feature.
+:::
+
 Weaviate provides differentiated access through [authorization](./authorization.md) levels, based on the [authenticated](./authentication.md) 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, directly through the REST API or through the client libraries.
+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](../api/rest.md) for concrete examples on how to manage roles.
+Refer to the client library examples below, or [the REST API documentation](../api/rest.md) for concrete examples on how to manage roles and permissions.
 
 ## Roles
 
@@ -27,7 +34,9 @@ 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.
+`admin` and `viewer` roles can be assigned through the Weaviate configuration file. Once a role is assigned to a user through the configuration file, it cannot be modified. The user also cannot 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](./authorization.md) page for more information on how to assign predefined roles to users.
 
@@ -76,19 +85,29 @@ Permissions can be defined for the following resources:
 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
 
-### Administrative permissions
+### Read and write permissions
 
-This confers administrative permissions for collections starting with `TargetCollection_`, and read permissions to nodes and cluster metadata.
+This confers read and write permissions for collections starting with `TargetCollection_`, and read permissions to nodes and cluster metadata.
 
 <Tabs groupId="languages">
 
   <TabItem value="py" label="Python Client v4">
     <FilteredTextBlock
       text={PyCode}
-      startMarker="# START AdminPermissionDefinition"
-      endMarker="# END AdminPermissionDefinition"
+      startMarker="# START ReadWritePermissionDefinition"
+      endMarker="# END ReadWritePermissionDefinition"
       language="py"
     />
   </TabItem>
@@ -384,9 +403,9 @@ This example removes from the "devrel" role permissions to:
 
 ### Assign a role to a user
 
-A custom user can have any number of roles assigned to them (including none).
+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 "devrel" role to "jane-doe".
+This example assigns the custom "devrel" role to "jane-doe".
 
 <Tabs groupId="languages">
 
@@ -669,7 +688,7 @@ View all roles in the system and their permissions.
 
 ### Delete a role
 
-Deleting a role will remove it from the system, and revoke all permissions associated with it.
+Deleting a role will remove it from the system, and revoke the associated permissions from all users had this role.
 
 <Tabs groupId="languages">