Skip to content

Commit 2224ef1

Browse files
kaitlynmichaelkaitlynmichael
committed
AI rough draft
1 parent 81c447a commit 2224ef1

File tree

2 files changed

+369
-0
lines changed

2 files changed

+369
-0
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Manage cluster credentials and authentication settings:
2020
- [Manage REC credentials]({{< relref "/operate/kubernetes/security/manage-rec-credentials" >}}) - Configure and manage Redis Enterprise cluster credentials
2121
- [Configuration secrets]({{< relref "/operate/kubernetes/security/configuration-secrets" >}}) - Store Redis Enterprise configuration items in Kubernetes Secrets for automatic updates and secure management
2222
- [LDAP authentication]({{< relref "/operate/kubernetes/security/ldap" >}}) - Integrate with LDAP for centralized authentication
23+
- [SSO authentication]({{< relref "/operate/kubernetes/security/sso" >}}) - Enable SAML-based single sign-on for Cluster Manager UI access
2324

2425
## Certificates and encryption
2526

‎content/operate/kubernetes/security/sso.md‎

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
---
2+
Title: Enable SSO authentication
3+
alwaysopen: false
4+
categories:
5+
- docs
6+
- operate
7+
- kubernetes
8+
description: Enable SAML-based SSO authentication for Redis Enterprise for Kubernetes.
9+
linkTitle: Enable SSO
10+
weight: 94
11+
---
12+
13+
Redis Enterprise Software supports SAML 2.0 single sign-on (SSO) for the Cluster Manager UI with both IdP-initiated and SP-initiated authentication. User accounts are automatically created on first sign-in using just-in-time (JIT) provisioning.
14+
15+
## IdP requirements
16+
17+
Your identity provider must support:
18+
19+
- SAML 2.0 protocol
20+
- Signed SAML responses
21+
- HTTP-Redirect binding for SP-initiated SSO
22+
- HTTP-POST binding for SAML assertions
23+
24+
## Enable SSO
25+
26+
To enable SSO for your Redis Enterprise cluster (REC), follow these steps to configure SAML authentication.
27+
28+
### Prerequisites
29+
30+
Before enabling SSO, ensure you have:
31+
32+
1. A SAML 2.0-compatible identity provider (such as Okta, Azure AD, or similar)
33+
2. Admin access to your identity provider
34+
3. A TLS certificate and private key for the Service Provider (SP)
35+
36+
### Step 1: Upload Service Provider certificate and private key
37+
38+
The Service Provider certificate is used by the cluster to sign SAML requests and encrypt SAML responses.
39+
40+
1. Create a secret with your Service Provider certificate and private key:
41+
42+
```sh
43+
kubectl -n <rec-namespace> create secret generic sso-service-cert \
44+
--from-literal=name=sso_service \
45+
--from-file=certificate=<sp-cert-file> \
46+
--from-file=key=<sp-key-file>
47+
```
48+
49+
The secret must:
50+
- Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
51+
- Include a `name` key explicitly set to `sso_service`.
52+
- Include a `certificate` key with the public certificate in PEM format.
53+
- Include a `key` key with the private key in PEM format.
54+
55+
Replace the `<placeholders>` in the command above with your own values.
56+
57+
2. Configure the Service Provider certificate in the `RedisEnterpriseCluster` custom resource:
58+
59+
```yaml
60+
apiVersion: app.redislabs.com/v1
61+
kind: RedisEnterpriseCluster
62+
metadata:
63+
name: rec
64+
spec:
65+
nodes: 3
66+
certificates:
67+
ssoServiceCertificateSecretName: sso-service-cert
68+
sso:
69+
saml:
70+
spMetadataSecretName: sp-metadata # Optional: store SP metadata in a secret
71+
serviceProvider:
72+
baseAddress: "https://redis-ui.example.com:443" # Optional: customize base address
73+
```
74+
75+
3. Apply the configuration:
76+
77+
```sh
78+
kubectl apply -f <rec-config-file>.yaml
79+
```
80+
81+
#### Configure Service Provider base address (optional)
82+
83+
The base address is used to construct Service Provider URLs, such as the Assertion Consumer Service (ACS) URL and Single Logout (SLO) URL.
84+
85+
If not specified, the base address is automatically determined from the REC Cluster Manager UI service:
86+
- If the UI service type is `LoadBalancer` (configured via `spec.uiServiceType`), the load balancer address is used.
87+
- Otherwise, the cluster-internal DNS name is used (for example, `rec-ui.svc.cluster.local`).
88+
- The port defaults to 8443 if not specified.
89+
90+
To explicitly set the base address, add it to the `serviceProvider` section:
91+
92+
```yaml
93+
spec:
94+
sso:
95+
saml:
96+
serviceProvider:
97+
baseAddress: "https://redis-ui.example.com:443"
98+
```
99+
100+
Format: `[<scheme>://]<hostname>[:<port>]`
101+
102+
Examples:
103+
- `"https://redis-ui.example.com:443"` (recommended - explicit scheme)
104+
- `"redis-ui.example.com:443"` (defaults to https://)
105+
- `"http://redis-ui.example.com:9443"` (NOT recommended for production)
106+
107+
{{<warning>}}
108+
Using `http://` is NOT recommended for production environments as it transmits sensitive SAML assertions in plaintext. Only use `http://` for testing or development purposes.
109+
{{</warning>}}
110+
111+
**Usage guidelines:**
112+
- **For LoadBalancer services:** Leave this field blank to use the default REC UI service, or set it explicitly to the LoadBalancer address for custom services.
113+
- **For Ingress:** Set this to the ingress hostname and port (typically 443), for example, `"https://redis-ui.example.com:443"`.
114+
115+
### Step 2: Download Service Provider metadata
116+
117+
After applying the configuration, retrieve the Service Provider metadata to use when configuring your identity provider.
118+
119+
#### Option A: Retrieve from Kubernetes secret
120+
121+
If you configured `spMetadataSecretName` in Step 1, the operator creates a secret with the SP metadata:
122+
123+
```sh
124+
kubectl -n <rec-namespace> get secret sp-metadata -o jsonpath='{.data.sp_metadata}' | base64 -d > sp-metadata.xml
125+
```
126+
127+
{{<note>}}
128+
This secret is only created when the cluster is configured to use Kubernetes secrets (`spec.clusterCredentialSecretType` is unset or set to `"kubernetes"`). When using Vault secrets, use Option B instead.
129+
{{</note>}}
130+
131+
#### Option B: Retrieve from the API
132+
133+
You can obtain the SP metadata directly from the Redis Enterprise Server API:
134+
135+
```sh
136+
kubectl -n <rec-namespace> exec -it <rec-pod-name> -c redis-enterprise-node -- \
137+
curl -k -u "<username>:<password>" \
138+
https://localhost:9443/v1/cluster/sso/saml/metadata/sp > sp-metadata.xml
139+
```
140+
141+
Replace `<rec-pod-name>`, `<username>`, and `<password>` with your cluster details.
142+
143+
### Step 3: Set up SAML app in your identity provider
144+
145+
Use the Service Provider metadata from Step 2 to configure a SAML application in your identity provider.
146+
147+
1. Sign in to your identity provider's admin console (for example, Okta, Azure AD, Google Workspace).
148+
149+
2. Create a new SAML 2.0 application or integration.
150+
151+
3. Upload the `sp-metadata.xml` file or manually configure the SAML settings using values from the metadata:
152+
- **Entity ID (SP)**: Found in the `entityID` attribute of the metadata
153+
- **Assertion Consumer Service (ACS) URL**: Found in the `AssertionConsumerService` element's `Location` attribute
154+
- **Single Logout (SLO) URL**: Found in the `SingleLogoutService` element's `Location` attribute (if present)
155+
156+
4. Configure the SAML assertion to include the following attributes:
157+
- `email` - User's email address (required)
158+
- `firstName` - User's first name (optional)
159+
- `lastName` - User's last name (optional)
160+
- `redisRoleMapping` - Role mapping for JIT user provisioning (required for new users)
161+
162+
Refer to your identity provider's documentation for specific configuration steps.
163+
164+
### Step 4: Download identity provider metadata
165+
166+
After configuring the SAML app in your identity provider, download the identity provider metadata and certificate.
167+
168+
1. In your identity provider's admin console, locate the SAML app you created in Step 3.
169+
170+
2. Download the following:
171+
- **IdP metadata XML**: Contains the IdP configuration (entity ID, SSO URL, SLO URL)
172+
- **IdP certificate**: Public certificate used to verify SAML assertions
173+
174+
Save these files for use in Step 5.
175+
176+
### Step 5: Configure SAML identity provider in Redis Enterprise
177+
178+
Now configure the identity provider details in your Redis Enterprise cluster.
179+
180+
1. Create a secret with the Identity Provider certificate:
181+
182+
```sh
183+
kubectl -n <rec-namespace> create secret generic sso-issuer-cert \
184+
--from-literal=name=sso_issuer \
185+
--from-file=certificate=<idp-cert-file>
186+
```
187+
188+
The secret must:
189+
- Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
190+
- Include a `name` key explicitly set to `sso_issuer`.
191+
- Include a `certificate` key with the IdP public certificate in PEM format.
192+
- **Not** include a `key` field (only the public certificate is needed).
193+
194+
Replace `<idp-cert-file>` with the path to your IdP certificate file.
195+
196+
{{<note>}}
197+
While IdP metadata XML may contain the certificate, Redis Enterprise Server does not use it from there, so the certificate must be provided separately via this secret.
198+
{{</note>}}
199+
200+
2. Configure the IdP using one of the following options:
201+
202+
#### Option A: Use IdP metadata XML (recommended)
203+
204+
Using IdP metadata XML is the recommended approach as it's less error-prone.
205+
206+
1. Create a secret with the IdP metadata:
207+
208+
```sh
209+
kubectl -n <rec-namespace> create secret generic idp-metadata \
210+
--from-file=idp_metadata=<idp-metadata-file>.xml
211+
```
212+
213+
The secret must:
214+
- Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.
215+
- Include an `idp_metadata` key with the IdP metadata XML content.
216+
- The XML can be plain text or base64-encoded; the operator handles encoding as needed.
217+
218+
Replace `<idp-metadata-file>` with the path to your IdP metadata XML file.
219+
220+
2. Update the `RedisEnterpriseCluster` custom resource to add the IdP configuration:
221+
222+
```yaml
223+
spec:
224+
certificates:
225+
ssoServiceCertificateSecretName: sso-service-cert
226+
ssoIssuerCertificateSecretName: sso-issuer-cert
227+
sso:
228+
saml:
229+
idpMetadataSecretName: idp-metadata
230+
spMetadataSecretName: sp-metadata
231+
serviceProvider:
232+
baseAddress: "https://redis-ui.example.com:443"
233+
```
234+
235+
3. Apply the updated configuration:
236+
237+
```sh
238+
kubectl apply -f <rec-config-file>.yaml
239+
```
240+
241+
#### Option B: Manual issuer configuration
242+
243+
If IdP metadata XML is unavailable, you can manually configure the issuer settings.
244+
245+
1. Update the `RedisEnterpriseCluster` custom resource with the IdP details:
246+
247+
```yaml
248+
spec:
249+
certificates:
250+
ssoServiceCertificateSecretName: sso-service-cert
251+
ssoIssuerCertificateSecretName: sso-issuer-cert
252+
sso:
253+
saml:
254+
issuer:
255+
entityID: "urn:sso:example:idp"
256+
loginURL: "https://idp.example.com/sso/saml"
257+
logoutURL: "https://idp.example.com/slo/saml" # optional
258+
spMetadataSecretName: sp-metadata
259+
serviceProvider:
260+
baseAddress: "https://redis-ui.example.com:443"
261+
```
262+
263+
Replace the values with your identity provider's configuration:
264+
265+
- `entityID`: Identity Provider entity ID (issuer identifier)
266+
- `loginURL`: Identity Provider SSO login URL where SAML authentication requests are sent
267+
- `logoutURL`: Identity Provider single logout URL (optional)
268+
269+
2. Apply the updated configuration:
270+
271+
```sh
272+
kubectl apply -f <rec-config-file>.yaml
273+
```
274+
275+
{{<note>}}
276+
If both `idpMetadataSecretName` and `issuer` are provided, `idpMetadataSecretName` takes precedence and `issuer` is ignored.
277+
{{</note>}}
278+
279+
### Step 6: Assign SAML app to users
280+
281+
In your identity provider's admin console, assign users to the SAML application you created in Step 3.
282+
283+
1. Navigate to the SAML app in your identity provider.
284+
285+
2. Assign existing users or groups to the application.
286+
287+
3. For new users who will use just-in-time (JIT) provisioning, ensure the `redisRoleMapping` attribute is configured with appropriate Redis Enterprise roles.
288+
289+
Refer to your identity provider's documentation for specific steps on assigning users to applications.
290+
291+
### Step 7: Activate SSO
292+
293+
Finally, activate SSO by enabling it in the `RedisEnterpriseCluster` custom resource.
294+
295+
1. Update the `RedisEnterpriseCluster` custom resource to enable SSO:
296+
297+
```yaml
298+
spec:
299+
certificates:
300+
ssoServiceCertificateSecretName: sso-service-cert
301+
ssoIssuerCertificateSecretName: sso-issuer-cert
302+
sso:
303+
enabled: true
304+
enforceSSO: false # Set to true to disable local authentication for non-admin users
305+
saml:
306+
idpMetadataSecretName: idp-metadata
307+
spMetadataSecretName: sp-metadata
308+
serviceProvider:
309+
baseAddress: "https://redis-ui.example.com:443"
310+
```
311+
312+
2. Apply the configuration:
313+
314+
```sh
315+
kubectl apply -f <rec-config-file>.yaml
316+
```
317+
318+
3. Test SSO by accessing the Cluster Manager UI and clicking **Sign in with SSO**.
319+
320+
#### Enforce SSO (optional)
321+
322+
By default, both SSO and local username/password authentication are available. To enforce SSO-only authentication for non-admin users, set `enforceSSO` to `true`:
323+
324+
```yaml
325+
spec:
326+
sso:
327+
enabled: true
328+
enforceSSO: true
329+
```
330+
331+
When `enforceSSO` is set to `true`, local username/password authentication is disabled for non-admin users.
332+
333+
## Complete example
334+
335+
Here's a complete example of a `RedisEnterpriseCluster` resource with SSO enabled:
336+
337+
```yaml
338+
apiVersion: app.redislabs.com/v1
339+
kind: RedisEnterpriseCluster
340+
metadata:
341+
name: rec
342+
spec:
343+
nodes: 3
344+
certificates:
345+
ssoServiceCertificateSecretName: sso-service-cert
346+
ssoIssuerCertificateSecretName: sso-issuer-cert
347+
sso:
348+
enabled: true
349+
enforceSSO: false
350+
saml:
351+
idpMetadataSecretName: idp-metadata
352+
spMetadataSecretName: sp-metadata
353+
serviceProvider:
354+
baseAddress: "https://redis-ui.example.com:443"
355+
```
356+
357+
Refer to the `RedisEnterpriseCluster` [API reference](https://github.com/RedisLabs/redis-enterprise-k8s-docs/blob/master/redis_enterprise_cluster_api.md#ssospec) for full details on the available fields.
358+
359+
## Next steps
360+
361+
After enabling SSO:
362+
363+
1. Configure users in your identity provider with matching email addresses
364+
2. Set up the `redisRoleMapping` attribute in your identity provider to assign appropriate roles for new users
365+
3. Test both IdP-initiated and SP-initiated SSO flows
366+
4. Consider enforcing SSO to disable local authentication for non-admin users
367+
368+
For more information about Redis Enterprise Software security, see [Access control]({{< relref "/operate/rs/security/access-control/" >}}).

0 commit comments

Comments
 (0)