{
  "id": "sso",
  "title": "Enable SSO authentication",
  "url": "https://redis.io/docs/latest/operate/kubernetes/8.0.18/security/sso/",
  "summary": "Enable SAML-based SSO authentication for Redis Enterprise for Kubernetes.",
  "content": "\n\nRedis 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.\n\n\n## IdP requirements\n\nYour identity provider must support:\n\n- SAML 2.0 protocol\n- Signed SAML responses\n- HTTP-Redirect binding for SP-initiated SSO\n- HTTP-POST binding for SAML assertions\n\n## Enable SSO\n\nTo enable SSO for your Redis Enterprise cluster (REC), follow these steps to configure SAML authentication.\n\n### Prerequisites\n\nBefore enabling SSO, ensure you have:\n\n\n1. An existing Redis Enterprise cluster (REC) deployed in Kubernetes\n\n2. **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](https://redis.io/docs/latest/operate/kubernetes/re-clusters/connect-to-admin-console.md) for configuration options.\n\n3. A SAML 2.0-compatible identity provider (such as Okta, Azure AD, or similar)\n\n4. Admin access to your identity provider\n\n5. A TLS certificate and private key for the service provider (SP)\n\n\nSSO requires external access to the Cluster Manager UI. Port forwarding is not sufficient for SSO authentication because the identity provider needs to redirect users back to the UI after authentication. You must configure either a LoadBalancer service (via `spec.uiServiceType: LoadBalancer`) or an Ingress controller.\n\n\n### Step 1: Upload Service Provider certificate and private key\n\nThe Service Provider certificate is used by the cluster to sign SAML requests and encrypt SAML responses.\n\n1. Create a secret with your service provider certificate and private key:\n\n    ```sh\n    kubectl -n \u003crec-namespace\u003e create secret generic sso-service-cert \\\n      --from-literal=name=sso_service \\\n      --from-file=certificate=\u003csp-cert-file\u003e \\\n      --from-file=key=\u003csp-key-file\u003e\n    ```\n\n    The secret must:\n    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.\n    - Include a `name` key explicitly set to `sso_service`.\n    - Include a `certificate` key with the public certificate in PEM format.\n    - Include a `key` key with the private key in PEM format.\n\n    Replace the `\u003cplaceholders\u003e` in the command above with your own values.\n\n2. Configure the service provider certificate in the `RedisEnterpriseCluster` custom resource:\n\n    ```yaml\n    apiVersion: app.redislabs.com/v1\n    kind: RedisEnterpriseCluster\n    metadata:\n      name: rec\n    spec:\n      nodes: 3\n      certificates:\n        ssoServiceCertificateSecretName: sso-service-cert\n      sso:\n        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration\n        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users\n        saml:\n          spMetadataSecretName: sp-metadata  # Optional: store SP metadata in a secret\n          serviceProvider:\n            baseAddress: \"https://redis-ui.example.com:443\"  # Optional: customize base address\n    ```\n\n3. Apply the configuration:\n\n    ```sh\n    kubectl apply -f \u003crec-config-file\u003e.yaml\n    ```\n\n#### Configure Service Provider base address (optional)\n\nThe base address is used to construct service provider URLs, such as the Assertion Consumer Service (ACS) URL and Single Logout (SLO) URL.\n\nIf not specified, the base address is automatically determined from the REC Cluster Manager UI service:\n- If the UI service type is `LoadBalancer` (configured via `spec.uiServiceType`), the load balancer address is used.\n- Otherwise, the cluster-internal DNS name is used (for example, `rec-ui.svc.cluster.local`).\n- The port defaults to 8443 if not specified.\n\nTo explicitly set the base address, add it to the `serviceProvider` section:\n\n```yaml\nspec:\n  sso:\n    saml:\n      serviceProvider:\n        baseAddress: \"https://redis-ui.example.com:443\"\n```\n\nFormat: `[\u003cscheme\u003e://]\u003chostname\u003e[:\u003cport\u003e]`\n\nExamples:\n- `\"https://redis-ui.example.com:443\"` (recommended - explicit scheme)\n- `\"redis-ui.example.com:443\"` (defaults to https://)\n- `\"http://redis-ui.example.com:9443\"` (NOT recommended for production)\n\n\nUsing `http://` is NOT recommended for production environments as it transmits sensitive SAML assertions in plaintext. Only use `http://` for testing or development purposes.\n\n\n**Usage guidelines:**\n- **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.\n- **For Ingress:** Set this to the ingress hostname and port (typically 443), for example, `\"https://redis-ui.example.com:443\"`.\n\n### Step 2: Download Service Provider metadata\n\nAfter applying the configuration, retrieve the service provider metadata to use when configuring your identity provider.\n\n#### Option A: Retrieve from Kubernetes secret\n\nIf you configured `spMetadataSecretName` in Step 1, the operator creates a secret with the SP metadata:\n\n```sh\nkubectl -n \u003crec-namespace\u003e get secret sp-metadata -o jsonpath='{.data.sp_metadata}' | base64 -d \u003e sp-metadata.xml\n```\n\n\nThis 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.\n\n\n#### Option B: Retrieve from the API\n\nYou can obtain the SP metadata directly from the Redis Enterprise Server API:\n\n```sh\nkubectl -n \u003crec-namespace\u003e exec -it \u003crec-pod-name\u003e -c redis-enterprise-node -- \\\n  curl -k -u \"\u003cusername\u003e:\u003cpassword\u003e\" \\\n  https://localhost:9443/v1/cluster/sso/saml/metadata/sp \u003e sp-metadata.xml\n```\n\nReplace `\u003crec-pod-name\u003e`, `\u003cusername\u003e`, and `\u003cpassword\u003e` with your cluster details.\n\n### Step 3: Set up SAML app in your identity provider\n\nUse the Service Provider metadata from Step 2 to configure a SAML application in your identity provider.\n\n1. Sign in to your identity provider's admin console (for example, Okta, Azure AD, Google Workspace).\n\n2. Create a new SAML 2.0 application or integration.\n\n3. Upload the `sp-metadata.xml` file or manually configure the SAML settings using values from the metadata:\n   - **Entity ID (SP)**: Found in the `entityID` attribute of the metadata\n   - **Assertion Consumer Service (ACS) URL**: Found in the `AssertionConsumerService` element's `Location` attribute\n   - **Single Logout (SLO) URL**: Found in the `SingleLogoutService` element's `Location` attribute (if present)\n\n4. Configure the SAML assertion to include the following attributes:\n   - `email` - User's email address (required)\n   - `firstName` - User's first name (optional)\n   - `lastName` - User's last name (optional)\n   - `redisRoleMapping` - Role mapping for JIT user provisioning (required for new users)\n\nRefer to your identity provider's documentation for specific configuration steps.\n\n### Step 4: Download identity provider metadata\n\nAfter configuring the SAML app in your identity provider, download the identity provider metadata and certificate.\n\n1. In your identity provider's admin console, locate the SAML app you created in Step 3.\n\n2. Download the following:\n   - **IdP metadata XML**: Contains the IdP configuration (entity ID, SSO URL, SLO URL)\n   - **IdP certificate**: Public certificate used to verify SAML assertions\n\nSave these files for use in Step 5.\n\n### Step 5: Configure SAML identity provider in Redis Enterprise\n\nNow configure the identity provider details in your Redis Enterprise cluster.\n\n1. Create a secret with the Identity Provider certificate:\n\n    ```sh\n    kubectl -n \u003crec-namespace\u003e create secret generic sso-issuer-cert \\\n      --from-literal=name=sso_issuer \\\n      --from-file=certificate=\u003cidp-cert-file\u003e\n    ```\n\n    The secret must:\n    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.\n    - Include a `name` key explicitly set to `sso_issuer`.\n    - Include a `certificate` key with the IdP public certificate in PEM format.\n    - **Not** include a `key` field (only the public certificate is needed).\n\n    Replace `\u003cidp-cert-file\u003e` with the path to your IdP certificate file.\n\n    \nWhile 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.\n    \n\n2. Configure the IdP using one of the following options:\n\n#### Option A: Use IdP metadata XML (recommended)\n\nUsing IdP metadata XML is the recommended approach as it's less error-prone.\n\n1. Create a secret with the IdP metadata:\n\n    ```sh\n    kubectl -n \u003crec-namespace\u003e create secret generic idp-metadata \\\n      --from-file=idp_metadata=\u003cidp-metadata-file\u003e.xml\n    ```\n\n    The secret must:\n    - Reside within the same namespace as the `RedisEnterpriseCluster` custom resource.\n    - Include an `idp_metadata` key with the IdP metadata XML content.\n    - The XML can be plain text or base64-encoded; the operator handles encoding as needed.\n\n    Replace `\u003cidp-metadata-file\u003e` with the path to your IdP metadata XML file.\n\n2. Update the `RedisEnterpriseCluster` custom resource to add the IdP configuration:\n\n    ```yaml\n    spec:\n      certificates:\n        ssoServiceCertificateSecretName: sso-service-cert\n        ssoIssuerCertificateSecretName: sso-issuer-cert\n      sso:\n        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration\n        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users\n        saml:\n          idpMetadataSecretName: idp-metadata\n          spMetadataSecretName: sp-metadata\n          serviceProvider:\n            baseAddress: \"https://redis-ui.example.com:443\"\n    ```\n\n3. Apply the updated configuration:\n\n    ```sh\n    kubectl apply -f \u003crec-config-file\u003e.yaml\n    ```\n\n#### Option B: Manual issuer configuration\n\nIf IdP metadata XML is unavailable, you can manually configure the issuer settings.\n\n1. Update the `RedisEnterpriseCluster` custom resource with the IdP details:\n\n    ```yaml\n    spec:\n      certificates:\n        ssoServiceCertificateSecretName: sso-service-cert\n        ssoIssuerCertificateSecretName: sso-issuer-cert\n      sso:\n        enabled: false  # SSO not yet active - set to true in Step 7 after completing configuration\n        enforceSSO: false  # Optional: set to true to disable local authentication for non-admin users\n        saml:\n          issuer:\n            entityID: \"urn:sso:example:idp\"\n            loginURL: \"https://idp.example.com/sso/saml\"\n            logoutURL: \"https://idp.example.com/slo/saml\"  # optional\n          spMetadataSecretName: sp-metadata\n          serviceProvider:\n            baseAddress: \"https://redis-ui.example.com:443\"\n    ```\n\n    Replace the values with your identity provider's configuration:\n\n    - `entityID`: Identity Provider entity ID (issuer identifier)\n    - `loginURL`: Identity Provider SSO login URL where SAML authentication requests are sent\n    - `logoutURL`: Identity Provider single logout URL (optional)\n\n2. Apply the updated configuration:\n\n    ```sh\n    kubectl apply -f \u003crec-config-file\u003e.yaml\n    ```\n\n\nIf both `idpMetadataSecretName` and `issuer` are provided, `idpMetadataSecretName` takes precedence and `issuer` is ignored.\n\n\n### Step 6: Assign SAML app to users\n\nIn your identity provider's admin console, assign users to the SAML application you created in Step 3.\n\n1. Navigate to the SAML app in your identity provider.\n\n2. Assign existing users or groups to the application.\n\n3. For new users who will use just-in-time (JIT) provisioning, ensure the `redisRoleMapping` attribute is configured with appropriate Redis Enterprise roles.\n\nRefer to your identity provider's documentation for specific steps on assigning users to applications.\n\n### Step 7: Activate SSO\n\nFinally, activate SSO by enabling it in the `RedisEnterpriseCluster` custom resource.\n\n1. Update the `RedisEnterpriseCluster` custom resource to enable SSO:\n\n    ```yaml\n    spec:\n      certificates:\n        ssoServiceCertificateSecretName: sso-service-cert\n        ssoIssuerCertificateSecretName: sso-issuer-cert\n      sso:\n        enabled: true\n        enforceSSO: false  # Set to true to disable local authentication for non-admin users\n        saml:\n          idpMetadataSecretName: idp-metadata\n          spMetadataSecretName: sp-metadata\n          serviceProvider:\n            baseAddress: \"https://redis-ui.example.com:443\"\n    ```\n\n2. Apply the configuration:\n\n    ```sh\n    kubectl apply -f \u003crec-config-file\u003e.yaml\n    ```\n\n3. Test SSO by accessing the Cluster Manager UI and clicking **Sign in with SSO**.\n\n## Complete example\n\nHere's a complete example of a `RedisEnterpriseCluster` resource with SSO enabled:\n\n```yaml\napiVersion: app.redislabs.com/v1\nkind: RedisEnterpriseCluster\nmetadata:\n  name: rec\nspec:\n  nodes: 3\n  certificates:\n    ssoServiceCertificateSecretName: sso-service-cert\n    ssoIssuerCertificateSecretName: sso-issuer-cert\n  sso:\n    enabled: true\n    enforceSSO: false\n    saml:\n      idpMetadataSecretName: idp-metadata\n      spMetadataSecretName: sp-metadata\n      serviceProvider:\n        baseAddress: \"https://redis-ui.example.com:443\"\n```\n\nRefer 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.\n\n## Next steps\n\nAfter enabling SSO:\n\n1. Configure users in your identity provider with matching email addresses\n2. Set up the `redisRoleMapping` attribute in your identity provider to assign appropriate roles for new users\n3. Test both IdP-initiated and SP-initiated SSO flows\n\nFor more information about Redis Enterprise Software security, see [Access control](https://redis.io/docs/latest/operate/rs/security/access-control/).\n",
  "tags": ["docs","operate","kubernetes"],
  "last_updated": "2026-06-04T14:49:57+01:00"
}