Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

SSO / SAML

RuleFlow’s identity plane is Keycloak: OIDC/OAuth2 for direct users, and SAML 2.0 for enterprise single sign-on. Every RuleFlow API token — however the user authenticated — carries the same claim shape (see Authentication), so SSO changes how a user proves who they are, not what the rest of the platform sees.

How a SAML tenant is onboarded

A tenant’s SAML identity provider is brokered into the realm as a dedicated identity-provider configuration, onboarded per tenant. Two properties are enforced at onboarding, not left to the IdP’s default posture:

  • The tenant claim is pinned, not imported. A hardcoded-attribute mapper sets tenant to the value the IdP was onboarded for; the SAML assertion’s own tenant attribute (if it sends one) is ignored. This closes the class of bug where a federated IdP could assert membership in a tenant other than the one it was actually onboarded for — the tenant boundary depends on this being true (see Isolation model).
  • Signed assertions are required. Onboarding an IdP with no signing certificate is refused; assertion signature validation is on, which blocks XML Signature Wrapping attacks against the SAML response.

Email-based account linking/trust is disabled for brokered identities, which closes an account-takeover path where an attacker-controlled IdP could assert an existing user’s email to hijack their account.

What SSO does and does not change

  • Does change: login flow, session issuance, and where credentials live (the enterprise’s own IdP, not Keycloak-managed passwords).
  • Does not change: role assignment mechanics, tenant scoping, or API behavior. A federated user’s token is verified the same way, carries the same claim shape, and is subject to the same 403-on-missing-tenant rule as a directly-provisioned user.

Provisioning

Users — direct or federated — are provisioned on the identity side, not via self-service signup: the realm disables open registration, so there is no flow by which a user picks their own tenant. Onboarding a new tenant (including its SAML brokering, if applicable) is an administrative, identity-side operation that happens before that tenant’s users can obtain a token — the control plane trusts the claim once it arrives, but does not issue it.