diff --git a/v2.5.x/assets/privilege_group_illustrated.png b/v2.5.x/assets/privilege_group_illustrated.png new file mode 100644 index 000000000..03378f93a Binary files /dev/null and b/v2.5.x/assets/privilege_group_illustrated.png differ diff --git a/v2.5.x/assets/users_roles_privileges.png b/v2.5.x/assets/users_roles_privileges.png new file mode 100644 index 000000000..f1d51ca08 Binary files /dev/null and b/v2.5.x/assets/users_roles_privileges.png differ diff --git a/v2.5.x/site/en/adminGuide/drop_users_roles.md b/v2.5.x/site/en/adminGuide/drop_users_roles.md new file mode 100644 index 000000000..b56181e79 --- /dev/null +++ b/v2.5.x/site/en/adminGuide/drop_users_roles.md @@ -0,0 +1,232 @@ +--- +id: drop_users_roles.md +related_key: enable RBAC +summary: To ensure data security, it is recommend that you drop users and roles that are no longer in use. This guide introduces how to drop users and roles.​ +title: Drop Users & Roles​ +--- + +# Drop Users & Roles​ + +To ensure data security, it is recommend that you drop users and roles that are no longer in use. This guide introduces how to drop users and roles.​ + +## Drop a user​ + +The following example demonstrates how to drop the user `user_1`. ​ + +
+ +The `root` user cannot be dropped.​ + +
+ +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client = MilvusClient(​ + uri="http://localhost:19530",​ + token="root:Milvus"​ +)​ +​ +# create a user​ +client.drop_user(user_name="user_1")​ + +``` + +```java +import io.milvus.v2.client.ConnectConfig​ +import io.milvus.v2.client.MilvusClientV2​ +import io.milvus.v2.service.rbac.request.DropUserReq​ +​ +ConnectConfig connectConfig = ConnectConfig.builder()​ + .uri("http://localhost:19530")​ + .token("root:Milvus")​ + .build();​ + ​ +MilvusClientV2 client = new MilvusClientV2(connectConfig);​ +​ +DropUserReq dropUserReq = DropUserReq.builder()​ + .userName("user_1")​ + .build();​ +client.dropUser(dropUserReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +const address = "http://localhost:19530";​ +const token = "root:Milvus";​ +const client = new MilvusClient({address, token});​ +​ +milvusClient.deleteUser({​ + username: 'user_1'​ +})​ + +``` + +```shell +export CLUSTER_ENDPOINT="http://localhost:19530"​ +export TOKEN="root:Milvus"​ +​ +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/drop" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "userName": "user_1"​ +}'​ + +``` + +Once the user is dropped, you can list all existing users to check if the drop operation is successful. ​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.list_users()​ + +``` + +```java +import io.milvus.v2.service.rbac.request.listUsersReq​ +​ +List resp = client.listUsers();​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +milvusClient.listUsers()​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/list" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{}'​ + +``` + +Below is an example output. There is no `user_1` in the list. The drop operation is successful.​ + +``` +['root']​ + +``` + +## Drop a role​ + +The following example demonstrates how to drop the role `role_a`.​ + +
+ +The built-in role `admin` cannot be dropped.​ + +
+ +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.drop_role(role_name="role_a")​ + +``` + +```java +import io.milvus.v2.service.rbac.request.DropRoleReq​ +​ +DropRoleReq dropRoleReq = DropRoleReq.builder()​ + .roleName("role_a")​ + .build();​ +client.dropRole(dropRoleReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +milvusClient.dropRole({​ + roleName: 'role_a',​ + })​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/drop" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "roleName": "role_a"​ +}'​ + +``` + +Once the role is dropped, you can list all existing roles to check if the drop operation is successful. ​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.list_roles()​ + +``` + +```java +List resp = client.listRoles();​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +milvusClient.listRoles(​ + includeUserInfo: True​ +)​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/list" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{}'​ + +``` + +Below is an example output. There is no `role_a` in the list. The drop operation is successful.​ + +``` +['admin']​ + +``` \ No newline at end of file diff --git a/v2.5.x/site/en/adminGuide/grant_privileges.md b/v2.5.x/site/en/adminGuide/grant_privileges.md new file mode 100644 index 000000000..f5ea0d796 --- /dev/null +++ b/v2.5.x/site/en/adminGuide/grant_privileges.md @@ -0,0 +1,755 @@ +--- +id: grant_privileges.md +related_key: enable RBAC +summary: Once a role is created, you can grant privileges to the role. This guide introduces how to grant privileges or privilege groups to a role.​ +title: Grant Privilege or Privilege Group to Roles​ +--- + +# Grant Privilege or Privilege Group to Roles​ + +Once a role is created, you can grant privileges to the role. This guide introduces how to grant privileges or privilege groups to a role.​ + +## Grant a privilege or a privilege group to a role​ + +Milvus 2.5 introduces a new version of API which streamlines the grant operation. You no longer need to look up the object type when granting a privilege to a role. The following are the parameters and corresponding explanations.​ + +- **role_name:** The name of the target role to which privilege(s) or privilege group(s) need to be granted.​ + +- **Resource**: The target resource of a privilege, which can be a specific instance, database or collection. The following table explains how to specify the resource in the `client.grantV2()` method.​ + +

Level​

+ +

Resource​

+ +

Grant Method​

+ +

Notes​

+ +

Collection​

+ +

​

+ +

A specific collection​

+ +

​

+ +

client.grant_privilege_v2(role_name="roleA", privilege="CollectionAdmin", collection_name="col1", db_name="db1")​

+ +

Input the name of your target collection and the name of the database to which the target collection belongs.​

+ +

​

+ +

All collections under a specific database​

+ +

client.grant_privilege_v2(role_name="roleA", privilege="CollectionAdmin", collection_name="*", db_name="db1")​

+ +

Input the name of your target database and a wildcard `*` as the collection name.​

+ +

**Database**​

+ +

A specific database​

+ +

client.grant_privilege_v2(role_name="roleA", privilege="DatabaseAdmin", collection_name="*", db_name="db1")​

+ +

Input the name of your target database and a wildcard `*` as the collection name.​

+ +

​

+ +

All databases under the current instance​

+ +

client.grant_privilege_v2(role_name="roleA", privilege="DatabaseAdmin", collection_name="*", db_name="*")​

+ +

Input `*` as the database name and `*` as the collection name.​

+ +

**Instance**​

+ +

The current instance​

+ +

client.grant_privilege_v2(role_name="roleA", privilege="ClusterAdmin", collection_name="*", db_name="*")​

+ +

Input `*` as the database name and `*` as the collection name.​

+ +
+ +- **Privilege**: The specific privilege or [privilege group](https://zilliverse.feishu.cn/wiki/GpoUwWH7kiAF3bkKqokcTAS4n5d) that you need to grant to a role. Currently, Milvus provides 56 types of privileges that you can grant. The table below lists the privileges in Milvus.​ + +
+ + The type column in the table below are user to facilitate your quick lookup for privileges and is used for classification purposes only. When granting privileges, you do not need to understand the types. You just need to input the corresponding privileges.​ + +
+ +

**Type **​

+ +

**Privilege**​

+ +

**Description**​

+ +

**Relevant API description on the client side**​

+ +

Database Privileges​

+ +

ListDatabases​

+ +

View all databases in the current instance​

+ +

[ListDatabases](https://milvus.io/docs/manage_databases.md)​

+ +

DescribeDatabase​

+ +

View the details of a database​

+ +

[DescribeDatabase](https://milvus.io/docs/manage_databases.md)​

+ +

CreateDatabase​

+ +

Create a database​

+ +

[CreateDatabase](https://milvus.io/docs/manage_databases.md)​

+ +

DropDatabase​

+ +

Drop a database​

+ +

[DropDatabase](https://milvus.io/docs/manage_databases.md)​

+ +

AlterDatabase​

+ +

Modify the properties of a database​

+ +

[AlterDatabase](https://milvus.io/docs/manage_databases.md)​

+ +

Collection Privileges​

+ +

​

+ +

GetFlushState​

+ +

Check the status of the collection flush operation​

+ +

[GetFlushState](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/Collection/flush.md)​

+ +

GetLoadState​

+ +

Check the load status of a collection​

+ +

[GetLoadState](https://milvus.io/api-reference/restful/v2.5.x/v2/Collection%20(v2)/Get%20Load%20State.md)​

+ +

GetLoadingProgress​

+ +

Check the loading progress of a collection​

+ +

[GetLoadingProgress](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/utility/loading_progress.md)​

+ +

ShowCollections​

+ +

View all collections with collection privileges​

+ +

[ShowCollections](https://milvus.io/docs/view-collections.md)​

+ +

ListAliases​

+ +

View all aliases of a collection​

+ +

[ListAliases](https://milvus.io/api-reference/pymilvus/v2.5.x/MilvusClient/Collections/list_aliases.md)​

+ +

DescribeCollection​

+ +

View the details of a collection​

+ +

[DescribeCollection](https://milvus.io/api-reference/pymilvus/v2.5.x/MilvusClient/Collections/describe_collection.md)​

+ +

DescribeAlias​

+ +

View the details of an alias​

+ +

[DescribeAlias](https://milvus.io/api-reference/pymilvus/v2.5.x/MilvusClient/Collections/describe_alias.md)​

+ +

GetStatistics​

+ +

Obtain the statistics of a collection (eg. The number of entities in a collection)​

+ +

[GetCollectionStatistics](https://milvus.io/api-reference/pymilvus/v2.5.x/MilvusClient/Collections/get_collection_stats.md)​

+ +

CreateCollection​

+ +

Create a collection​

+ +

[CreateCollection](https://milvus.io/docs/create-collection.md)​

+ +

DropCollection​

+ +

Drop a collection​

+ +

[DropCollection](https://milvus.io/docs/drop-collection.md)​

+ +

Load​

+ +

Load a collection​

+ +

[LoadCollection](https://milvus.io/docs/load-and-release.md)/[GetLoadingProgress](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/utility/loading_progress.md)/[GetLoadState](https://milvus.io/api-reference/restful/v2.5.x/v2/Collection%20(v2)/Get%20Load%20State.md)​

+ +

Release​

+ +

Release a collection​

+ +

[ReleaseCollection](https://milvus.io/docs/load-and-release.md)​

+ +

Flush​

+ +

​

+ +

Persist all entities in a collection to a sealed segment. Any entity inserted after the flush operation will be stored in a new segment.​

+ +

[Flush](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/Collection/flush.md)/[GetFlushState](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/Collection/flush.md)​

+ +

Compaction​

+ +

Manually trigger compaction​

+ +

[Compact](https://milvus.io/docs/v2.0.x/compact_data.md)​

+ +

RenameCollection​

+ +

Rename a collection​

+ +

[RenameCollection](https://milvus.io/docs/modify-collection.md)​

+ +

CreateAlias​

+ +

Create an alias for a collection​

+ +

[CreateAlias](https://milvus.io/docs/manage-aliases.md)​

+ +

DropAlias​

+ +

Drop the alias of a collection​

+ +

[DropAlias](https://milvus.io/docs/manage-aliases.md)​

+ +

FlushAll​

+ +

Flush all collections in a database​

+ +

[FlushAll](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/utility/flush_all.md)​

+ +

Partition Privileges​

+ +

HasPartition​

+ +

Check whether a partition exists​

+ +

[HasPartition](https://milvus.io/docs/manage-partitions.md)​

+ +

ShowPartitions​

+ +

View all partitions in a collection​

+ +

[ShowPartitions](https://milvus.io/docs/manage-partitions.md)​

+ +

CreatePartition​

+ +

Create a partition​

+ +

[CreatePartition](https://milvus.io/docs/manage-partitions.md)​

+ +

DropPartition​

+ +

Drop a partition​

+ +

[DropPartition](https://milvus.io/docs/manage-partitions.md)​

+ +

Index Privileges​

+ +

IndexDetail​

+ +

View the details of an index​

+ +

​

+ +

[DescribeIndex/GetIndexState/GetIndexBuildProgress](https://milvus.io/docs/index-vector-fields.md?tab=floating)​

+ +

CreateIndex​

+ +

Create an index​

+ +

[CreateIndex](https://milvus.io/docs/index-vector-fields.md?tab=floating)​

+ +

DropIndex​

+ +

Drop an index​

+ +

[DropIndex](https://milvus.io/docs/index-vector-fields.md?tab=floating)​

+ +

Resource Management Privileges​

+ +

​

+ +

LoadBalance​

+ +

Achieve load balance​

+ +

[LoadBalance](https://milvus.io/docs/resource_group.md)​

+ +

CreateResourceGroup​

+ +

Create a resource group​

+ +

[CreateResourceGroup](https://milvus.io/api-reference/pymilvus/v2.5.x/ORM/utility/create_resource_group.md)​

+ +

DropResourceGroup​

+ +

Drop a resource group​

+ +

[DropResourceGroup](https://milvus.io/docs/resource_group.md)​

+ +

UpdateResourceGroups​

+ +

Update a resource group​

+ +

[UpdateResourceGroups](https://milvus.io/docs/resource_group.md)​

+ +

DescribeResourceGroup​

+ +

View the details of a resource group​

+ +

[DescribeResourceGroup](https://milvus.io/docs/resource_group.md)​

+ +

ListResourceGroups​

+ +

View all resource groups of the current instance​

+ +

[ListResourceGroups](https://milvus.io/docs/resource_group.md)​

+ +

TransferNode​

+ +

Transfer nodes between resource groups​

+ +

[TransferNode](https://milvus.io/docs/resource_group.md)​

+ +

TransferReplica​

+ +

Transfer replicas between resource groups​

+ +

[TransferReplica](https://milvus.io/docs/resource_group.md)​

+ +

BackupRBAC​

+ +

Create a backup for all RBAC related operations in the current instance​

+ +

BackupRBAC​

+ +

RestoreRBAC​

+ +

Restore a backup of all RBAC related operations in the current instance​

+ +

RestoreRBAC​

+ +

Entity Privileges​

+ +

​

+ +

Query​

+ +

Conduct a query​

+ +

[Query](https://milvus.io/docs/get-and-scalar-query.md)​

+ +

Search​

+ +

Conduct a search​

+ +

[Search](https://milvus.io/docs/single-vector-search.md)​

+ +

Insert​

+ +

Insert entities​

+ +

[Insert](https://milvus.io/docs/insert-update-delete.md)​

+ +

Delete​

+ +

Delete entities​

+ +

[Delete](https://milvus.io/docs/delete-entities.md)​

+ +

Upsert​

+ +

Upsert entities​

+ +

[Upsert](https://milvus.io/docs/upsert-entities.md)​

+ +

Import​

+ +

Bulk insert or import entities​

+ +

[BulkInsert/Import](https://milvus.io/docs/import-data.md)​

+ +

RBAC Privileges​

+ +

CreateOwnership​

+ +

Create a user or a role​

+ +

[CreateUser/CreateRole](https://zilliverse.feishu.cn/wiki/CnzkwQBW3i7bE3kVtLzcqQLtn9d)​

+ +

UpdateUser​

+ +

Update the password of a user​

+ +

[UpdateCredential](https://zilliverse.feishu.cn/wiki/CnzkwQBW3i7bE3kVtLzcqQLtn9d)​

+ +

DropOwnership​

+ +

Drop a user password or a role​

+ +

[DeleteCredential/DropRole](https://zilliverse.feishu.cn/wiki/OqZnwJHrJilLPukfvp5cSgnmnTh)​

+ +

SelectOwnership​

+ +

View all users that are granted a specific role ​

+ +

[SelectRole/SelectGrant](https://zilliverse.feishu.cn/wiki/ZsNZwn1MkiOtH9kFU35cyRgVnue)​

+ +

ManageOwnership​

+ +

Manage a user or a role or grant a role to a user​

+ +

[OperateUserRole/OperatePrivilege/OperatePrivilegeV2](https://zilliverse.feishu.cn/wiki/ZsNZwn1MkiOtH9kFU35cyRgVnue)​

+ +

SelectUser​

+ +

View all roles granted to a user​

+ +

[SelectUser](https://zilliverse.feishu.cn/wiki/ZsNZwn1MkiOtH9kFU35cyRgVnue)​

+ +

CreatePrivilegeGroup​

+ +

Create a privilege group​

+ +

[CreatePrivilegeGroup](https://zilliverse.feishu.cn/wiki/FpV8wdWcZiDwnQkBloucYF7wnUg)​

+ +

DropPrivilegeGroup​

+ +

Drop a privilege group​

+ +

[DropPrivilegeGroup](https://zilliverse.feishu.cn/wiki/FpV8wdWcZiDwnQkBloucYF7wnUg)​

+ +

ListPrivilegeGroups​

+ +

View all privilege groups in the current instance​

+ +

[ListPrivilegeGroups](https://zilliverse.feishu.cn/wiki/FpV8wdWcZiDwnQkBloucYF7wnUg)​

+ +

OperatePrivilegeGroup​

+ +

Add privileges to or remove privileges from a privilege group​

+ +

[OperatePrivilegeGroup](https://zilliverse.feishu.cn/wiki/FpV8wdWcZiDwnQkBloucYF7wnUg)​

+ +
+ +The following example demonstrates how to grant the privilege `PrivilegeSearch` on `collection_01` under the default database as well as a privilege group named `privilege_group_1` to the role `role_a`. + +
+ Python + Java + Go + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient + +client = MilvusClient( + uri="http://localhost:19530", + token="root:Milvus" +) + +client.grant_privilege_v2( + role_name="role_a", + privilege="Search" + collection_name='collection_01' + db_name='default', +) + +client.grant_privilege_v2( + role_name="role_a", + privilege="privilege_group_1" + collection_name='collection_01' + db_name='default', +) + +client.grant_privilege_v2( + role_name="role_a", + privilege="ClusterReadOnly" + collection_name='*' + db_name='*', +) +``` + +```java +import io.milvus.v2.service.rbac.request.GrantPrivilegeReqV2 + +client.grantPrivilegeV2(GrantPrivilegeReqV2.builder() + .roleName("role_a") + .privilege("Search") + .collectionName("collection_01") + .dbName("default") + .build()); + +client.grantPrivilegeV2(GrantPrivilegeReqV2.builder() + .roleName("role_a") + .privilege("privilege_group_1") + .collectionName("collection_01") + .dbName("default") + .build()); + +client.grantPrivilegeV2(GrantPrivilegeReqV2.builder() + .roleName("role_a") + .privilege("ClusterReadOnly") + .collectionName("*") + .dbName("*") + .build()); +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client" + +client.GrantV2(context.Background(), "role_a", "collection_01", "Search", entity.WithOperatePrivilegeDatabase("default")) + +client.GrantV2(context.Background(), "role_a", "collection_01", "privilege_group_1", entity.WithOperatePrivilegeDatabase("default")) + +client.GrantV2(context.Background(), "role_a", "*", "ClusterReadOnly", entity.WithOperatePrivilegeDatabase("*")) +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node") + +const address = "http://localhost:19530"; +const token = "root:Milvus"; +const client = new MilvusClient({address, token}); + +await milvusClient.grantPrivilege({ + roleName: 'role_a', + object: 'Collection', + objectName: 'collection_01', + privilegeName: 'Search' + }); +``` + +```shell +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/grant_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "Search", + "collectionName": "collection_01", + "dbName":"default" +}' + +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/grant_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "privilege_group_1", + "collectionName": "collection_01", + "dbName":"default" +}' + +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/grant_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "ClusterReadOnly", + "collectionName": "*", + "dbName":"*" +}' +``` + +## Describe a role + +The following example demonstrates how to view the privileges granted to the role role_a using the describe_role method. + +
+ Python + Java + Go + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient + +client.describe_role(role_name="role_a") +``` + +```java +import io.milvus.v2.service.rbac.response.DescribeRoleResp; +import io.milvus.v2.service.rbac.request.DescribeRoleReq + +DescribeRoleReq describeRoleReq = DescribeRoleReq.builder() + .roleName("role_a") + .build(); +DescribeRoleResp resp = client.describeRole(describeRoleReq); +List infos = resp.getGrantInfos(); +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client" + +client.ListRoles(context.Background()) +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node") + +await milvusClient.describeRole({roleName: 'role_a'}); +``` + +```shell +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/describe" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a" +}' +``` + +Below is an example output. + +```json +{ + "role": "role_a", + "privileges": [ + { + "collection_name": "collection_01", + "db_name": "default", + "role_name": "role_a", + "privilege": "Search", + "grantor_name": "root" + }, + "privilege_group_1" + ] +} +``` + +## Revoke a privilege or a privilege group from a role + +The following example demonstrates how to revoke the privilege `PrivilegeSearch` on `collection_01` under the default database as well as the privilege group `privilege_group_1` that have been granted to the role `role_a`. + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient + +client = MilvusClient( + uri="http://localhost:19530", + token="root:Milvus" +) + +client.revoke_privilege_v2( + role_name="role_a", + privilege="Search" + collection_name='collection_01' + db_name='default', +) + +client.revoke_privilege_v2( + role_name="role_a", + privilege="privilege_group_1" + collection_name='collection_01' + db_name='default', +) + +client.revoke_privilege_v2( + role_name="role_a", + privilege="ClusterReadOnly" + collection_name='*' + db_name='*', +) +``` + +```java +import io.milvus.v2.service.rbac.request.RevokePrivilegeReqV2 + +client.revokePrivilegeV2(RevokePrivilegeReqV2.builder() + .roleName("role_a") + .privilege("Search") + .collectionName("collection_01") + .dbName("default") + .build()); + +client.revokePrivilegeV2(RevokePrivilegeReqV2.builder() + .roleName("role_a") + .privilege("privilege_group_1") + .collectionName("collection_01") + .dbName("default") + .build()); + +client.revokePrivilegeV2(RevokePrivilegeReqV2.builder() + .roleName("role_a") + .privilege("ClusterReadOnly") + .collectionName("*") + .dbName("*") + .build()); +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client" + +client.RevokeV2(context.Background(), "role_a", "collection_01", "Search", entity.WithOperatePrivilegeDatabase("default")) + +client.RevokeV2(context.Background(), "role_a", "collection_01", "privielge_group_1", entity.WithOperatePrivilegeDatabase("default")) + +client.RevokeV2(context.Background(), "role_a", "*", "ClusterReadOnly", entity.WithOperatePrivilegeDatabase("*")) +``` + +```shell +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/revoke_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "Search", + "collectionName": "collection_01", + "dbName":"default" +}' + +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/revoke_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "Search", + "collectionName": "collection_01", + "dbName":"default" +}' + +curl --request POST \ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/revoke_privilege_v2" \ +--header "Authorization: Bearer ${TOKEN}" \ +--header "Content-Type: application/json" \ +-d '{ + "roleName": "role_a", + "privilege": "ClusterReadOnly", + "collectionName": "*", + "dbName":"*" +}' +``` diff --git a/v2.5.x/site/en/adminGuide/grant_roles.md b/v2.5.x/site/en/adminGuide/grant_roles.md new file mode 100644 index 000000000..0a1fe9dee --- /dev/null +++ b/v2.5.x/site/en/adminGuide/grant_roles.md @@ -0,0 +1,197 @@ +--- +id: grant_roles.md +related_key: enable RBAC +summary: After creating a role and granting privileges to the role, you can grant the role to users so that the users can access resources and perform actions that are defined by the role. You can grant multiple roles to a user or grant a role to multiple users. This guide introduces how to grant roles to users.​ +title: Grant Roles to Users​ +--- + +# Grant Roles to Users​ + +After creating a role and granting privileges to the role, you can grant the role to users so that the users can access resources and perform actions that are defined by the role. You can grant multiple roles to a user or grant a role to multiple users. This guide introduces how to grant roles to users.​ + +The built-in user `root` in Milvus has already been granted the `admin` role, which has all privileges. You do not need to assign any other roles to it.​ + +## Grant a role to a user​ + +The following example demonstrates how to grant the role `role_a` to the user `user_1`.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client = MilvusClient(​ + uri="http://localhost:19530",​ + token="root:Milvus"​ +)​ +​ +client.grant_role(user_name="user_1", role_name="role_a")​ + +``` + +```java +import io.milvus.v2.client.ConnectConfig;​ +import io.milvus.v2.client.MilvusClientV2;​ +import io.milvus.v2.service.rbac.request.GrantRoleReq;​ +​ +String CLUSTER_ENDPOINT = "http://localhost:19530";​ +String TOKEN = "root:Milvus";​ +​ +​ +ConnectConfig connectConfig = ConnectConfig.builder()​ + .uri(CLUSTER_ENDPOINT)​ + .token(TOKEN)​ + .build();​ + ​ +MilvusClientV2 client = new MilvusClientV2(connectConfig);​ +​ +GrantRoleReq grantRoleReq = GrantRoleReq.builder()​ + .roleName("role_a")​ + .userName("user_1")​ + .build();​ +client.grantRole(grantRoleReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +const address = "http://localhost:19530";​ +const token = "root:Milvus";​ +const client = new MilvusClient({address, token});​ +​ +milvusClient.grantRole({​ + username: 'user_1',​ + roleName: 'role_a'​ + })​ + +``` + +```shell +export CLUSTER_ENDPOINT="http://localhost:19530"​ +export TOKEN="root:Milvus"​ +​ +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/grant_role" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "roleName": "role_a",​ + "userName": "user_1"​ +}'​ + +``` + +## Describe user​ + +Once you grant a role to a user, you can check if the grant operation is successful via the `describe_user()` method.​ + +The following example demonstrates how to check the role(s) of the user `user_1`.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.describe_user(user_name="user_1")​ + +``` + +```java +import io.milvus.v2.service.rbac.request.DescribeUserReq;​ +import io.milvus.v2.service.rbac.response.DescribeUserResp;​ +​ +DescribeUserReq describeUserReq = DescribeUserReq.builder()​ + .userName("user_1")​ + .build();​ +DescribeUserResp describeUserResp = client.describeUser(describeUserReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +milvusClient.describeUser({username: 'user_1'})​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/describe" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "userName": "user_1"​ +}'​ + +``` + +Below is an example output.​ + +``` +{'user_name': 'user_1', 'roles': 'role_a'}​ + +``` + +## Revoke a role​ + +You can also revoke a role that has been assigned to a user.​ + +The following example demonstrates how to revoke the role `role_a` assigned to the user `user_1`.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.revoke_role(​ + user_name='user_1',​ + role_name='role_a'​ +)​ + +``` + +```java +import io.milvus.v2.service.rbac.request.RevokeRoleReq;​ +​ +client.revokeRole(RevokeRoleReq.builder()​ + .userName("user_1")​ + .roleName("role_a")​ + .build());​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/revoke_role" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "userName": "user_1",​ + "roleName": "role_a"​ +}'​ + +``` + diff --git a/v2.5.x/site/en/adminGuide/privilege_group.md b/v2.5.x/site/en/adminGuide/privilege_group.md new file mode 100644 index 000000000..1c3c9f825 --- /dev/null +++ b/v2.5.x/site/en/adminGuide/privilege_group.md @@ -0,0 +1,780 @@ +--- +id: privilege_group.md +related_key: enable RBAC +summary: To streamline the process of granting privileges, it is recommended that you combine multiple privileges into a privilege group.​ +title: Create Privilege Group +--- + +# Create Privilege Group​ + +To streamline the process of granting privileges, it is recommended that you combine multiple privileges into a privilege group.​ + +## Privilege group vs. privileges​ + +A privilege group consists of multiple privileges.​ + +![Privilege group illustrated](../../../assets/privilege_group_illustrated.png) + +As shown in the figure above, suppose you need to grant three different privileges to a role.​ + +- If you do not use a privilege group, you need to grant the privileges three times.​ + +- If you use a privilege group, you only need to create a privilege group and add the three privileges to this privilege group and grant the privilege group to Role A.​ + +By using a privilege group, you can grant multiple privileges in bulk to a role.​ + +## Built-in privilege groups​ + +For ease-of-use, Milvus provides a total of 9 built-in privileges on the collection, database, and instance level: COLL_RO, COLL_RW, COLL_ADMIN, DB_RO, DB_RW, DB_Admin, Cluster_RO, Cluster_RW and Cluster_Admin.​ + +
+ +The three levels of built-in privilege groups do not have a cascading relationship. Setting a privilege group at the instance level does not automatically set permissions for all databases and collections under that instance. Privileges at the database and collection levels need to be set manually.​ + +
+ +The following tables explains the privileges includes in each of the built-in privilege group.​ + +### Collection level​ + +- **COLL_RO**: includes privileges to read collection data​ + +- **COLL_RW**: includes privileges to read and write collection data​ + +- **COLL_ADMIN**: includes privileges to read and write collection data and manage collections.​ + +The table below lists the specific privileges included in the three built-in privilege groups at the collection level:​ + +

**Privilege**​

+ +

**CollectionReadOnly**​

+ +

**CollectionReadWrite**​

+ +

**CollectionAdmin**​

+ +

Query​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

Search​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

IndexDetail​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

GetFlushState​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

GetLoadState​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

GetLoadingProgress​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

HasPartition​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

ShowPartitions​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

ListAliases​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

DescribeCollection​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

DescribeAlias​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

GetStatistics​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

CreateIndex​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

DropIndex​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

CreatePartition​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

DropPartition​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Load​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Release​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Insert​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Delete​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Upsert​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Import​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Flush​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

Compaction​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

LoadBalance​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

CreateAlias​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropAlias​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +
+ +### Database level​ + +- **DB_RO**: includes privileges to read database data​ + +- **DB_RW**: includes privileges to read and write database data​ + +- **DB_Admin**: includes privileges to read and write database data and manage databases.​ + +The table below lists the specific privileges included in the three built-in privilege groups at the database level:​ + +

**Privilege**​

+ +

**DatabaseReadOnly**​

+ +

**DatabaseReadWrite**​

+ +

**DatabaseAdmin**​

+ +

ShowCollections​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

DescribeDatabase​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

CreateCollection​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropCollection​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

AlterDatabase​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +
+ +### Cluster level​ + +- **Cluster_RO**: includes privileges to read instnace data​ + +- **Cluster_RW**: includes privileges to read and write instance data​ + +- **Cluster_Admin**: includes privileges to read and write instance data and manage instances.​ + +The table below lists the specific privileges included in the three built-in privilege groups at the instance level:​ + +

**Privilege**​

+ +

**ClusterReadOnly**​

+ +

**ClusterReadWrite**​

+ +

**ClusterAdmin**​

+ +

ListDatabases​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

RenameCollection​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

CreateOwnership​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

UpdateUser​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropOwnership​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

SelectOwnership​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

ManageOwnership​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

SelectUser​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

BackupRBAC​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

RestoreRBAC​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

CreateResourceGroup​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropResourceGroup​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

UpdateResourceGroups​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

DescribeResourceGroup​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

ListResourceGroups​

+ +

✔️​

+ +

✔️​

+ +

✔️​

+ +

TransferNode​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

TransferReplica​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

CreateDatabase​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropDatabase​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

FlushAll​

+ +

❌​

+ +

✔️​

+ +

✔️​

+ +

CreatePrivilegeGroup​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

DropPrivilegeGroup​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

ListPrivilegeGroups​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +

OperatePrivilegeGroup​

+ +

❌​

+ +

❌​

+ +

✔️​

+ +
+ +## Procedures​ + +You can create a privilege group and then add privileges to the privilege group. ​ + +### Create a privilege group​ + +The following example demonstrates how to create a privilege group named `privilege_group_1`.​ + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient​ +client.create_privileg_group(group_name='privilege_group_1'）​ + +``` + +```java +import io.milvus.v2.service.rbac.request.CreatePrivilegeGroupReq;​ +​ +client.createPrivilegeGroup(CreatePrivilegeGroupReq.builder()​ + .groupName("privilege_group_1")​ + .build());​ + +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client"​ +​ +client.CreatePrivilegeGroup(context.Background(), "privilege_group_1")​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/privilege_groups/create" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "privilegeGroupName":"privilege_group_1"​ +}'​ + +``` + +### Add privileges to a privilege group​ + +The following example demonstrates how to add privileges `PrivilegeBackupRBAC` and `PrivilegeRestoreRBAC` to the privilege group `privilege_group_1` that is just created.​ + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient​ +client.add_privileges_to_group(group_name='privilege_group_1', privileges=['Query', 'Search'])​ + +``` + +```java +import io.milvus.v2.service.rbac.request.AddPrivilegesToGroupReq;​ +​ +client.addPrivilegesToGroup(AddPrivilegesToGroupReq.builder()​ + .groupName("privilege_group_1")​ + .privileges(Arrays.asList("Query", "Search"))​ + .build());​ + +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client"​ +​ +client.AddPrivilegesToGroup(context.Background(), "privilege_group_1", []string{"Query", "Search"})​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/privilege_groups/add_privileges_to_group" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "privilegeGroupName":"privilege_group_1",​ + "privileges":["Query", "Search"]​ +}'​ + +``` + +### Remove privileges from a privilege group​ + +The following example demonstrates how to remove the privilege `PrivilegeRestoreRBAC` from the privilege group `privilege_group_1`.​ + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient​ +client.remove_privileges_from_group(group_name='privilege_group_1', privileges='Search')​ + +``` + +```java +import io.milvus.v2.service.rbac.request.RemovePrivilegesFromGroupReq;​ +​ +client.removePrivilegesFromGroup(RemovePrivilegesFromGroupReq.builder()​ + .groupName("privilege_group_1")​ + .privileges(Collections.singletonList("Search"))​ + .build());​ + +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client"​ +​ +client.RemovePrivilegesFromGroup(context.Background(), "privilege_group_1", []string{"Search"})​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/privilege_groups/remove_privileges_from_group" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "privilegeGroupName":"privilege_group_1",​ + "privileges":["Search"]​ +}'​ + +``` + +### List privilege groups​ + +The following example demonstrates how to list all existing privilege groups.​ + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient​ +client.list_privilege_groups()​ + +``` + +```java +import io.milvus.v2.service.rbac.PrivilegeGroup;​ +import io.milvus.v2.service.rbac.request.ListPrivilegeGroupsReq;​ +import io.milvus.v2.service.rbac.response.ListPrivilegeGroupsResp;​ +​ +ListPrivilegeGroupsResp resp = client.listPrivilegeGroups(ListPrivilegeGroupsReq.builder()​ + .build());​ +List groups = resp.getPrivilegeGroups();​ + +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client"​ +​ +client.ListPrivilegeGroups(context.Background())​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/privilege_groups/list" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{}'​ + +``` + +Below is an example output.​ + +``` +PrivilegeGroupItem: , ​ + +``` + +### Drop a privilege group​ + +The following example demonstrates how to drop the privilege group `privilege_group_1`.​ + +
+ Python + Java + Go + cURL +
+ +```python +from pymilvus import MilvusClient​ +client.drop_privilege_group(group_name='privilege_group_1')​ + +``` + +```java +import io.milvus.v2.service.rbac.request.DropPrivilegeGroupReq;​ +​ +client.dropPrivilegeGroup(DropPrivilegeGroupReq.builder()​ + .groupName("privilege_group_1")​ + .build());​ + +``` + +```go +import "github.com/milvus-io/milvus-sdk-go/v2/client"​ +​ +client.DropPrivilegeGroup(context.Background(), "privilege_group_1")​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/privilege_groups/drop" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "privilegeGroupName":"privilege_group_1"​ +}'​ + +``` + diff --git a/v2.5.x/site/en/adminGuide/rbac.md b/v2.5.x/site/en/adminGuide/rbac.md index c9c48cbb2..d8f9aca84 100644 --- a/v2.5.x/site/en/adminGuide/rbac.md +++ b/v2.5.x/site/en/adminGuide/rbac.md @@ -1,201 +1,44 @@ --- id: rbac.md related_key: enable RBAC -summary: Learn how to manage users, roles, and privileges. -title: Enable RBAC +summary: RBAC (Role-Based Access Control) is an access control method based on roles. With RBAC, you can finely control the operations users can perform at the collection, database, and instance levels, enhancing data security. ​ +title: RBAC Explained --- -# Enable RBAC +# RBAC Explained​ -By enabling RBAC, you can control access to specific Milvus resources (Eg. a collection or a partition) or permissions based on user role and privileges. Currently, this feature is only available in Python and Java. +RBAC (Role-Based Access Control) is an access control method based on roles. With RBAC, you can finely control the operations users can perform at the collection, database, and instance levels, enhancing data security. ​ -This topic describes how to enable RBAC and manage [users and roles](users_and_roles.md). +Unlike traditional user access control models, RBAC introduces the concept of **roles**. In the RBAC model, you grant privileges to roles and then grant those roles to users. Then users can obtain privileges. ​ -
+The RBAC model can improve the efficiency of access control management. For example, if multiple users require the same set of privileges, you do not need to manually set the privileges for each user. Instead, you can create a role and assign the role to users. If you want to adjust the privileges of these users, you can just adjust the role privileges and the modification will be applied to all users with this role.​ -The code snippets on this page use new MilvusClient (Python) to interact with Milvus. New MilvusClient SDKs for other languages will be released in future updates. +## RBAC key concepts​ -
+![Users, roles, and privileges](../../../assets/users_roles_privileges.png) -## 1. Initiate a Milvus client to establish a connection +There are four major components in the RBAC model.​ -After you enable [user authentication](authenticate.md), connect to your Milvus instance using `token` that consists of a username and a password. By default, Milvus uses the `root` user with the password `Milvus`. +- **Resource: **The resource entity that can be accessed. There are three levels of resources in Milvus - instance, database, and collection.​ -```python -from pymilvus import MilvusClient +- **Privilege: **The permission to perform certain operations on Milvus resources (eg. create collections, insert data, etc). ​ -client = MilvusClient( - uri='http://localhost:19530', # replace with your own Milvus server address - token='root:Milvus' # replace with your own Milvus server token -) -``` +- **Privilege group: **A group of multiple privileges.​ -## 2. Create a user +- **Role: **A role consists of two parts-privileges and resources. Privileges define the type of operations that a role can perform while resources define the target resources that the operations can be performed on. For example, the database administrator role can perform read, write, and manage operations on certain databases.​ -Create a user named `user_1` with the password `P@ssw0rd`: +- **User: **A user is someone who uses Milvus. Each user has a unique ID and is granted a role or multiple roles. ​ -```python -client.create_user( - user_name='user_1', - password='P@ssw0rd' -) -``` +## Procedures​ -After creating a user, you can: +The achieve access control via RBAC, you need to follow the steps below:​ -- Update a user password. You need to provide both the original and the new password. +1. [Create a user](users_and_roles.md#Create-a-user): In addition to the default user `root` in Milvus, you can create new users and set passwords to protect data security.​ -```python -client.update_password( - user_name='user_1', - old_password='P@ssw0rd', - new_password='P@ssw0rd123' -) -``` +2. [Create a role](users_and_roles.md#Create-a-role): You can create customized roles based on your needs. The specific capabilities of a role are determined by its privileges.​ -- List all users. +3. [Create a privilege group](privilege_group.md): Combine multiple privileges into one privilege group to streamline the process of granting privileges to a role.​ -```python -client.list_users() +4. [Grant privileges or privilege groups to a role](grant_privileges.md): Define the capabilities of a role be granting privileges or privilege groups to this role. ​ -# output: -# ['root', 'user_1'] -``` - -- Check the role of a particular user. - -```python -client.describe_user(user_name='user_1') - -# output: -# {'user_name': 'user_1', 'roles': ()} -``` - -## 3. Create a role - -The following example creates a role named `roleA`. - -```python -client.create_role( - role_name="roleA", -) -``` - -After creating a role, you can: - -- List all roles. - -```python -client.list_roles() - -# output: -# ['admin', 'public', 'roleA'] -``` - -## 4. Grant a privilege to a role - -The following example demonstrates how to grant the permission of searching all collections to the role named `roleA`. - -The `object_type` specifies the object type, which can also be understood as the resource type. Currently, valid values ​​include Collection/User/Global, etc., where Global means that there is no specific resource type. The `object_name` is the resource name. If object*type is Collection, then object name can be referred to a specific collection name, or you can use * to specify all collections. If object*type is Global, then the object name can be only specified as *. See [Users and Roles](users_and_roles.md) for other types of privileges you can grant. - -Before managing role privileges, make sure you have enabled user authentication. Otherwise, an error may occur. For information on how to enable user authentication, refer to [Authenticate User Access](authenticate.md). - -```python -# grant privilege to a role - -client.grant_privilege( - role_name='roleA', - object_type='User', # value here can be Global, Collection or User, object type also depends on the API defined in privilegeName - object_name='user_1', # value here can be * or a specific user name if object type is 'User' - privilege='SelectUser' -) -``` - -After granting a privilege to a role, you can: - -- View the privileges granted to a role. - -```python -client.describe_role( - role_name='roleA' -) - -# output: -# {'role': 'roleA', -# 'privileges': [{'object_type': 'User', -# 'object_name': 'user_1', -# 'db_name': 'default', -# 'role_name': 'roleA', -# 'privilege': 'SelectUser', -# 'grantor_name': 'root'}]} -``` - -## 5. Grant a role to a user - -Grant the role to a user so that this user can inherit all the privileges of the role. - -```python -# grant a role to a user - -client.grant_role( - user_name='user_1', - role_name='roleA' -) -``` - -After granting the role, verify that it has been granted: - -```python -client.describe_user( - user_name='user_1' -) - -# output: -# {'user_name': 'user_1', 'roles': ('roleA')} -``` - -## 6. Revoke privileges - -
- -Exercise caution when performing the following operations because these operations are irreversible. - -
- -- Remove a privilege from a role. If you revoke a privilege that has not been granted to the role, an error will occur. - -```python -client.revoke_privilege( - role_name='roleA', - object_type='User', # value here can be Global, Collection or User, object type also depends on the API defined in privilegeName - object_name='user_1', # value here can be * or a specific user name if object type is 'User' - privilege='SelectUser' -) -``` - -- Remove a user from a role. If you revoke a role that has not been granted to the user, an error will occur. - -```python -client.revoke_role( - user_name='user_1', - role_name='roleA' -) -``` - -- Drop a role. - -```python -client.drop_role(role_name='roleA') -``` - -- Drop a user. - -```python -client.drop_user(user_name='user_1') -``` - -## What's next - -- Learn how to manage [user authentication](authenticate.md). - -- Learn how to enable [TLS proxy](tls.md) in Milvus. +5. [Grant roles to users](grant_roles.md): Grant roles with certain privileges to users so that users can have the privileges of a role. A single role can be granted to multiple users.​ diff --git a/v2.5.x/site/en/adminGuide/users_and_roles.md b/v2.5.x/site/en/adminGuide/users_and_roles.md new file mode 100644 index 000000000..1088329ab --- /dev/null +++ b/v2.5.x/site/en/adminGuide/users_and_roles.md @@ -0,0 +1,307 @@ +--- +id: users_and_roles.md +related_key: users, roles +summary: Milvus achieves fine-grained access control through RBAC. You can start by creating users and roles, then assign privileges or privilege groups to roles, and finally manage access control by granting roles to users. This method ensures the efficiency and security of access management. This page introduces how to create users and roles in Milvus.​ +title: Create Users & Roles​ +--- + +# Create Users & Roles​ + +Milvus achieves fine-grained access control through RBAC. You can start by creating users and roles, then assign privileges or privilege groups to roles, and finally manage access control by granting roles to users. This method ensures the efficiency and security of access management. This page introduces how to create users and roles in Milvus.​ + +## User​ + +After initializing a Milvus instance, a root user is automatically generated for authentication when connecting to Milvus for the first time. The username of the root user is `root` and the password is `Milvus`. The default role of the root user is `admin`, which has access to all resources. To ensure data security, please keep your root user's credentials safe to prevent unauthorized access.​ + +For daily operations, we recommend creating users instead of using the root user.​ + +### Create a user​ + +The following example shows how to create a user with the username `user_1` and the password `P@ssw0rd`. The username and password for the user must follow these rules:​ + +- Username: Must start with a letter and can only include uppercase or lowercase letters, numbers, and underscores.​ + +- Password: Must be 8-64 characters long and must include three of the following: uppercase letters, lowercase letters, numbers, and special characters.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client = MilvusClient(​ + uri="http://localhost:19530",​ + token="root:Milvus"​ +)​ +​ +client.create_user(user_name="user_1", password="P@ssw0rd")​ + +``` + +```java +import io.milvus.v2.client.ConnectConfig;​ +import io.milvus.v2.client.MilvusClientV2;​ +import io.milvus.v2.service.rbac.request.CreateUserReq;​ +​ +ConnectConfig connectConfig = ConnectConfig.builder()​ + .uri("http://localhost:19530")​ + .token("root:Milvus")​ + .build();​ + ​ +MilvusClientV2 client = new MilvusClientV2(connectConfig);​ +​ +CreateUserReq createUserReq = CreateUserReq.builder()​ + .userName("user_1")​ + .password("P@ssw0rd")​ + .build();​ + ​ +client.createUser(createUserReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +const address = "http://localhost:19530";​ +const token = "root:Milvus";​ +const client = new MilvusClient({address, token});​ +​ +await milvusClient.createUser({​ + username: 'user_1',​ + password: 'P@ssw0rd',​ + });​ + +``` + +```shell +export CLUSTER_ENDPOINT="http://localhost:19530"​ +export TOKEN="root:Milvus"​ +​ +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/create" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "userName": "user_1",​ + "password": "P@ssw0rd"​ +}'​ + +``` + +### Update password​ + +After creating a user, you can update the password if you forget.​ + +The new password must also follow the following rule:​ + +- Must be 8-64 characters long and include three of the following: uppercase letters, lowercase letters, numbers, and special characters. ​ + +The following example shows how to update the password for user `user_1` to `NewP@ssw0rd`.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.update_password(​ + user_name="user_1",​ + old_password="P@ssw0rd",​ + new_password="NewP@ssw0rd"​ +)​ + +``` + +```java +import io.milvus.v2.service.rbac.request.UpdatePasswordReq;​ +​ +UpdatePasswordReq updatePasswordReq = UpdatePasswordReq.builder()​ + .userName("user_1")​ + .password("P@ssw0rd")​ + .newPassword("NewP@ssw0rd")​ + .build();​ +client.updatePassword(updatePasswordReq);​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +await milvusClient.updateUser({​ + username: 'user_1',​ + newPassword: 'P@ssw0rd',​ + oldPassword: 'NewP@ssw0rd',​ +});​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/update_password" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "newPassword": "P@ssw0rd!",​ + "userName": "user_1",​ + "password": "P@ssw0rd"​ +}'​ + +``` + +### List users​ + +After creating several users, you can list and view all existing users.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.list_users()​ + +``` + +```java +List resp = client.listUsers();​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +await milvusClient.listUsers();​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/users/list" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{}'​ + +``` + +Below is an example output. `root` is the default user automatically generated in Milvus. `user_1` is the new user that is just created.​ + +```bash +['root', 'user_1']​ + +``` + +## Role​ + +Milvus provides a built-in role called `admin`, which is an administrator role that can access resources under all instances and has privileges for all operations. For more fine-grained access management and enhanced data security, it is recommended that you create custom roles based on your needs.​ + +### Create a role​ + +The following example demonstrates how to create a role named `role_a`. ​ + +The role name must follow the following rule:​ + +- Must start with a letter and can only include uppercase or lowercase letters, numbers, and underscores."​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.create_role(role_name="role_a")​ +import io.milvus.v2.service.rbac.request.CreateRoleReq;​ + +``` + +```java +CreateRoleReq createRoleReq = CreateRoleReq.builder()​ + .roleName("role_a")​ + .build();​ + ​ + +``` + +```javascript +client.createRole(createRoleReq);​ +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +await milvusClient.createRole({​ + roleName: 'role_a',​ +});​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/create" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{​ + "roleName": "role_a"​ +}'​ + +``` + +### List roles​ + +After creating several roles, you can list and view all existing roles.​ + +
+ Python + Java + Node.js + cURL +
+ +```python +from pymilvus import MilvusClient​ +​ +client.list_roles()​ + +``` + +```java +List roles = client.listRoles();​ + +``` + +```javascript +const { MilvusClient, DataType } = require("@zilliz/milvus2-sdk-node")​ +​ +await milvusClient.listRoles(​ + includeUserInfo: True​ +);​ + +``` + +```shell +curl --request POST \​ +--url "${CLUSTER_ENDPOINT}/v2/vectordb/roles/list" \​ +--header "Authorization: Bearer ${TOKEN}" \​ +--header "Content-Type: application/json" \​ +-d '{}'​ + +``` + +Below is an example output. `admin` is the default role in Milvus. `role_a` is the new role that is just created.​ + +```bash +['admin', 'role_a']​ + +``` diff --git a/v2.5.x/site/en/menuStructure/en.json b/v2.5.x/site/en/menuStructure/en.json index 3af038648..4211dab99 100644 --- a/v2.5.x/site/en/menuStructure/en.json +++ b/v2.5.x/site/en/menuStructure/en.json @@ -1364,17 +1364,48 @@ "children": [] }, { - "label": "Users, Privileges, and Roles", - "id": "users_and_roles.md", - "order": 10, - "children": [] - }, - { - "label": "Enable RBAC", - "id": "rbac.md", + "label": "RBAC", + "id": "rbac", "order": 1, "isMenu": true, - "children": [] + "children": [ + { + "label": "RBAC Explained", + "id": "rbac.md", + "order": 0, + "children": [] + }, + { + "label": "Create Users & Roles", + "id": "users_and_roles.md", + "order": 1, + "children": [] + }, + { + "label": "Create Privilege Group", + "id": "privilege_group.md", + "order": 2, + "children": [] + }, + { + "label": "Grant Privileges", + "id": "grant_privileges.md", + "order": 3, + "children": [] + }, + { + "label": "Grant Roles", + "id": "grant_roles.md", + "order": 4, + "children": [] + }, + { + "label": "Drop Users & Roles", + "id": "drop_users_roles.md", + "order": 5, + "children": [] + } + ] }, { "label": "Encryption in Transit", diff --git a/v2.5.x/site/en/reference/users_and_roles.md b/v2.5.x/site/en/reference/users_and_roles.md deleted file mode 100644 index 65b994561..000000000 --- a/v2.5.x/site/en/reference/users_and_roles.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -id: users_and_roles.md -related_key: users, roles -summary: Learn about the definition of users, roles, objects, and privileges in role-based access control (RBAC). -title: Users, Privileges, and Roles ---- - -# Users, Privileges, and Roles - -This topic provides an overview of Role-Based Access Control (RBAC) in Milvus, detailing the definitions and relationships between users, roles, objects, and privileges. - -The following figure illustrates the relationship between objects, privileges, roles, and users. - -![users_and_roles](../../../assets/users_and_roles.png "The relationship between object, privilege, role and user.") - -## Key concepts - -To manage access control to Milvus resources, it’s important to understand the key components of RBAC: object types, object names, users, roles, and privileges. - -- **Object type**: the category of the object for which a privilege is being assigned. The object type can be: - - `Global`: System-wide objects, allowing the user to perform actions that affect all collections, users, or system-wide settings. - - `Collection`: Collection-specific objects, allowing the user to perform actions such as creating indexes, loading data, inserting or deleting data, and querying data within a specific collection. - - `User`: Objects related to user management, allowing the user to manage credentials and roles for database users, such as updating user credentials or viewing user details. - -- **Object name**: the specific name of the object to control access for. For instance: - - If the object type is `Global`, the object name must be set to the wildcard (`*`), indicating all objects of the specified type. - - If the object type is `Collection`, the object name is the name of a collection. - - If the object type is `User`, the object name is the name of a database user. - -- **User**: a person or an application that interacts with Milvus, which consists of a username and a corresponding password. - -- **Privilege**: defines the actions that can be performed and the resources that can be accessed. Privileges are not granted directly to users but are assigned to roles. - -- **Role**: defines the set of privileges that a user has for certain objects. Once a role is bound to a user, the user inherits all the privileges granted to that role. - -## Example: Granting privileges - -The following code snippet shows how to grant a `CreateIndex` privilege to a role on a specific collection: - -
- Python - Java - Node.js -
- -```python -milvusClient.grant_privilege( - role_name="CUSTOM_ROLE_NAME", - object_type="Collection", # Valid value: Global, Collection or User. - privilege="CreateIndex", # See the table below for valid privilege names and relevant API descriptions. - object_name="YOUR_COLLECTION_NAME" # The name of the collection to grant access to. Use "*" to grant access to all collections. -) -``` - -```java -GrantPrivilegeReq grantPrivilegeReq = GrantPrivilegeReq.builder() - .roleName("roleName") - .objectName("CollectionName") // The name of the collection to grant access to. Use "*" to grant access to all collections. - .objectType("Collection") // Valid value: Global, Collection or User. - .privilege("CreateIndex") // See the table below for valid privilege names and relevant API descriptions. - .build(); -client.grantPrivilege(grantPrivilegeReq); -``` - -```javascript -milvusClient.grantPrivilege({ - roleName: 'roleName', - object: 'Collection', // Valid value: Global, Collection or User. - objectName: 'CollectionName', // The name of the collection to grant access to. Use "*" to grant access to all collections. - privilegeName: 'CreateIndex' // See the table below for valid privilege names and relevant API descriptions. - }) -``` - -
- -To obtain more information about privilege-related APIs, refer to [grant_privilege](https://milvus.io/api-reference/pymilvus/v2.4.x/MilvusClient/Authentication/grant_privilege.md) and [revoke_privilege](https://milvus.io/api-reference/pymilvus/v2.4.x/MilvusClient/Authentication/revoke_privileges.md). - -
- -
- -To obtain more information about privilege-related APIs, refer to [grantPrivilege](https://milvus.io/api-reference/java/v2.4.x/v2/Authentication/grantPrivilege.md) and [revokePrivilege](https://milvus.io/api-reference/java/v2.4.x/v2/Authentication/revokePrivilege.md). - -
- -
- -To obtain more information about privilege-related APIs, refer to [grantPrivilege](https://milvus.io/api-reference/node/v2.4.x/Authentication/grantPrivilege.md) and [revokePrivilege](https://milvus.io/api-reference/node/v2.4.x/Authentication/revokePrivilege.md). - -
- -## Default users and roles - -Milvus creates a `root` user by default with a default password `Milvus`. The `root` user is granted the `admin` privileges, which means that this `root` user can have access to all resources and perform all actions. - -If a user is associated with the `public` role, they are entitled to the following privileges: - -- `DescribeCollection` -- `ShowCollections` -- `IndexDetail` - -## List of object types and privileges - -The following table lists the values you can choose when [enabling RBAC](rbac.md). - -| Object type | Privilege name | Relevant API description on the client side | -| ----------- | --------------------- | ------------------------------------------------- | -| Collection | CreateIndex | CreateIndex | -| Collection | DropIndex | DropIndex | -| Collection | IndexDetail | DescribeIndex/GetIndexState/GetIndexBuildProgress | -| Collection | Load | LoadCollection/GetLoadingProgress/GetLoadState | -| Collection | GetLoadingProgress | GetLoadingProgress | -| Collection | GetLoadState | GetLoadState | -| Collection | Release | ReleaseCollection | -| Collection | Insert | Insert | -| Collection | Delete | Delete | -| Collection | Upsert | Upsert | -| Collection | Search | Search | -| Collection | Flush | Flush/GetFlushState | -| Collection | GetFlushState | GetFlushState | -| Collection | Query | Query | -| Collection | GetStatistics | GetCollectionStatistics | -| Collection | Compaction | Compact | -| Collection | Import | BulkInsert/Import | -| Collection | LoadBalance | LoadBalance | -| Collection | CreatePartition | CreatePartition | -| Collection | DropPartition | DropPartition | -| Collection | ShowPartitions | ShowPartitions | -| Collection | HasPartition | HasPartition | -| Global | All | All API operation permissions in this table | -| Global | CreateCollection | CreateCollection | -| Global | DropCollection | DropCollection | -| Global | DescribeCollection | DescribeCollection | -| Global | ShowCollections | ShowCollections | -| Global | RenameCollection | RenameCollection | -| Global | FlushAll | FlushAll | -| Global | CreateOwnership | CreateUser CreateRole | -| Global | DropOwnership | DeleteCredential DropRole | -| Global | SelectOwnership | SelectRole/SelectGrant | -| Global | ManageOwnership | OperateUserRole OperatePrivilege | -| Global | CreateResourceGroup | CreateResourceGroup | -| Global | DropResourceGroup | DropResourceGroup | -| Global | DescribeResourceGroup | DescribeResourceGroup | -| Global | ListResourceGroups | ListResourceGroups | -| Global | TransferNode | TransferNode | -| Global | TransferReplica | TransferReplica | -| Global | CreateDatabase | CreateDatabase | -| Global | DropDatabase | DropDatabase | -| Global | ListDatabases | ListDatabases | -| Global | CreateAlias | CreateAlias | -| Global | DropAlias | DropAlias | -| Global | DescribeAlias | DescribeAlias | -| Global | ListAliases | ListAliases | -| User | UpdateUser | UpdateCredential | -| User | SelectUser | SelectUser | - -
-
  • Object and privilege names are case-sensitive.
    • -
  • To grant all privileges to a kind of object, like Collection, Global, User, use "*" for privilege name.
    • -
  • The "*" privilege name for the Global object doesn't include the All privilege, because the All privilege includes all permissions, including any collection and user object.
    • -
    - -## What's next -- Learn how to [enable RBAC](rbac.md).