Enable SSO authentication

Enable SAML-based SSO authentication for Redis Enterprise for Kubernetes.

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.

IdP requirements

Your identity provider must support:

• SAML 2.0 protocol
• Signed SAML responses
• HTTP-Redirect binding for SP-initiated SSO
• HTTP-POST binding for SAML assertions

Enable SSO

To enable SSO for your Redis Enterprise cluster (REC), follow these steps to configure SAML authentication.

Prerequisites

Before enabling SSO, ensure you have:

1. An existing Redis Enterprise cluster (REC) deployed in Kubernetes

2. External access to the Cluster Manager UI - The Cluster Manager UI must be accessible externally via a LoadBalancer service or Ingress so users can access it from their browser and the identity provider can redirect back after authentication. See Connect to the admin console for configuration options.

3. A SAML 2.0-compatible identity provider (such as Okta, Azure AD, or similar)

4. Admin access to your identity provider

5. A TLS certificate and private key for the service provider (SP)

Step 1: Upload Service Provider certificate and private key

The Service Provider certificate is used by the cluster to sign SAML requests and encrypt SAML responses.

1. Create a secret with your service provider certificate and private key:

   kubectl -n <rec-namespace> create secret generic sso-service-cert \
     --from-literal=name=sso_service \
     --from-file=certificate=<sp-cert-file> \
     --from-file=key=<sp-key-file>
   

   The secret must:

   • Reside within the same namespace as the RedisEnterpriseCluster custom resource.
   • Include a name key explicitly set to sso_service.
   • Include a certificate key with the public certificate in PEM format.
   • Include a key key with the private key in PEM format.

   Replace the <placeholders> in the command above with your own values.

2. Configure the service provider certificate in the RedisEnterpriseCluster custom resource:

   apiVersion: app.redislabs.com/v1
   kind: RedisEnterpriseCluster
   metadata:
     name: rec
   spec:
     nodes: 3
     certificates:
       ssoServiceCertificateSecretName: sso-service-cert
     sso:
       saml:
         spMetadataSecretName: sp-metadata  # Optional: store SP metadata in a secret
         serviceProvider:
           baseAddress: "https://redis-ui.example.com:443"  # Optional: customize base address
   

3. Apply the configuration:

   kubectl apply -f <rec-config-file>.yaml
   

Configure Service Provider base address (optional)

The base address is used to construct service provider URLs, such as the Assertion Consumer Service (ACS) URL and Single Logout (SLO) URL.

If not specified, the base address is automatically determined from the REC Cluster Manager UI service:

• If the UI service type is LoadBalancer (configured via spec.uiServiceType), the load balancer address is used.
• Otherwise, the cluster-internal DNS name is used (for example, rec-ui.svc.cluster.local).
• The port defaults to 8443 if not specified.

To explicitly set the base address, add it to the serviceProvider section:

spec:
  sso:
    saml:
      serviceProvider:
        baseAddress: "https://redis-ui.example.com:443"

Format: [<scheme>://]<hostname>[:<port>]

Examples:

• "https://redis-ui.example.com:443" (recommended - explicit scheme)
• "redis-ui.example.com:443" (defaults to https://)
• "http://redis-ui.example.com:9443" (NOT recommended for production)

Usage guidelines:

• 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.
• For Ingress: Set this to the ingress hostname and port (typically 443), for example, "https://redis-ui.example.com:443".

Step 2: Download Service Provider metadata

After applying the configuration, retrieve the service provider metadata to use when configuring your identity provider.

Option A: Retrieve from Kubernetes secret

If you configured spMetadataSecretName in Step 1, the operator creates a secret with the SP metadata:

kubectl -n <rec-namespace> get secret sp-metadata -o jsonpath='{.data.sp_metadata}' | base64 -d > sp-metadata.xml

Option B: Retrieve from the API

You can obtain the SP metadata directly from the Redis Enterprise Server API:

kubectl -n <rec-namespace> exec -it <rec-pod-name> -c redis-enterprise-node -- \
  curl -k -u "<username>:<password>" \
  https://localhost:9443/v1/cluster/sso/saml/metadata/sp > sp-metadata.xml

Replace <rec-pod-name>, <username>, and <password> with your cluster details.

Step 3: Set up SAML app in your identity provider

Use the Service Provider metadata from Step 2 to configure a SAML application in your identity provider.

1. Sign in to your identity provider's admin console (for example, Okta, Azure AD, Google Workspace).

2. Create a new SAML 2.0 application or integration.

3. Upload the sp-metadata.xml file or manually configure the SAML settings using values from the metadata:

   • Entity ID (SP): Found in the entityID attribute of the metadata
   • Assertion Consumer Service (ACS) URL: Found in the AssertionConsumerService element's Location attribute
   • Single Logout (SLO) URL: Found in the SingleLogoutService element's Location attribute (if present)

4. Configure the SAML assertion to include the following attributes:

   • email - User's email address (required)
   • firstName - User's first name (optional)
   • lastName - User's last name (optional)
   • redisRoleMapping - Role mapping for JIT user provisioning (required for new users)

Refer to your identity provider's documentation for specific configuration steps.

Step 4: Download identity provider metadata

After configuring the SAML app in your identity provider, download the identity provider metadata and certificate.

1. In your identity provider's admin console, locate the SAML app you created in Step 3.

2. Download the following:

   • IdP metadata XML: Contains the IdP configuration (entity ID, SSO URL, SLO URL)
   • IdP certificate: Public certificate used to verify SAML assertions

Save these files for use in Step 5.

Step 5: Configure SAML identity provider in Redis Enterprise

Now configure the identity provider details in your Redis Enterprise cluster.

1. Create a secret with the Identity Provider certificate:

   kubectl -n <rec-namespace> create secret generic sso-issuer-cert \
     --from-literal=name=sso_issuer \
     --from-file=certificate=<idp-cert-file>
   

   The secret must:

   • Reside within the same namespace as the RedisEnterpriseCluster custom resource.
   • Include a name key explicitly set to sso_issuer.
   • Include a certificate key with the IdP public certificate in PEM format.
   • Not include a key field (only the public certificate is needed).

   Replace <idp-cert-file> with the path to your IdP certificate file.

   Note:

   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.

2. Configure the IdP using one of the following options:

Option A: Use IdP metadata XML (recommended)

Using IdP metadata XML is the recommended approach as it's less error-prone.

1. Create a secret with the IdP metadata:

   kubectl -n <rec-namespace> create secret generic idp-metadata \
     --from-file=idp_metadata=<idp-metadata-file>.xml
   

   The secret must:

   • Reside within the same namespace as the RedisEnterpriseCluster custom resource.
   • Include an idp_metadata key with the IdP metadata XML content.
   • The XML can be plain text or base64-encoded; the operator handles encoding as needed.

   Replace <idp-metadata-file> with the path to your IdP metadata XML file.

2. Update the RedisEnterpriseCluster custom resource to add the IdP configuration:

   spec:
     certificates:
       ssoServiceCertificateSecretName: sso-service-cert
       ssoIssuerCertificateSecretName: sso-issuer-cert
     sso:
       saml:
         idpMetadataSecretName: idp-metadata
         spMetadataSecretName: sp-metadata
         serviceProvider:
           baseAddress: "https://redis-ui.example.com:443"
   

3. Apply the updated configuration:

   kubectl apply -f <rec-config-file>.yaml
   

Option B: Manual issuer configuration

If IdP metadata XML is unavailable, you can manually configure the issuer settings.

1. Update the RedisEnterpriseCluster custom resource with the IdP details:

   spec:
     certificates:
       ssoServiceCertificateSecretName: sso-service-cert
       ssoIssuerCertificateSecretName: sso-issuer-cert
     sso:
       saml:
         issuer:
           entityID: "urn:sso:example:idp"
           loginURL: "https://idp.example.com/sso/saml"
           logoutURL: "https://idp.example.com/slo/saml"  # optional
         spMetadataSecretName: sp-metadata
         serviceProvider:
           baseAddress: "https://redis-ui.example.com:443"
   

   Replace the values with your identity provider's configuration:

   • entityID: Identity Provider entity ID (issuer identifier)
   • loginURL: Identity Provider SSO login URL where SAML authentication requests are sent
   • logoutURL: Identity Provider single logout URL (optional)

2. Apply the updated configuration:

   kubectl apply -f <rec-config-file>.yaml
   

Step 6: Assign SAML app to users

In your identity provider's admin console, assign users to the SAML application you created in Step 3.

1. Navigate to the SAML app in your identity provider.

2. Assign existing users or groups to the application.

3. For new users who will use just-in-time (JIT) provisioning, ensure the redisRoleMapping attribute is configured with appropriate Redis Enterprise roles.

Refer to your identity provider's documentation for specific steps on assigning users to applications.

Step 7: Activate SSO

Finally, activate SSO by enabling it in the RedisEnterpriseCluster custom resource.

1. Update the RedisEnterpriseCluster custom resource to enable SSO:

   spec:
     certificates:
       ssoServiceCertificateSecretName: sso-service-cert
       ssoIssuerCertificateSecretName: sso-issuer-cert
     sso:
       enabled: true
       enforceSSO: false  # Set to true to disable local authentication for non-admin users
       saml:
         idpMetadataSecretName: idp-metadata
         spMetadataSecretName: sp-metadata
         serviceProvider:
           baseAddress: "https://redis-ui.example.com:443"
   

2. Apply the configuration:

   kubectl apply -f <rec-config-file>.yaml
   

3. Test SSO by accessing the Cluster Manager UI and clicking Sign in with SSO.

Complete example

Here's a complete example of a RedisEnterpriseCluster resource with SSO enabled:

apiVersion: app.redislabs.com/v1
kind: RedisEnterpriseCluster
metadata:
  name: rec
spec:
  nodes: 3
  certificates:
    ssoServiceCertificateSecretName: sso-service-cert
    ssoIssuerCertificateSecretName: sso-issuer-cert
  sso:
    enabled: true
    enforceSSO: false
    saml:
      idpMetadataSecretName: idp-metadata
      spMetadataSecretName: sp-metadata
      serviceProvider:
        baseAddress: "https://redis-ui.example.com:443"

Refer to the RedisEnterpriseCluster API reference for full details on the available fields.

Next steps

After enabling SSO:

1. Configure users in your identity provider with matching email addresses
2. Set up the redisRoleMapping attribute in your identity provider to assign appropriate roles for new users
3. Test both IdP-initiated and SP-initiated SSO flows

For more information about Redis Enterprise Software security, see Access control.