Skip to content

Commit b9e713e

Browse files
rrelledgerrelledge
authored
RS: Add REST API examples for creating & associating roles and ACLs with databases (#1024)
* DOC-4175 RS: Added REST API examples for creating & associating roles and ACLs with databases * DOC-4175 RS: Add more REST API examples for role & ACL creation
1 parent 3434e5f commit b9e713e

File tree

3 files changed

+187
-5
lines changed

3 files changed

+187
-5
lines changed

‎content/operate/rs/security/access-control/create-cluster-roles.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,11 @@ Here's a summary of the Cluster Manager UI actions permitted by each default man
4949

5050
## Create roles for cluster access {#create-cluster-role}
5151

52-
To create a role that grants cluster access but does not grant access to any databases:
52+
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.
53+
54+
### Cluster Manager UI method {#create-roles-ui}
55+
56+
To create a role that grants cluster access:
5357

5458
1. From **Access Control** > **Roles**, you can:
5559

@@ -70,3 +74,15 @@ To create a role that grants cluster access but does not grant access to any dat
7074
1. Select **Save**.
7175

7276
You can [assign the new role to users]({{<relref "/operate/rs/security/access-control/create-users#assign-roles-to-users">}}) to grant cluster access.
77+
78+
### REST API method {#define-roles-rest-api}
79+
80+
To [create a role]({{<relref "/operate/rs/references/rest-api/requests/roles#post-role">}}) that grants cluster access:
81+
82+
```sh
83+
POST /v1/roles
84+
{
85+
"name": "<role-name>",
86+
"management": "db_viewer | db_member | cluster_viewer | cluster_member | user_manager | admin"
87+
}
88+
```

‎content/operate/rs/security/access-control/create-combined-roles.md

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,11 @@ To create a role that grants database access privileges and allows access to the
1818

1919
## Define Redis ACLs
2020

21-
To define a Redis ACL rule that you can assign to a role:
21+
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.
22+
23+
### Cluster Manager UI method {#define-acls-ui}
24+
25+
To define a Redis ACL rule using the Cluster Manager UI:
2226

2327
1. From **Access Control > Redis ACLs**, you can either:
2428

@@ -40,9 +44,39 @@ The **ACL builder** does not support selectors and key permissions. Use **Free t
4044
For multi-key commands on multi-slot keys, the return value is `failure`, but the command runs on the keys that are allowed.
4145
{{</note>}}
4246

47+
### REST API method {#define-acls-rest-api}
48+
49+
To define a Redis ACL rule using the REST API, use a [create Redis ACL]({{<relref "/operate/rs/references/rest-api/requests/redis_acls#post-redis_acl">}}) request. For more information about Redis ACL rules and syntax, see the [Redis ACL overview]({{<relref "/operate/rs/security/access-control/redis-acl-overview">}}).
50+
51+
Example request:
52+
53+
```sh
54+
POST /v1/redis_acls
55+
{
56+
"name": "Test_ACL_1",
57+
"acl": "+@read +FT.INFO +FT.SEARCH"
58+
}
59+
```
60+
61+
Example response body:
62+
63+
```json
64+
{
65+
"acl": "+@read +FT.INFO +FT.SEARCH",
66+
"name": "Test_ACL_1",
67+
"uid": 11
68+
}
69+
```
70+
71+
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.
72+
4373
## Create roles with ACLs and cluster access {#create-role}
4474

45-
To create a role that grants database access privileges and allows access to the Cluster Management UI and REST API:
75+
You can create a role that grants database access privileges and allows access to the Cluster Management UI and REST API.
76+
77+
### Cluster Manager UI method {#create-roles-ui}
78+
79+
To define a role for combined access using the Cluster Manager UI:
4680

4781
1. From **Access Control** > **Roles**, you can:
4882

@@ -73,3 +107,53 @@ To create a role that grants database access privileges and allows access to the
73107
{{<image filename="images/rs/screenshots/access-control/rbac-save-combined-role.png" alt="Add databases to access">}}
74108

75109
You can [assign the new role to users]({{<relref "/operate/rs/security/access-control/create-users#assign-roles-to-users">}}) to grant database access and access to the Cluster Manager UI and REST API.
110+
111+
### REST API method {#define-roles-rest-api}
112+
113+
To define a role for combined access using the REST API:
114+
115+
1. [Create a role.](#create-role-rest-api)
116+
117+
1. [Associate a database with roles and Redis ACLs.](#associate-roles-acls-rest-api)
118+
119+
#### Create a role {#create-role-rest-api}
120+
121+
To [create a role]({{<relref "/operate/rs/references/rest-api/requests/roles#post-role">}}) using the REST API:
122+
123+
```sh
124+
POST /v1/roles
125+
{
126+
"name": "<role-name>",
127+
"management": "db_viewer | db_member | cluster_viewer | cluster_member | admin"
128+
}
129+
```
130+
131+
Example response body:
132+
133+
```json
134+
{
135+
"management": "admin",
136+
"name": "<role-name>",
137+
"uid": 7
138+
}
139+
```
140+
141+
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.
142+
143+
144+
#### Associate a database with roles and Redis ACLs {#associate-roles-acls-rest-api}
145+
146+
[Update a database's configuration]({{<relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs">}}) to add `roles_permissions` with the role and Redis ACL:
147+
148+
```sh
149+
POST /v1/bdbs/<database-id>
150+
{
151+
"roles_permissions":
152+
[
153+
{
154+
"role_uid": <integer>,
155+
"redis_acl_uid": <integer>
156+
}
157+
]
158+
}
159+
```

‎content/operate/rs/security/access-control/create-db-roles.md

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,11 @@ To create a role that grants database access without granting access to the Redi
2020

2121
## Define Redis ACLs
2222

23-
To define a Redis ACL rule that you can assign to a role:
23+
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.
24+
25+
### Cluster Manager UI method {#define-acls-ui}
26+
27+
To define a Redis ACL rule using the Cluster Manager UI:
2428

2529
1. From **Access Control > Redis ACLs**, you can either:
2630

@@ -42,11 +46,39 @@ The **ACL builder** does not support selectors and key permissions. Use **Free t
4246
For multi-key commands on multi-slot keys, the return value is `failure`, but the command runs on the keys that are allowed.
4347
{{</note>}}
4448

49+
### REST API method {#define-acls-rest-api}
50+
51+
To define a Redis ACL rule using the REST API, use a [create Redis ACL]({{<relref "/operate/rs/references/rest-api/requests/redis_acls#post-redis_acl">}}) request. For more information about Redis ACL rules and syntax, see the [Redis ACL overview]({{<relref "/operate/rs/security/access-control/redis-acl-overview">}}).
52+
53+
Example request:
54+
55+
```sh
56+
POST /v1/redis_acls
57+
{
58+
"name": "Test_ACL_1",
59+
"acl": "+@read +FT.INFO +FT.SEARCH"
60+
}
61+
```
62+
63+
Example response body:
64+
65+
```json
66+
{
67+
"acl": "+@read +FT.INFO +FT.SEARCH",
68+
"name": "Test_ACL_1",
69+
"uid": 11
70+
}
71+
```
72+
73+
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.
74+
4575
## Create roles with ACLs
4676

4777
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**.
4878

49-
To define a role for database access:
79+
### Cluster Manager UI method {#create-roles-ui}
80+
81+
To define a role for database access using the Cluster Manager UI:
5082

5183
1. From **Access Control** > **Roles**, you can:
5284

@@ -77,3 +109,53 @@ To define a role for database access:
77109
{{<image filename="images/rs/access-control-role-save.png" alt="Add databases to access" >}}
78110

79111
You can [assign the new role to users]({{<relref "/operate/rs/security/access-control/create-users#assign-roles-to-users">}}) to grant database access.
112+
113+
### REST API method {#define-roles-rest-api}
114+
115+
To define a role for database access using the REST API:
116+
117+
1. [Create a role.](#create-role-rest-api)
118+
119+
1. [Associate a database with roles and Redis ACLs.](#associate-roles-acls-rest-api)
120+
121+
#### Create a role {#create-role-rest-api}
122+
123+
To [create a role]({{<relref "/operate/rs/references/rest-api/requests/roles#post-role">}}) using the REST API:
124+
125+
```sh
126+
POST /v1/roles
127+
{
128+
"name": "<role-name>",
129+
"management": "none"
130+
}
131+
```
132+
133+
Example response body:
134+
135+
```json
136+
{
137+
"management": "none",
138+
"name": "<role-name>",
139+
"uid": 7
140+
}
141+
```
142+
143+
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.
144+
145+
146+
#### Associate a database with roles and Redis ACLs {#associate-roles-acls-rest-api}
147+
148+
[Update a database's configuration]({{<relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs">}}) to add `roles_permissions` with the role and Redis ACL:
149+
150+
```sh
151+
POST /v1/bdbs/<database-id>
152+
{
153+
"roles_permissions":
154+
[
155+
{
156+
"role_uid": <integer>,
157+
"redis_acl_uid": <integer>
158+
}
159+
]
160+
}
161+
```

0 commit comments

Comments
 (0)