Require federated_id Claim in SAML Connections
Date: 2025-XX-XX
Status: accepted
Context
We require a dedicated federated_id claim because SAML's built-in NameID is not reliably stable across IdPs or tenants. Many IdPs (Google Workspace, Azure AD, Okta, etc.) default to sending an email address as NameID, and those emails can and do change on rename or domain migration. That means using NameID as our primary key would cause silent identity drift: the same human would appear as a "new" user after such changes, breaking account linking, auditing, and permissions.
By contrast, federated_id is defined in the integration contract as a stable, non-reassigned identifier under the customer's control (e.g., employee number or immutable directory ID).
Decision
All SAML connections must provide a federated_id claim as the application-level subject identifier.
This gives us:
- A consistent, long-lived join key across SAML assertions and systems
- Predictable behavior during renames and email/domain changes
- Lower risk of security issues caused by identifier reuse or collisions
In short: NameID is a transport-level identifier whose semantics vary by IdP, while federated_id is our application-level subject identifier with clear stability guarantees, so we can safely build authorization, auditing, and data models on top of it.
Consequences
Positive Consequences
- Stable user identity across email changes and domain migrations
- Reliable join key for account linking, auditing, and permissions
- Reduced security risk from identifier reuse
Negative Consequences
- Increased support burden: customers must understand and configure the
federated_idclaim correctly - We have already seen a surge in support requests as customers onboard with this requirement