Shuffle SSO with OpenID Connect and SAML guide

Why teams set up Shuffle SSO with OpenID Connect or SAML

A security team running Shuffle SOAR usually wants analysts to sign in with their corporate identities instead of local Shuffle accounts. Single sign-on removes separate passwords from the platform and ties access to the directory, so joiners, movers and leavers are handled where the organization already manages them. Shuffle supports two options for this: OpenID Connect and SAML. Per-tenant SSO enforcement is the control that makes sign-in through the identity provider mandatory for a given tenant, which is the setting you will verify before any analyst is moved over.

The setup looks like a configuration task but has several points where it fails quietly. Redirect URIs registered at the identity provider must match the exact address Shuffle sends users back to, including scheme, host and path, so a mismatch after a DNS or TLS change will block sign-in. Claim mapping decides which attributes Shuffle reads for the user's identity and email, and an unexpected claim name or missing attribute can create duplicate or unusable accounts. Role mapping on first login decides what a new user can do the moment they arrive, so default roles should be reviewed before anyone signs in for the first time.

Rollout also needs more care than a single switch. Enforcement is set tenant by tenant, so a multi-tenant deployment should move one tenant at a time, test sign-in with a small group of accounts, and keep a break-glass path for administrators until the directory integration is proven. Teams should also confirm which protocol they are building on. SAML is being deprecated on Shuffle Cloud in favor of OpenID Connect, so a new Cloud-based design should start from OpenID Connect, while on-premises teams should confirm the current support position for their own version with Shuffle before committing.

Two boundaries shape the work. The protocol settings, such as client registration, signing certificates, token lifetimes and group or claim configuration, come from the identity provider, whether that is Keycloak, Microsoft Entra ID or another product. Shuffle's side depends on its version and extension configuration, so the exact fields, screens and behavior should be checked against the release you run, not against older guides. Ask for both sides to be documented in the implementation, including the test accounts and the rollback steps for each tenant.

Which Shuffle and identity provider pieces must line up

A Shuffle SSO login passes through the browser, the Shuffle frontend and Go backend, the OpenSearch store and the identity provider, and each piece holds part of the configuration. When sign-in fails, the cause is usually a mismatch between two of these pieces rather than a fault in any single one.

Browser, frontend and backend login flow

The browser loads the Shuffle frontend, which sends the user to the identity provider and returns to the Go backend API on port 5001 to complete the login. Check that the public URL the browser uses matches the redirect and callback addresses registered with the identity provider. A mismatch in scheme, host or port is one of the most common causes of a failed redirect.

OpenSearch user and tenant records

Shuffle stores user and tenant records in OpenSearch, so first-login provisioning and role assignment write to that store. Confirm the cluster is healthy and reachable from the backend before testing SSO, because a failed write surfaces as a login error that looks like an identity problem. Ask your team how backups of this index are scheduled and tested.

Identity provider tokens and SAML assertions

Keycloak or Microsoft Entra ID issues the OpenID Connect tokens or SAML assertions that Shuffle trusts. Each side must agree on the client identifier or entity ID, the signing certificate or keys, and the claims or attributes that carry the user's email and group membership. Record which identity provider application each Shuffle environment uses so that changes are traceable.

Per-tenant SSO settings

SSO is configured per tenant, and enforcement can be turned on for one tenant without affecting others. Each tenant needs its own provider settings and enforcement choice, so a test tenant and a production tenant can differ. Keep a written record of which settings apply to each tenant and who approves changes to them.

Components outside the login path

Orborus and the app containers execute workflows and do not take part in sign-in, so restarting or scaling them does not change login behavior. When a user cannot sign in, start troubleshooting between the browser, the backend and the identity provider. Stop checking workers for login problems unless the failure is in a workflow run.

Exact setting names for your version

The names of SSO settings, environment variables and provider fields depend on the Shuffle version you run, so do not copy them from older guides. Read the SSO section of the Shuffle extensions documentation for the version in your environment and match each name exactly. Confirm any change in a non-production tenant first.

OpenID Connect or SAML: which protocol to choose

This table compares OpenID Connect and SAML for Shuffle single sign-on across deployment situations and day-to-day operating effort. Read each row against your own identity landscape, then use the last row to decide whether Entra ID should connect directly or through Keycloak. Confirm feature availability for your chosen Shuffle release before you commit to a design.

Decision factor	OpenID Connect	SAML
New deployments	Preferred starting point for new on-premises Shuffle deployments, since it is the protocol the Shuffle docs direct new SSO work toward.	Usable where it is already configured, but plan it as the legacy path for new work.
Shuffle Cloud	Use this protocol for Shuffle Cloud, where SAML is being deprecated in favor of OpenID Connect.	Expect SAML to be retired on Shuffle Cloud, so plan a move before the deprecation date you confirm with Shuffle.
Existing SAML-only directories	Requires an identity provider or broker that can issue OpenID Connect tokens to Shuffle.	Fits when your directory or application catalog only supports SAML and no broker is in place.
Keycloak brokering	Keycloak can accept SAML from upstream providers and present OpenID Connect to Shuffle, which keeps the Shuffle side on one protocol.	Keycloak can also use SAML on the Shuffle side, but this adds a second protocol to maintain.
Certificates and metadata	Client secrets and issuer endpoints are the main items to rotate and verify, with no XML metadata exchange.	Signing certificates and SAML metadata must be exchanged, tracked and renewed before expiry on both sides.
Claim configuration	Map the subject, email and group claims in the token, and confirm which claims Shuffle reads for user provisioning on first login.	Map the NameID and attribute statements, and confirm the attribute names match what Shuffle expects.
Token lifetimes	Access and ID token lifetimes and refresh behavior are set at the identity provider, so review them against your session policy.	Assertion validity windows and session lifetimes are set in the identity provider, so align them with Shuffle session expectations.
Entra ID directly or through Keycloak	Connecting Entra ID directly keeps one fewer component to run, but group and role mapping lives in Entra ID and changes need Entra ID administrator access. Keycloak adds a component to patch and back up, and gives you a single place to map claims and per-tenant rules.	Not applicable

How to configure Shuffle SSO step by step

This sequence takes a self-hosted Shuffle instance from a confirmed release to a tested single sign-on login for its first tenant. Each step ends with a check you can run yourself, so a fault surfaces at the step where it was introduced, before other users depend on it.

Confirm release support for your protocol
Check the running Shuffle version against the release notes before choosing a protocol. SAML single sign-on was added in version 0.9.16 and OpenID Connect in 1.0.0, so an older instance needs an upgrade before either can be configured. The platform owner records the exact running version and the protocol your identity provider supports. The step is done when the release notes for that version confirm the chosen protocol is present, and that record is saved with the change request.
Register Shuffle with the identity provider
In the identity provider, create a client for OpenID Connect or a service provider for SAML that represents your Shuffle instance. Enter the redirect URL or assertion consumer URL that your Shuffle deployment uses, and serve it over TLS with a certificate that users' browsers trust. The identity provider administrator usually makes this change, with the Shuffle owner supplying the public hostname. The step is done when the application is listed in the identity provider and a test sign-in reaches the provider's login page without a redirect error. Confirm the exact URL format in the Shuffle extensions documentation for your version.
Map claims or attributes Shuffle needs
Shuffle needs a stable user identifier, an email address, a display name and group membership to decide who may sign in. Configure the identity provider to release these as claims for OpenID Connect or as attributes for SAML, using the names your Shuffle version expects. Group membership is the control that keeps accounts outside the intended directory group out, so settle the allowed group before testing. The step is done when a sample user's token or assertion, inspected in the provider's log or debug view, shows all four values populated.
Enter provider settings in Shuffle
In Shuffle's authentication settings, enter the issuer or metadata location and client identifier for OpenID Connect, or the identity provider metadata and certificate for SAML, using the values from the identity provider. Store the client secret in your secrets manager, and back up the Shuffle encryption secret separately, since it protects saved app credentials. Keep a local administrator account available until login is confirmed. The step is done when the settings save without a validation error and the provider appears as a sign-in option on the login page.
Enable SSO for the first tenant only
Turn on SSO enforcement for one tenant, the one that holds your pilot users, and leave every other tenant on its current sign-in method. Per-tenant enforcement makes SSO mandatory for that tenant only, so set it deliberately and record the tenant name and the time of the change in your change log. The step is done when the pilot tenant shows the enforcement state you set and the other tenants are unchanged.
Test an allowed login in a clean session
Open a private browser window with no existing Shuffle or identity provider session, then sign in as a user in the allowed group. The browser should redirect to the identity provider, return to Shuffle, and open the workspace. Check the user record in OpenSearch and confirm the identifier and email match the claims you mapped. The step is done when the login succeeds and the stored record matches the identity provider's values for that user.
Confirm refusal for accounts outside the group
Sign in with an account that belongs to the directory but outside the allowed group, and confirm the attempt is refused. Check whether a user record was created in OpenSearch for that account, and if one was, confirm it grants no workspace access. Keep the refused attempt, the identity provider log entry and the Shuffle log entry in your test evidence. The step is done when the refusal is recorded at the identity provider or in Shuffle, and the outcome matches the expected behavior for your version.

What drives SSO effort and how to keep it down

This table lists the factors that change how much work a Shuffle SSO project takes, how each one pushes effort up, and the reduction that keeps it contained. Read each row as a decision to make before scoping, then use the last column to shape the quote. The main takeaway is that a single tenant, one identity provider and group-based roles keep the project small, while each extra tenant, environment or evidence request adds separate work.

Driver	Why it changes effort	How to keep it down
Identity providers and tenants	Each OpenID Connect or SAML provider needs its own registration, claim checks and per-tenant enforcement settings in Shuffle	Start with one tenant and one provider, then add the others as separate, scoped changes
Keycloak between Shuffle and Entra ID	A broker adds a second configuration layer, with realm, client and identity brokering settings to verify end to end	Decide early whether Shuffle connects directly to Entra ID or through Keycloak, and document the choice before building
Group-to-role mapping	Each directory group that maps to a Shuffle role must be named, tested and kept in sync with the directory	Keep the mapping to a small set of roles and assign access through groups, not per-user grants
Environments (test, production, hybrid)	Each environment usually needs its own client registration, redirect URIs and secrets, and each must be tested	Write one claim map and configuration template, then reuse it across environments with only the endpoints and secrets changed
Identity administrator availability	Registration changes, group membership and claim questions need a directory administrator who can act during the build	Confirm the named administrator and their time before scoping, and agree who approves each registration change
Compliance evidence requests	Access reviews, role exports and login records require a repeatable way to produce them, which adds reporting and test work	Ask for the evidence list in writing up front, and build the group-based role export and review step into the initial scope
Quote itemization	Unclear scope lets effort grow during the build without anyone agreeing to it	Ask the quote to itemize each tenant, provider, environment, role mapping, administrator input and evidence item separately

How user provisioning on first login affects access

The first successful sign-in through your identity provider decides what a new person can do in Shuffle, so review that moment before you enable single sign-on for anyone. When a user signs in for the first time, Shuffle trusts the identity the provider asserts, then either creates a Shuffle user or links the login to an existing one. The role and tenant assignment follow from the claims or groups the provider sends in the OpenID Connect token or the SAML assertion. Those claims are the input to every access decision that follows, so the attributes your provider emits are part of your access design and need a named owner.

The most immediate risk is a default role. If a person with no matching group or claim can sign in and receive a broad role, every account in your directory that can authenticate becomes a potential Shuffle user. Confirm in the extensions documentation for your version what role applies when no mapping matches, whether accounts are created automatically on first login, whether group mapping is available, and which token fields Shuffle reads. Record those answers in your access review, because a change to provider claims or group configuration can alter what the next new login receives.

The second risk is stale accounts. First-login provisioning creates or links the user, but it does not remove that user when someone leaves the directory. Disabling the identity in your provider stops new sign-ins, yet the Shuffle user record, the workflows it owns and any credentials it created may remain until someone acts. Decide early whether deprovisioning is manual, with a written offboarding step that disables the Shuffle user and rotates credentials it owned, or whether your identity provider drives that change through its own lifecycle tooling. Ask the vendor or your implementation partner to confirm which of these your version supports.

Test the behavior before any administrator relies on SSO. Use a non-privileged test account in the provider, sign in once, and record which Shuffle user, role and tenant were created or linked. Change that account's group membership, sign in again, and confirm the role changes as the design says. Then disable the account and check what remains in Shuffle. Only after these results match the design should an administrator sign in through SSO, and keep a local administrator path available until the mapping has been verified in production conditions.

How SSO differs on-premises, in Shuffle Cloud and with a hybrid runtime

With Shuffle running on your own servers, your team owns the whole login path. You set the backend URL that the identity provider redirects users back to, manage the certificates that browsers and the identity provider trust, and configure the connection to your identity provider. Because these settings are part of the deployment, a change to the public hostname or a certificate affects every login, so treat them as controlled configuration.

Backend URL: the redirect addresses registered with the identity provider must match the external address users actually reach. Confirm the exact format for your version in the extensions documentation.
Certificates: your team issues and renews the TLS certificates for the frontend and backend, and handles any SAML signing material exchanged with the provider.
Identity provider connection: you register Shuffle as a client or service provider and map the attributes or claims Shuffle needs to identify users.
Upgrades: keep redirect addresses and provider registrations stable across upgrades, and test a login after each upgrade in a non-production instance.

Before go-live, check that the redirect addresses, certificate chain and provider registration all point to the same final hostname.

Access control and secrets to protect around SSO

Single sign-on moves the login decision to your identity provider, but Shuffle still holds sessions, tenant boundaries, a local administrator path and signing trust that you must protect. The cards below cover the controls and secrets that connect the SSO configuration to day-to-day access, and the one encryption secret that SSO does not replace.

TLS on every login endpoint

Every route the browser and identity provider use during sign-in should be served over TLS, including the Shuffle frontend, the backend callback path and the identity provider's redirect and metadata URLs. Mixed content or a plain HTTP callback can expose authorization codes and session cookies. Check the certificate chain from a machine outside your network, confirm the redirect URI registered at the provider matches the deployed hostname exactly, and confirm the backend trusts the provider's certificate authority.

Identity provider group restrictions per tenant

SSO only controls who can authenticate, so each Shuffle tenant needs a rule that limits which identity provider groups or roles can reach it. Map groups deliberately rather than granting access to every account in the directory. Review the group claim your provider sends, confirm which users inherit administrator rights on first login, and test with a user from each group that should be excluded to confirm the denial happens before a session is created.

Session lifetime and sign-out behavior

Set session lifetimes that match your policy for privileged security tooling, and test what happens at the identity provider when a user signs out of Shuffle. A local session that ends while the provider session remains active can let the next user sign in silently, and a removed or disabled user may keep access until their session expires. Confirm the lifetime values with your identity team, and verify both single-app and global sign-out in a test tenant.

Break-glass local administrator account

Keep one local administrator account that works without the identity provider, so a directory outage or misconfigured SSO does not lock out every operator. Store its credentials in a sealed record with a named custodian, and write a documented procedure that states who may open the record, what must be logged, and how the password is rotated afterward. Test the procedure on a schedule in a non-production tenant, and confirm that SSO enforcement settings do not disable this account unintentionally.

Client secret and SAML certificate rotation

The OpenID Connect client secret and the SAML signing certificate both expire or become exposed over time, and each rotation can break sign-in if the Shuffle configuration is not updated at the same moment. Put both on a written rotation schedule, record the expiry dates, and stage the new value in the provider before switching Shuffle. Confirm with your provider whether the old and new values can overlap during the change window, and keep the previous value available until login is verified.

Token signature and audience validation

Shuffle should accept identity tokens only when the signature verifies against the provider's published keys and the audience value names this Shuffle client. Without these checks, a token issued to another application in the same provider could be replayed against your instance. For SAML, confirm that assertions are signed and that the expected audience and recipient values are enforced. Ask your provider which claims are included and test a token issued to a different client to confirm it is refused.

SHUFFLE_ENCRYPTION_MODIFIER is not replaced by SSO

SSO controls who signs in, but it does not protect the saved app credentials and API keys in OpenSearch. Those are encrypted with AES-256 using SHUFFLE_ENCRYPTION_MODIFIER, and losing or changing that value breaks every saved app authentication. An identity change that prompts re-authentication or a reinstall must not be done with a new modifier value. Store the value in your secrets manager, back it up with the database, and confirm the value is unchanged after any SSO reconfiguration.

How to test that SSO works and fails safely

Test SSO by proving three things before any user depends on it: the right people get in with the right role, the wrong people and altered credentials do not, and local access survives an identity provider outage. Run these checks in a non-production Shuffle instance that uses the same OpenID Connect or SAML configuration as production, then repeat the critical ones after every change to the identity provider, the redirect URLs or the Shuffle version. Write each test as a numbered case with its preconditions, the account used, the expected result and the observed result, so the same plan can be rerun during an upgrade.

Successful and denied logins. Sign in through the identity provider once for each Shuffle role you intend to map, such as an administrator, a workflow editor and a read-only analyst, and confirm that each account lands with the expected permissions. Then sign in with an account that exists in the identity provider but is outside the allowed group. The denial should happen at the identity provider or at Shuffle, and the test should confirm that no user record or session is created for the denied account. Also test a first login for a new user in an allowed group and confirm that the account receives only the default role you configured, not an administrative one.

Unreachable provider, altered tokens and tenant enforcement. Stop or block access to the identity provider from the Shuffle backend and from a user's browser, then confirm whether local login still works and which accounts can use it. Record that answer in writing, because it determines who holds break-glass access. Next, present an expired token or SAML assertion, and a copy with a modified claim or signature, and confirm both are rejected. For each tenant that requires SSO, attempt a local password login and confirm it is refused. Confirm the exact enforcement behavior in the current Shuffle extensions documentation for your edition, since the SSO and per-tenant options are described there.

Logging and rollback. Each login attempt, success or failure, should leave a record that identifies the identity provider event, the account and the outcome. Check that the audit or login logs contain these entries and that they are retained and forwarded according to your policy. Then run a rollback test: disable the SSO configuration, confirm that the designated local administrators can sign in, and verify that workflows, apps, saved app credentials and user records are unchanged. Saved credentials depend on the encryption secret being unchanged, so confirm that secret is still in place before and after the rollback.

Evidence for access reviews. Keep the test plan, the account list used, the expected and observed results, screenshots or exported log excerpts, and the names of the people who ran and approved each test. Store them in the same evidence location as your access review records. Define in advance who signs off, what counts as a failed test, and what must be fixed and retested before go-live. This record shows an auditor that the control was tested, which is different from having an auditor certify it. Ask your compliance lead which control evidence formats they require before the first run.

Questions teams ask before setting up Shuffle SSO

Can our own identity team set up Shuffle SSO without a partner?

Yes, many identity teams can, provided they have an administrator for the identity provider and someone who can run and restart the Shuffle server. The configuration itself is small: you register Shuffle as a client in your provider, set the redirect and issuer values, and map the groups or claims that decide who gets which role. What usually takes longer is the surrounding work: agreeing on role mapping, testing with real accounts, and planning what happens to existing local users. A partner is useful when those decisions are unclear, when several environments need the same pattern, or when the team has no spare capacity to test. Confirm the exact settings for your Shuffle version in the extensions documentation before you start.

What drives the effort of a Shuffle SSO project?

The main drivers are the identity provider you use, the number of Shuffle environments, and how much role mapping you need. A single Keycloak or Microsoft Entra ID tenant with two or three roles is a small job. Effort grows when you have several tenants that need different enforcement rules, when group membership lives in more than one directory, or when you must document the configuration for an audit. Testing takes time too, because each role should be verified with a real test account. When you ask for a quote, request a written breakdown by task: discovery, configuration, role mapping, test cases, handover, and any retest after upgrades. Ask which items are one-time and which are recurring, and what the provider needs from your team in each step.

What access and inputs does Shuffle SSO need from our team?

You need four things before the work starts. First, identity administrator access to the provider, so the Shuffle client can be created and claims or groups can be configured. Second, a test directory group with a few non-privileged accounts that represent each intended role. Third, DNS and TLS for the Shuffle URL, because OpenID Connect and SAML both depend on a stable, trusted address for redirects and callbacks. Fourth, a named owner for role mapping who can decide which directory group maps to which Shuffle role and approve changes. Without that owner, role decisions stall. Also confirm who can access the Shuffle server to change environment settings and restart the service.

Does SAML still work on Shuffle Cloud?

Shuffle added SAML single sign-on in version 0.9.16 and OpenID Connect in 1.0.0, and both are available on-premises and in the cloud. However, the Shuffle extensions documentation states that SAML is being deprecated on Shuffle Cloud in favor of OpenID Connect. That means a new Shuffle Cloud integration should start with OpenID Connect unless you have a specific reason to use SAML. If you already run SAML on Shuffle Cloud, plan a migration window and confirm the current status with Shuffle before you rely on it. Check the extensions documentation for the exact behavior in the version you run, because the status of deprecated features can change.

Is Keycloak required to use Shuffle SSO?

No. Keycloak is a common choice because it is open source and speaks OpenID Connect and SAML, but Shuffle SSO is configured against standard protocols, so other providers such as Microsoft Entra ID can be used. The decision should depend on where your users and groups already live. If your workforce identities are in Entra ID, connecting Shuffle directly avoids running an extra identity service. If you need a broker that federates several sources, Keycloak can serve that role. Whichever provider you choose, confirm the claim names, group format and redirect settings against the extensions documentation for your Shuffle version, since these details decide whether role mapping works.

What happens to existing local Shuffle users when SSO is enforced?

Local accounts created before SSO can remain in the database, and enforcement determines whether they can still sign in with a password. Before you turn enforcement on for a tenant, list every local user, decide which ones are service or break-glass accounts, and confirm that each person who needs access has an SSO identity that maps to the right role. Shuffle provisions users on first login, so an SSO user who has never signed in will not exist yet, and role assignments should be checked after their first login. Keep at least one tested administrator path for recovery, and document how it is used. Confirm the enforcement behavior for your version in the extensions documentation before a cutover.

What should we test before we enforce SSO for a tenant?

Test the full sign-in path with one account per role, including a user who should be denied access. Verify that first-login provisioning creates the account with the expected role, that a user removed from the directory group loses the matching permission as your design intends, and that local login behaves as you decided for each existing account. Also test the redirect after an upgrade and after any change to the Shuffle URL or certificate, since these are common breakage points. Keep the test results and the configuration as evidence. Your auditors or internal reviewers can then see what was tested, but the evidence still needs to be reviewed by them, as DeployOpen prepares records and does not issue audit reports.

How DeployOpen scopes, builds and hands over Shuffle SSO

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, and Shuffle SSO follows the same path. Each engagement starts with a written, fixed scope that names the identity provider, the protocol, the tenants and the users to be provisioned, so the work and its deliverables are agreed before anything is built.

How we scope

Confirm whether the identity provider will use OpenID Connect, SAML, or both, and which Shuffle deployment type hosts the login flow.
Record each tenant that must enforce SSO, its identity provider configuration and the local accounts that must stay available for recovery.
Agree in writing how users are provisioned on first login, including which attributes map to Shuffle roles and workflow access.

How we build

Configure the OpenID Connect or SAML connection in Shuffle, using the extensions documentation for the version your deployment runs.
Test sign-in, sign-out, first-login provisioning and per-tenant enforcement with test accounts before any production user is affected.
Check the Shuffle encryption secret, redirect URLs and certificate settings against your environment so saved app credentials stay usable after the change.

How we hand over

Deliver a runbook covering the identity provider settings, claim mappings, certificate renewal dates and the steps to add a tenant.
Document the emergency local login procedure and who may use it, so administrators can still reach Shuffle if the provider is unavailable.
Walk your administrators through the configuration and test evidence, then close the engagement against the agreed deliverables.

How we support

Ongoing support, upgrades and continuous testing are available as retainers, so SSO changes can be tested again after each Shuffle release.
Re-verify SSO behavior when the identity provider rotates certificates, changes claims or when Shuffle moves a protocol to a new configuration path.
Ask any support provider to confirm in writing which Shuffle versions, identity providers and tenants fall within the agreed support scope.

Shuffle SSO with OpenID Connect and SAML