SAML SSO Troubleshooting Guide for Redis Software

Redis Software supports SAML 2.0 single-sign-on for authenticating users into the Redis Software UI. When SAML authentication fails, the root cause is almost always related to assertion attributes, role mapping, certificate trust, or Identity Provider configuration drift. This guide focuses on diagnosing and resolving common SAML SSO activation and login issues after initial setup, with practical fixes based on real support cases.

Quick Fix Table

Prerequisites

Before troubleshooting, ensure you have:

• Admin access to the Redis Software UI

• Admin access to your Identity Provider (Okta, Azure Entra ID, Ping, Auth0, etc.)

• Access to the SAML application configuration in the IdP

• Ability to inspect SAML assertions using a browser SAML tracing tool

Step-by-Step Troubleshooting

1. Verify Required SAML Attributes

Redis Software requires specific attributes to be present in the SAML assertion.

• For all SSO logins, the SAML assertion must include:

  • firstName

  • lastName

  • email

• For JIT-provisioned new users, the assertion must also include:

  • redisRoleMapping (a string array of Redis Enterprise role UIDs used for role-based access control during account creation).

  • If any of the required attributes for the specific flow (existing user vs new JIT user) are missing or empty, SAML authentication fails, and the user is redirected back to the login page.

Verify the SAML Subject (NameID):

• The NameID in the SAML assertion should contain the user’s email address (using the emailAddress format).

• That email must match either the username or email field of the corresponding user in Redis Enterprise.

• A mismatch here commonly results in a redirect back to the login page or a generic 400 error even when attributes appear correct.

2. Validate Role Mapping and Case Sensitivity

The redisRoleMapping attribute must map users to valid Redis Enterprise roles:

• redisRoleMapping is a string array of role UIDs (not display names).

• Role UIDs are case-sensitive. If they don’t match exactly, the role assignment during JIT provisioning fails.

• You can assign multiple roles by including more than one role UID in the array; Redis will attach all of them when creating the user.

• For existing users, redisRoleMapping is ignored and their current roles in Redis Enterprise are preserved. It only affects new JIT-provisioned users.

If a new JIT user logs in and ends up with no access, inspect redisRoleMapping in the SAML assertion and verify that every value corresponds to a valid role UID defined in the Redis Enterprise UI.

This check is the most critical for new JIT users. If an existing user logs in but lacks access, inspect their assigned roles directly in the Redis Enterprise UI. Changing redisRoleMapping alone will not update roles for users that already exist.

3. Confirm the Activating User Has Admin Access

The user enabling SAML SSO must already be a valid Redis Software admin.

• If SSO is enforced, non-admin users can no longer sign in with local usernames and passwords and must use SSO instead.

• Admin users can still log in locally even when SSO is enforced. Always retain at least one local admin to recover from SSO misconfiguration (for example, to disable enforcement or fix IdP settings).

4. Check Certificate Formatting and Trust

Certificate issues are a common cause of SAML failures.

• Paste the IdP X.509 certificate exactly as provided

• Do not modify headers or line breaks unless explicitly required

• Expired or rotated IdP certificates require metadata refresh

• Redis Enterprise Software requires signed SAML responses and validates them against the IdP X.509 certificate you configure. If the certificate is wrong, expired, or rotated in the IdP without updating Redis Enterprise, responses fail signature validation, and the user typically sees a generic error (for example, HTTP 400).

After updating certificates, re-download and apply updated metadata if needed.

5. Validate Identity Provider Configuration

Common IdP-specific issues include:

• Custom attributes not added to the SAML app

• Attributes defined but not assigned to users

• Binding mismatch (POST vs redirect)

• Incorrect ACS or entity ID values

For Okta, make sure attributes are defined in the Profile Editor and assigned to the app.
For Google Workspace, attributes must be configured per user.

6. Refresh Metadata After Changes

Any change to certificates, attributes, or endpoints requires metadata updates.

• Download updated IdP metadata

• Reapply it in the Redis UI

• Restart the authentication flow

7. Test in a Clean Browser Session

Browser state can interfere with SAML flows.

• Use an incognito or private window

• Disable extensions that modify requests

• Retry login after clearing cookies

Advanced Diagnostics

SAML Assertion Tracing

Use a browser SAML tracing tool to confirm:

• Assertions are signed

• Required attributes are present

• Attribute values match expected formats

HAR File Capture

If errors persist, capture a HAR file during login and provide it to Redis Support for deeper analysis.

When to Contact Redis Support

Contact Redis Support if:

• Assertions validate correctly, but Redis rejects authentication

• Metadata refresh doesn't resolve certificate-related failures

• Errors persist across users and IdPs

Include:

• Redis version

• IdP type

• SAML trace or HAR file

• Exact error message from the UI

Additional Resources

• Redis Software SAML SSO configuration

• Redis Enterprise 8.0.6 release notes