Skip to content

Commit ac8a7b0

Browse files
rrelledgerrelledge
committed
DOC-5858 RS: Initial draft of SAML SSO for RS
1 parent 362055b commit ac8a7b0

File tree

3 files changed

+222
-0
lines changed

3 files changed

+222
-0
lines changed

‎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.

‎content/operate/rs/security/access-control/saml-sso.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
Title: SAML single sign-on
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- rs
8+
description: Set up single sign-on with SAML for the Redis Enterprise Software Cluster Manager UI.
9+
hideListLinks: true
10+
linkTitle: SAML SSO
11+
weight: 60
12+
---
13+
14+
15+
Redis Enterprise Software supports both [IdP-initiated](#idp-initiated-sso) and [SP-initiated](#sp-initiated-sso) [single sign-on (SSO)](https://en.wikipedia.org/wiki/Single_sign-on) with [SAML (Security Assertion Markup Language)](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) for the Cluster Manager UI.
16+
17+
You cannot use [SCIM (System for Cross-domain Identity Management)](https://en.wikipedia.org/wiki/System_for_Cross-domain_Identity_Management) to provision Redis Enterprise Software users. However, Redis Enterprise Software supports just-in-time (JIT) user provisioning, which means Redis Enterprise Software automatically creates a user account the first time a new user signs in with SSO.
18+
19+
## SAML SSO overview
20+
21+
When SAML SSO is enabled, the [identity provider (IdP)](https://en.wikipedia.org/wiki/Identity_provider) admin handles SAML user management instead of the Redis Enterprise Software.
22+
23+
You can use any identity provider to integrate with Redis Enterprise Software as long as it supports the SAML protocol.
24+
25+
After you activate SAML SSO, all existing local users except for admin users are required to use SAML SSO to sign in. Before they can sign in to Redis Enterprise Software Cluster Manager UI, the identity provider admin needs to set up these users on the IdP side and configure the `redisRoleMapping` attribute to map them to the appropriate Redis Enterprise Software roles.
26+
27+
### IdP-initiated SSO
28+
29+
With IdP-initiated single sign-on, you can select the Redis Enterprise Software application after you sign in to your [identity provider (IdP)](https://en.wikipedia.org/wiki/Identity_provider). This redirects you to the Redis Enterprise Software Cluster Manager UI and signs you in.
30+
31+
### SP-initiated SSO
32+
33+
You can also initiate single sign-on from the Redis Enterprise Software Cluster Manager UI. This process is known as [service provider (SP)](https://en.wikipedia.org/wiki/Service_provider)-initiated single sign-on.
34+
35+
1. From the Redis Enterprise Software Cluster Manager UI's sign-in screen, select **SSO**.
36+
37+
1. Enter the email address associated with your user account.
38+
39+
1. Select the **Login** button.
40+
41+
- If you already have an active SSO session with your identity provider, this signs you in.
42+
43+
- Otherwise, the SSO flow redirects you to your identity provider's sign in screen. Enter your IdP user credentials to sign in. This redirects you back to the Redis Enterprise Software Cluster Manager UI and automatically signs you in.
44+
45+
## Set up SAML SSO
46+
47+
To set up SAML single sign-on for a Redis Enterprise Software cluster:
48+
49+
1. [Set up a SAML app](#set-up-app) to integrate Redis Enterprise Software with your identity provider.
50+
51+
1. [Configure SAML identity provider in Redis Enterprise Software](#configure-idp).
52+
53+
1. [Download service provider metadata](#download-sp) and upload it to your identity provider.
54+
55+
1. [Activate SAML SSO](#activate-saml-sso).
56+
57+
58+
Flow from HLD: <!--TODO: need to confirm which setup flow to keep-->
59+
60+
1. Upload new SP certificate and private key (PUT /v1/cluster/certificates /sso_service/)
61+
62+
1. Export the metadata (GET /v1/cluster/sso/saml/metadata)
63+
64+
1. Upload new IdP public certificate (PUT /v1/cluster/certificates /sso_issuer/)
65+
66+
1. Set the IdP metadata, fallback behavior and enable SSO (PUT /v1/cluster/sso)
67+
68+
69+
### Set up SAML app {#set-up-app}
70+
71+
Set up a SAML app to integrate Redis Enterprise Software with your identity provider:
72+
73+
1. Sign in to your identity provider's admin console.
74+
75+
1. Create or add a SAML integration app for the service provider Redis Enterprise Software.
76+
77+
1. Set up your SAML service provider app so the SAML assertion contains the following attributes:
78+
79+
| Attribute&nbsp;name<br />(case-sensitive) | Description |
80+
|-------------------------------------------|-------------|
81+
| FirstName | User's first name |
82+
| LastName | User's last name |
83+
| Email | User's email address (used as the username in the Redis Enterprise Software Cluster Manager UI) |
84+
| redisRoleMapping | Key-value pair of a lowercase role name (owner, member, manager, billing_admin, or viewer) |
85+
86+
For `redisRoleMapping`, you can add the same user to multiple SAML-enabled accounts using one of these options:
87+
88+
- A single string that contains a comma-separated list of account/role pairs
89+
90+
```xml
91+
<saml2:Attribute Name="redisRoleMapping" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
92+
<saml2:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
93+
12345=owner,54321=manager
94+
</saml2:AttributeValue>
95+
</saml2:Attribute>
96+
```
97+
98+
- Multiple strings, where each represents a single account/role pair
99+
100+
```xml
101+
<saml2:Attribute Name="redisRoleMapping" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
102+
<saml2:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
103+
12345=owner
104+
</saml2:AttributeValue>
105+
<saml2:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
106+
54321=manager
107+
</saml2:AttributeValue>
108+
</saml2:Attribute>
109+
```
110+
111+
{{<note>}}
112+
To confirm the identity provider's SAML assertions contain the required attributes, you can use a SAML-tracer web developer tool to inspect them.
113+
{{</note>}}
114+
115+
1. Set up any additional configuration required by your identity provider to ensure you can configure the `redisRoleMapping` attribute for SAML users.
116+
117+
If your identity provider lets you configure custom attributes with workflows or group rules, you can set up automation to configure the `redisRoleMapping` field automatically instead of manually.
118+
119+
### Configure SAML in Redis Enterprise Software {#configure-idp}
120+
121+
After you set up the SAML integration app and create a SAML user in your identity provider, you need to configure your Redis Enterprise Software cluster to set up SSO.
122+
123+
1. Sign in to Redis Enterprise Software Cluster Manager UI with the email address associated with the SAML user you set up with your identity provider.
124+
125+
1. Go to **Access Control > Single Sign-On**.
126+
127+
1. [Verify at least one domain](#verify-domain) if you haven't.
128+
129+
1. Configure the **Identity Provider metadata** settings.
130+
131+
{{<image filename="images/rc/access-management-saml-config.png" alt="SAML Single Sign-On configuration screen.">}}
132+
133+
To do so, you need the following metadata values from your identity provider:
134+
135+
| Setting | Description |
136+
|---------|-------------|
137+
| **Issuer (IdP entity ID)** | The unique entity ID for the identity provider |
138+
| **IdP server URL** | The identity provider's HTTPS URL for SAML SSO |
139+
| **Single logout URL** | The URL used to sign out of the identity provider and connected apps (optional) |
140+
| **Assertion signing certificate** | Public SHA-256 certificate used to validate SAML assertions from the identity provider |
141+
142+
To find these metadata values, see your identity provider's documentation.
143+
144+
1. Select **Enable**.
145+
146+
1. From the **SAML activation** dialog box, select **Continue**.
147+
148+
### Download service provider metadata {#download-sp}
149+
150+
Next, you need to download the service provider metadata for Redis Enterprise Software and use it to finish configuring the SAML integration app for your identity provider:
151+
152+
1. Select the **Download** button to download the service provider [metadata](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf) in XML format.
153+
154+
1. Sign in to your identity provider's admin console.
155+
156+
1. Configure the Redis Enterprise Software service provider app with the downloaded XML.
157+
158+
- Some identity providers let you upload the XML file directly.
159+
160+
- Others require you to manually configure the service provider app with specific metadata fields, such as:
161+
162+
| XML attribute | Value | Description |
163+
|---------------|-------|-------------|
164+
| EntityDescriptor's **entityID** | https://<nobr>auth.redis.com</nobr>/saml2/<nobr>service-provider</nobr>/\<ID\> | Unique URL that identifies the Redis Enterprise Software service provider |
165+
| AssertionConsumerService's **Location** | <nobr> https://<nobr>auth.redis.com</nobr>/sso/saml2/\<ID\> | The service provider endpoint where the identity provider sends a SAML assertion that authenticates a user |
166+
167+
- To use [IdP-initiated SSO](#idp-initiated-sso) with certain identity providers, you also need to set the RelayState parameter to the following URL:
168+
169+
```sh
170+
https://cloud.redis.io/#/login/?idpId=<ID>
171+
```
172+
173+
> Replace `<ID>` so it matches the `AssertionConsumerService Location` URL's ID.
174+
175+
To learn more about how to configure service provider apps, see your identity provider's documentation.
176+
177+
### Activate SAML SSO {#activate-saml-sso}
178+
179+
After you finish the required SAML SSO configuration between your identity provider and Redis Enterprise Software cluster, you can test and activate SSO.
180+
181+
If SSO is enforced for the cluster, non-admin users can no longer sign in with their previous username and password and must use SSO instead.
182+
183+
To activate SAML SSO:
184+
185+
1. Sign out of any active SSO sessions with your identity provider.
186+
187+
1. For **Activate SAML integration**, select the **Activate SSO** button.
188+
189+
1. From the **Logout notification** dialog, select **Continue**. This redirects you to your configured identity provider's sign-in screen.
190+
191+
1. Sign in with your identity provider.
192+
193+
1. When redirected to the Redis Enterprise Software sign-in screen, you can either:
194+
195+
- Sign in with your local credentials as usual.
196+
197+
- Select **SSO** and enter the email address associated with the SAML user configured in your identity provider. Your user converts to a SAML user in Redis Enterprise Software.
198+
199+
{{<note>}}
200+
If you see a **SAML activation failed** notification when redirected to the Redis Enterprise Software sign-in screen, sign in with your local user credentials and review the SAML configuration for issues.
201+
{{</note>}}
202+
203+
## Update configuration {#update-config}
204+
205+
If you change certain metadata or configuration settings after you set up SSO, such as the assertion signing certificate, remember to do the following:
206+
207+
1. [Update the SAML SSO configuration](#configure-idp) with the new values.
208+
209+
1. [Download the updated service provider metadata](#download-sp) and use it to update the Redis Enterprise Software service provider app.
210+
211+
## Deactivate SAML SSO
212+
213+
To deactivate SAML SSO:
214+
215+
1. Go to **Access Control > Single Sign-On**.
216+
217+
1. TBA

0 commit comments

Comments
 (0)