Skip to content

Commit 4cb165f

Browse files
rrelledgerrelledge
authored
RS: SAML SSO (#2498)
* DOC-5858 RS: Added SSO permissions to RS REST API reference * DOC-5858 RS: Added SSO requests and objects to RS REST API reference * DOC-5858 RS: Added more info about enforce_control_plane SSO to RS REST API reference * DOC-5858 RS: Added SSO auth_method to user object in RS REST API reference * DOC-5858 RS: Added SSO certs to RS REST API reference and certs list * DOC-5858 RS: Initial draft of SAML SSO for RS * DOC-5858 A few adjustments to RS SSO draft * DOC-5858 Added SSO setup steps for uploading SP cert and downloading SP metadata * DOC-5858 More adjustments to SSO setup in RS * DOC-5858 More adjustments to RS SSO setup * DOC-5858 More RS SSO edits * DOC-5858 Fixed in-page link in RS SSO * DOC-5858 Updated RS SSO REST API reference and examples * DOC-5858 Added test screenshot for RS SSO * DOC-5858 Added screenshots for RS SSO * DOC-5858 Added additional details/limitations for RS SSO * Feedback update to fix sso permissions tables * Feedback updates for SAML 2.0 and SP Entity ID port * Feedback update for SP-initiated SSO * Fixed SP metadata screenshot * DOC-5858 Feedback update to add instructions to change the SP address
1 parent 2b01af8 commit 4cb165f

File tree

13 files changed

+820
-9
lines changed

13 files changed

+820
-9
lines changed

‎content/operate/rs/references/rest-api/objects/certificates.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,6 @@ An API object that represents a certificate used by a Redis Enterprise Software
1414

1515
| Name | Type/Value | Description |
1616
|------|------------|-------------|
17-
| name | `cm`<br />`api`<br />`mtls_trusted_ca`<br />`proxy`<br />`metrics_exporter`<br />`syncer`<br />`ldap_client`<br />`ccs_internode_encryption`<br />`data_internode_encryption` | Certificate type.<br />See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. |
17+
| name | "cm"<br />"api"<br />"mtls_trusted_ca"<br />"proxy"<br />"metrics_exporter"<br />"syncer"<br />"ldap_client"<br />"ccs_internode_encryption"<br />"data_internode_encryption"<br />"sso_service"<br />"sso_issuer" | Certificate type.<br />See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. |
1818
| certificate | string | The certificate in PEM format |
1919
| key | string | The private key in PEM format |

‎content/operate/rs/references/rest-api/objects/sso.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
Title: SSO object
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: An object for single sign-on (SSO) configuration
9+
linkTitle: sso
10+
weight: $weight
11+
---
12+
13+
An API object that represents single sign-on (SSO) configuration in the cluster.
14+
15+
| Name | Type/Value | Description |
16+
|------|------------|-------------|
17+
| control_plane | boolean (default: false) | If `true`, enables single sign-on (SSO) for the control plane. |
18+
| enforce_control_plane | boolean (default: false) | If `true`, enforce SSO login for the control plane for non-admin users. If `false`, all users can still login using their local username and password if SSO is down. |
19+
| protocol | "saml2" | SSO protocol to use. |
20+
| issuer | complex object | Issuer related configuration.<br>Contains the following fields:<br>**id**: Unique ID of the issuer side (example: "urn:sso:example:idp")<br>**login_url**: SSO login URL (example: "https://idp.example.com/sso/saml")<br>**logout_url**: SSO logout URL (example: "https://idp.example.com/sso/slo")<br />**metadata**: Base64 encoded IdP metadata (read-only) |
21+
| service | complex object | Service related configuration.<br />For SAML2 service configuration:<br />{{<code>}}{
22+
"address": "string",
23+
"saml2": {
24+
"entity_id": "string",
25+
"acs_url": "string",
26+
"slo_url": "string"
27+
}
28+
}{{</code>}}<br>**address**: External service address used for SSO. By default, the cluster name with the Cluster Manager port is used.<br />**acs_url**: Assertion Consumer Service URL (read-only)<br>**slo_url**: Single Logout URL (read-only)<br>**entity_id**: Service entity ID (read-only) |

‎content/operate/rs/references/rest-api/objects/user.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ weight: $weight
1515
| uid | integer | User's unique ID |
1616
| account_id | integer | SM account ID |
1717
| action_uid | string | Action UID. If it exists, progress can be tracked by the <span class="break-all">`GET /actions/{uid}`</span> API request (read-only) |
18-
| auth_method | **'regular'**<br />'certificate'<br />'entraid' | User's authentication method |
18+
| auth_method | **'regular'**<br />'certificate'<br />'entraid'<br />'sso' | User's authentication method |
1919
| bdbs_email_alerts | complex object | UIDs of databases that user will receive alerts for |
2020
| <span class="break-all">certificate_subject_line</span> | string | The certificate’s subject line as defined by RFC2253. Used for certificate-based authentication users only. |
2121
| cluster_email_alerts | boolean | Activate cluster email alerts for a user |

‎content/operate/rs/references/rest-api/permissions.md‎

Lines changed: 8 additions & 6 deletions
Large diffs are not rendered by default.

‎content/operate/rs/references/rest-api/requests/cluster/sso.md‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
---
2+
Title: Single sign-on requests
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: Single sign-on (SSO) configuration requests
9+
headerRange: '[1-2]'
10+
linkTitle: sso
11+
toc: 'true'
12+
weight: $weight
13+
---
14+
15+
| Method | Path | Description |
16+
|--------|------|-------------|
17+
| [GET](#get-cluster-sso) | `/v1/cluster/sso` | Get SSO configuration |
18+
| [PUT](#put-cluster-sso) | `/v1/cluster/sso` | Set or update SSO configuration |
19+
| [DELETE](#delete-cluster-sso) | `/v1/cluster/sso` | Clear SSO configuration |
20+
| [GET](#get-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/sp` | Get SAML service provider metadata |
21+
| [POST](#post-cluster-sso-saml-metadata) | `/v1/cluster/sso/saml/metadata/idp` | Upload SAML identity provider metadata |
22+
23+
## Get SSO configuration {#get-cluster-sso}
24+
25+
GET /v1/cluster/sso
26+
27+
Get the single sign-on configuration as JSON.
28+
29+
#### Required permissions
30+
31+
| Permission name | Roles |
32+
|-----------------|-------|
33+
| [view_sso]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}}) | admin<br />user_manager |
34+
35+
### Request {#get-request}
36+
37+
#### Example HTTP request
38+
39+
GET /v1/cluster/sso
40+
41+
#### Request headers
42+
43+
| Key | Value | Description |
44+
|-----|-------|-------------|
45+
| Host | cnm.cluster.fqdn | Domain name |
46+
| Accept | application/json | Accepted media type |
47+
48+
### Response {#get-response}
49+
50+
Returns an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}).
51+
52+
#### Example JSON body
53+
54+
```json
55+
{
56+
"control_plane": true,
57+
"protocol": "saml2",
58+
"enforce_control_plane": false,
59+
"issuer": {
60+
"id": "urn:sso:example:idp",
61+
"login_url": "https://idp.example.com/sso/saml",
62+
"logout_url": "https://idp.example.com/sso/slo",
63+
"metadata": "<base64 encoded metadata>"
64+
},
65+
"service": {
66+
"address": "https://hostname:port",
67+
"saml2": {
68+
"entity_id": "https://cnm.cluster.fqdn/sp",
69+
"acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
70+
"slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
71+
}
72+
}
73+
}
74+
```
75+
76+
### Status codes {#get-status-codes}
77+
78+
| Code | Description |
79+
|------|-------------|
80+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
81+
82+
## Update SSO configuration {#put-cluster-sso}
83+
84+
PUT /v1/cluster/sso
85+
86+
Set or update the cluster single sign-on configuration.
87+
88+
#### Required permissions
89+
90+
| Permission name | Roles |
91+
|-----------------|-------|
92+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
93+
94+
### Request {#put-request}
95+
96+
#### Example HTTP request
97+
98+
PUT /v1/cluster/sso
99+
100+
#### Example JSON body
101+
102+
```json
103+
{
104+
"control_plane": false,
105+
"protocol": "saml2",
106+
"enforce_control_plane": false,
107+
"issuer": {
108+
"id": "urn:sso:example:idp",
109+
"login_url": "https://idp.example.com/sso/saml",
110+
"logout_url": "https://idp.example.com/sso/slo"
111+
},
112+
"service": {
113+
"address": "https://hostname:port"
114+
}
115+
}
116+
```
117+
118+
#### Request headers
119+
120+
| Key | Value | Description |
121+
|-----|-------|-------------|
122+
| Host | cnm.cluster.fqdn | Domain name |
123+
| Accept | application/json | Accepted media type |
124+
125+
#### Request body
126+
127+
Include an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}) with updated fields in the request body.
128+
129+
### Response {#put-response}
130+
131+
Returns a status code. If an error occurs, the response body can include an error code and message with more details.
132+
133+
### Error codes {#put-error-codes}
134+
135+
Possible `error_code` values:
136+
137+
| Code | Description |
138+
|------|-------------|
139+
| missing_param | A required parameter is missing while SSO is being enabled |
140+
| missing_certificate | SSO certificate is not found while SSO is being enabled |
141+
142+
### Status codes {#put-status-codes}
143+
144+
| Code | Description |
145+
|------|-------------|
146+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, SSO config has been set |
147+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing configuration parameters |
148+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required certificate |
149+
150+
## Delete SSO configuration {#delete-cluster-sso}
151+
152+
DELETE /v1/cluster/sso
153+
154+
Clear the single sign-on configuration.
155+
156+
#### Required permissions
157+
158+
| Permission name | Roles |
159+
|-----------------|-------|
160+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
161+
162+
### Request {#delete-request}
163+
164+
#### Example HTTP request
165+
166+
DELETE /v1/cluster/sso
167+
168+
#### Request headers
169+
170+
| Key | Value | Description |
171+
|-----|-------|-------------|
172+
| Host | cnm.cluster.fqdn | Domain name |
173+
| Accept | application/json | Accepted media type |
174+
175+
### Response {#delete-response}
176+
177+
Returns a status code.
178+
179+
### Error codes {#delete-error-codes}
180+
181+
Possible `error_code` values:
182+
183+
| Code | Description |
184+
|------|-------------|
185+
| delete_certificate_error | An error occurred during SSO certificate deletion |
186+
187+
### Status codes {#delete-status-codes}
188+
189+
| Code | Description |
190+
|------|-------------|
191+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
192+
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Error during deletion |
193+
194+
## Get SAML service provider metadata {#get-cluster-sso-saml-metadata}
195+
196+
GET /v1/cluster/sso/saml/metadata/sp
197+
198+
Generates and returns the SAML2 service provider metadata XML.
199+
200+
#### Required permissions
201+
202+
| Permission name | Roles |
203+
|-----------------|-------|
204+
| [view_sso]({{< relref "/operate/rs/references/rest-api/permissions#view_sso" >}}) | admin<br />user_manager |
205+
206+
### Request {#get-metadata-request}
207+
208+
#### Example HTTP request
209+
210+
GET /v1/cluster/sso/saml/metadata/sp
211+
212+
#### Request headers
213+
214+
| Key | Value | Description |
215+
|-----|-------|-------------|
216+
| Host | cnm.cluster.fqdn | Domain name |
217+
| Accept | application/samlmetadata+xml | Accepted media type |
218+
219+
### Response {#get-metadata-response}
220+
221+
Returns SAML2 service provider metadata as XML.
222+
223+
#### Example response body
224+
225+
```xml
226+
<?xml version="1.0" encoding="UTF-8"?>
227+
<md:EntityDescriptor
228+
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
229+
...
230+
</md:EntityDescriptor>
231+
```
232+
233+
### Error codes {#get-metadata-error-codes}
234+
235+
Possible `error_code` values:
236+
237+
| Code | Description |
238+
|------|-------------|
239+
| missing_certificate | Service certificate is missing |
240+
| saml_metadata_generation_error | An error occurred while generating the XML metadata |
241+
242+
### Status codes {#get-metadata-status-codes}
243+
244+
| Code | Description |
245+
|------|-------------|
246+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
247+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |
248+
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Unexpected error when generating metadata |
249+
250+
## Upload SAML identity provider metadata {#post-cluster-sso-saml-metadata}
251+
252+
POST /v1/cluster/sso/saml/metadata/idp
253+
254+
Uploads and validates the SAML2 identity provider metadata XML.
255+
256+
#### Required permissions
257+
258+
| Permission name | Roles |
259+
|-----------------|-------|
260+
| [config_sso]({{< relref "/operate/rs/references/rest-api/permissions#config_sso" >}}) | admin<br />user_manager |
261+
262+
### Request {#post-metadata-request}
263+
264+
#### Example HTTP request
265+
266+
POST /v1/cluster/sso/saml/metadata/idp
267+
268+
#### Example JSON body
269+
270+
```json
271+
{
272+
"idp_metadata": "YWp3cjkwcHR1eWF3MHJ0eTkwYXc0eXQwOW4..."
273+
}
274+
```
275+
276+
#### Request headers
277+
278+
| Key | Value | Description |
279+
|-----|-------|-------------|
280+
| Host | cnm.cluster.fqdn | Domain name |
281+
| Accept | application/json | Accepted media type |
282+
283+
#### Request body
284+
285+
| Name | Type/Value | Description |
286+
|------|------------|-------------|
287+
| idp_metadata | string | Base64-encoded SAML2 identity provider metadata XML |
288+
289+
### Response {#post-metadata-response}
290+
291+
Returns an [SSO object]({{< relref "/operate/rs/references/rest-api/objects/sso" >}}) with the updated configuration.
292+
293+
#### Example JSON body
294+
295+
```json
296+
{
297+
"control_plane": true,
298+
"protocol": "saml2",
299+
"enforce_control_plane": false,
300+
"issuer": {
301+
"id": "urn:sso:example:idp",
302+
"login_url": "https://idp.example.com/sso/saml",
303+
"logout_url": "https://idp.example.com/sso/slo"
304+
},
305+
"service": {
306+
"saml2": {
307+
"entity_id": "https://cnm.cluster.fqdn/sp",
308+
"acs_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/acs",
309+
"slo_url": "https://cnm.cluster.fqdn/v1/cluster/sso/saml/slo"
310+
}
311+
}
312+
}
313+
```
314+
315+
### Error codes {#post-metadata-error-codes}
316+
317+
Possible `error_code` values:
318+
319+
| Code | Description |
320+
|------|-------------|
321+
| saml_metadata_validation_error | IdP metadata failed configuration validation checks |
322+
| saml_metadata_parsing_error | IdP metadata is not a valid base64-encoded XML |
323+
| missing_certificate | SSO certificate is not found while SSO is being enabled |
324+
325+
### Status codes {#post-metadata-status-codes}
326+
327+
| Code | Description |
328+
|------|-------------|
329+
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success |
330+
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters |
331+
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Missing required service certificate |

‎content/operate/rs/security/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Redis Enterprise Software provides various features to secure your Redis Enterpr
1919
| [Password expiration]({{<relref "/operate/rs/security/access-control/manage-passwords/password-expiration">}}) | [Create roles]({{<relref "/operate/rs/security/access-control/create-combined-roles">}}) | [Configure cipher suites]({{<relref "/operate/rs/security/encryption/tls/ciphers">}}) | [Update certificates]({{<relref "/operate/rs/security/certificates/updating-certificates">}}) |
2020
| [Default database access]({{<relref "/operate/rs/security/access-control/manage-users/default-user">}}) | [Redis ACLs]({{<relref "/operate/rs/security/access-control/redis-acl-overview">}}) | [Encrypt private keys on disk]({{<relref "/operate/rs/security/encryption/pem-encryption">}}) | [Enable OCSP stapling]({{<relref "/operate/rs/security/certificates/ocsp-stapling">}}) |
2121
| [Rotate user passwords]({{<relref "/operate/rs/security/access-control/manage-passwords/rotate-passwords">}}) | [Integrate with LDAP]({{<relref "/operate/rs/security/access-control/ldap">}}) | [Internode encryption]({{<relref "/operate/rs/security/encryption/internode-encryption">}}) | [Audit database connections]({{<relref "/operate/rs/security/audit-events">}}) |
22+
| [Single sign-on (SSO)]({{<relref "/operate/rs/security/access-control/saml-sso">}}) | | | |
2223

2324
## Recommended security practices
2425

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ To add a user to the cluster:
3030

3131
{{<image filename="images/rs/screenshots/access-control/7-22-updates/create-user-panel.png" alt="Create user panel with fields for username, email, password, and alerts.">}}
3232

33+
{{< note >}}
34+
To use [single sign-on (SSO)]({{< relref "/operate/rs/security/access-control/saml-sso" >}}), users must have email addresses.
35+
{{< /note >}}
36+
3337
1. Select the **Alerts** the user should receive by email:
3438

3539
- **Receive alerts for databases** - The alerts that are enabled for the selected databases will be sent to the user. Choose **All databases** or **Customize** to select the individual databases to send alerts for.

0 commit comments

Comments
 (0)