From c3bd010c485f528867ffa0009eb49e36951a0fa2 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Thu, 2 Jan 2025 16:49:42 -0600 Subject: [PATCH 1/2] DOC-4175 RS: Added REST API examples for creating & associating roles and ACLs with databases --- .../access-control/create-db-roles.md | 49 ++++++++++++++++++- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/content/operate/rs/security/access-control/create-db-roles.md b/content/operate/rs/security/access-control/create-db-roles.md index e3152c12e0..9462bed261 100644 --- a/content/operate/rs/security/access-control/create-db-roles.md +++ b/content/operate/rs/security/access-control/create-db-roles.md @@ -20,7 +20,9 @@ To create a role that grants database access without granting access to the Redi ## Define Redis ACLs -To define a Redis ACL rule that you can assign to a role: +### Cluster Manager UI method + +To define a Redis ACL rule that you can assign to a role using the Cluster Manager UI: 1. From **Access Control > Redis ACLs**, you can either: @@ -42,11 +44,25 @@ The **ACL builder** does not support selectors and key permissions. Use **Free t For multi-key commands on multi-slot keys, the return value is `failure`, but the command runs on the keys that are allowed. {{}} +### REST API method + +To define a Redis ACL rule that you can assign to a role using the REST API: + +```sh +POST /v1/redis_acls +{ + "name": "Test_ACL_1", + "acl": "+@read +FT.INFO +FT.SEARCH" +} +``` + ## Create roles with ACLs To create a role that grants database access to users but blocks access to the Redis Enterprise Cluster Manager UI and REST API, set the **Cluster management role** to **None**. -To define a role for database access: +### Cluster Manager UI method + +To define a role for database access using the Cluster Manager UI: 1. From **Access Control** > **Roles**, you can: @@ -77,3 +93,32 @@ To define a role for database access: {{Add databases to access}} You can [assign the new role to users]({{}}) to grant database access. + +### REST API method + +To define a role for database access using the REST API: + +1. Create role: + + ```sh + POST /v1/roles + { + "name": "", + "management": "none" + } + ``` + +1. Associate the role with ACLs and databases: + + ```sh + POST /v1/bdbs/ + { + "roles_permissions": + [ + { + "role_uid": , + "redis_acl_uid": + } + ] + } + ``` From b17511d4ce884888b4b9b3a3bce6d8274ee3e413 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Fri, 3 Jan 2025 16:06:38 -0600 Subject: [PATCH 2/2] DOC-4175 RS: Add more REST API examples for role & ACL creation --- .../access-control/create-cluster-roles.md | 18 +++- .../access-control/create-combined-roles.md | 88 ++++++++++++++++++- .../access-control/create-db-roles.md | 87 ++++++++++++------ 3 files changed, 165 insertions(+), 28 deletions(-) diff --git a/content/operate/rs/security/access-control/create-cluster-roles.md b/content/operate/rs/security/access-control/create-cluster-roles.md index 10b8d9f1c1..2374e0d8b7 100644 --- a/content/operate/rs/security/access-control/create-cluster-roles.md +++ b/content/operate/rs/security/access-control/create-cluster-roles.md @@ -49,7 +49,11 @@ Here's a summary of the Cluster Manager UI actions permitted by each default man ## Create roles for cluster access {#create-cluster-role} -To create a role that grants cluster access but does not grant access to any databases: +You can use the [Cluster Manager UI](#create-roles-ui) or the [REST API](#define-roles-rest-api) to create a role that grants cluster access but does not grant access to any databases. + +### Cluster Manager UI method {#create-roles-ui} + +To create a role that grants cluster access: 1. From **Access Control** > **Roles**, you can: @@ -70,3 +74,15 @@ To create a role that grants cluster access but does not grant access to any dat 1. Select **Save**. You can [assign the new role to users]({{}}) to grant cluster access. + +### REST API method {#define-roles-rest-api} + +To [create a role]({{}}) that grants cluster access: + +```sh +POST /v1/roles +{ + "name": "", + "management": "db_viewer | db_member | cluster_viewer | cluster_member | user_manager | admin" +} +``` diff --git a/content/operate/rs/security/access-control/create-combined-roles.md b/content/operate/rs/security/access-control/create-combined-roles.md index 4d74616f3e..9809b59d8d 100644 --- a/content/operate/rs/security/access-control/create-combined-roles.md +++ b/content/operate/rs/security/access-control/create-combined-roles.md @@ -18,7 +18,11 @@ To create a role that grants database access privileges and allows access to the ## Define Redis ACLs -To define a Redis ACL rule that you can assign to a role: +You can use the [Cluster Manager UI](#define-acls-ui) or the [REST API](#define-acls-rest-api) to define Redis ACL rules that you can assign to roles. + +### Cluster Manager UI method {#define-acls-ui} + +To define a Redis ACL rule using the Cluster Manager UI: 1. From **Access Control > Redis ACLs**, you can either: @@ -40,9 +44,39 @@ The **ACL builder** does not support selectors and key permissions. Use **Free t For multi-key commands on multi-slot keys, the return value is `failure`, but the command runs on the keys that are allowed. {{}} +### REST API method {#define-acls-rest-api} + +To define a Redis ACL rule using the REST API, use a [create Redis ACL]({{}}) request. For more information about Redis ACL rules and syntax, see the [Redis ACL overview]({{}}). + +Example request: + +```sh +POST /v1/redis_acls +{ + "name": "Test_ACL_1", + "acl": "+@read +FT.INFO +FT.SEARCH" +} +``` + +Example response body: + +```json +{ + "acl": "+@read +FT.INFO +FT.SEARCH", + "name": "Test_ACL_1", + "uid": 11 +} +``` + +To associate the Redis ACL with a role and database, use the `uid` from the response as the `redis_acl_uid` when you add `roles_permissions` to the database. See [Associate a database with roles and Redis ACLs](#associate-roles-acls-rest-api) for an example request. + ## Create roles with ACLs and cluster access {#create-role} -To create a role that grants database access privileges and allows access to the Cluster Management UI and REST API: +You can create a role that grants database access privileges and allows access to the Cluster Management UI and REST API. + +### Cluster Manager UI method {#create-roles-ui} + +To define a role for combined access using the Cluster Manager UI: 1. From **Access Control** > **Roles**, you can: @@ -73,3 +107,53 @@ To create a role that grants database access privileges and allows access to the {{Add databases to access}} You can [assign the new role to users]({{}}) to grant database access and access to the Cluster Manager UI and REST API. + +### REST API method {#define-roles-rest-api} + +To define a role for combined access using the REST API: + +1. [Create a role.](#create-role-rest-api) + +1. [Associate a database with roles and Redis ACLs.](#associate-roles-acls-rest-api) + +#### Create a role {#create-role-rest-api} + +To [create a role]({{}}) using the REST API: + +```sh +POST /v1/roles +{ + "name": "", + "management": "db_viewer | db_member | cluster_viewer | cluster_member | admin" +} +``` + +Example response body: + +```json +{ + "management": "admin", + "name": "", + "uid": 7 +} +``` + +To associate the role with a Redis ACL and database, use the `uid` from the response as the `role_uid` when you add `roles_permissions` to the database. See [Associate a database with roles and Redis ACLs](#associate-roles-acls-rest-api) for an example request. + + +#### Associate a database with roles and Redis ACLs {#associate-roles-acls-rest-api} + +[Update a database's configuration]({{}}) to add `roles_permissions` with the role and Redis ACL: + +```sh +POST /v1/bdbs/ +{ + "roles_permissions": + [ + { + "role_uid": , + "redis_acl_uid": + } + ] +} +``` diff --git a/content/operate/rs/security/access-control/create-db-roles.md b/content/operate/rs/security/access-control/create-db-roles.md index 9462bed261..93ca06acb3 100644 --- a/content/operate/rs/security/access-control/create-db-roles.md +++ b/content/operate/rs/security/access-control/create-db-roles.md @@ -20,9 +20,11 @@ To create a role that grants database access without granting access to the Redi ## Define Redis ACLs -### Cluster Manager UI method +You can use the [Cluster Manager UI](#define-acls-ui) or the [REST API](#define-acls-rest-api) to define Redis ACL rules that you can assign to roles. -To define a Redis ACL rule that you can assign to a role using the Cluster Manager UI: +### Cluster Manager UI method {#define-acls-ui} + +To define a Redis ACL rule using the Cluster Manager UI: 1. From **Access Control > Redis ACLs**, you can either: @@ -44,9 +46,11 @@ The **ACL builder** does not support selectors and key permissions. Use **Free t For multi-key commands on multi-slot keys, the return value is `failure`, but the command runs on the keys that are allowed. {{}} -### REST API method +### REST API method {#define-acls-rest-api} + +To define a Redis ACL rule using the REST API, use a [create Redis ACL]({{}}) request. For more information about Redis ACL rules and syntax, see the [Redis ACL overview]({{}}). -To define a Redis ACL rule that you can assign to a role using the REST API: +Example request: ```sh POST /v1/redis_acls @@ -56,11 +60,23 @@ POST /v1/redis_acls } ``` +Example response body: + +```json +{ + "acl": "+@read +FT.INFO +FT.SEARCH", + "name": "Test_ACL_1", + "uid": 11 +} +``` + +To associate the Redis ACL with a role and database, use the `uid` from the response as the `redis_acl_uid` when you add `roles_permissions` to the database. See [Associate a database with roles and Redis ACLs](#associate-roles-acls-rest-api) for an example request. + ## Create roles with ACLs To create a role that grants database access to users but blocks access to the Redis Enterprise Cluster Manager UI and REST API, set the **Cluster management role** to **None**. -### Cluster Manager UI method +### Cluster Manager UI method {#create-roles-ui} To define a role for database access using the Cluster Manager UI: @@ -94,31 +110,52 @@ To define a role for database access using the Cluster Manager UI: You can [assign the new role to users]({{}}) to grant database access. -### REST API method +### REST API method {#define-roles-rest-api} To define a role for database access using the REST API: -1. Create role: +1. [Create a role.](#create-role-rest-api) - ```sh - POST /v1/roles - { - "name": "", - "management": "none" - } - ``` +1. [Associate a database with roles and Redis ACLs.](#associate-roles-acls-rest-api) + +#### Create a role {#create-role-rest-api} + +To [create a role]({{}}) using the REST API: + +```sh +POST /v1/roles +{ + "name": "", + "management": "none" +} +``` + +Example response body: + +```json +{ + "management": "none", + "name": "", + "uid": 7 +} +``` + +To associate the role with a Redis ACL and database, use the `uid` from the response as the `role_uid` when you add `roles_permissions` to the database. See [Associate a database with roles and Redis ACLs](#associate-roles-acls-rest-api) for an example request. + + +#### Associate a database with roles and Redis ACLs {#associate-roles-acls-rest-api} -1. Associate the role with ACLs and databases: +[Update a database's configuration]({{}}) to add `roles_permissions` with the role and Redis ACL: - ```sh - POST /v1/bdbs/ +```sh +POST /v1/bdbs/ +{ + "roles_permissions": + [ { - "roles_permissions": - [ - { - "role_uid": , - "redis_acl_uid": - } - ] + "role_uid": , + "redis_acl_uid": } - ``` + ] +} +```