Federation — OIDC and SAML

Federation is the pattern where a user signs in to your IntelliAuth tenant using their existing identity at a different provider — Google, GitHub, Microsoft, Apple, Okta, Entra, OneLogin, etc. IntelliAuth handles the protocol dance; your app sees the result as a normal IntelliAuth session.

Two flavours:

Social federation — typically OIDC against consumer providers (Google, GitHub, Microsoft, Apple, Facebook, Twitter/X). One-click sign-in for end-users who already have those accounts.
Enterprise federation — typically SAML 2.0 (or sometimes OIDC) against corporate identity providers (Okta, Entra ID, OneLogin, Ping). One-click sign-in for employees of your B2B customers.

The two share the same shape conceptually — IntelliAuth is the SP (Service Provider) and the external provider is the IdP (Identity Provider). The differences are protocol details (OIDC vs SAML, JWT vs XML) that the platform abstracts away.

How it looks to your code

From your code's perspective, federation is invisible. The user signs in; your SDK calls return a user object; the user's identity is whatever the federation produced. The connection claim on the token tells you which route they used:

{
  "sub": "usr_01HZX...",
  "email": "alice@cymmetri.com",
  "connection": "google-oauth2",  // ← they signed in via Google
  "amr": ["pwd"],  // ← Google authenticated them with a password
  ...
}

Use the connection claim if you want connection-specific behaviour ("only allow Google sign-ins from @cymmetri.com domain users", say). Most apps don't need it; the identity is the identity regardless of route.

Identity linking

A common question: what if a user signs in with Google as alice@cymmetri.com, and later signs in with Microsoft using the same email? Two answers depending on tenant policy:

Link by email (default for most tenants) — they become the same identity. The IntelliAuth user has both Google and Microsoft federation links; signing in either way returns the same sub.
Separate identities — the two sign-ins create two distinct identities. Same email, different users in IntelliAuth.

The default is link-by-email because that matches user expectations ("I'm the same Alice whether I clicked Google or Microsoft"). If your tenant deals with high-security domains (banking, gov) where automatic linking is too permissive, the admin can disable it.

What gets imported

When a user signs in via federation, the platform reads the standard OIDC / SAML attributes the IdP sends:

email and email_verified
name / given_name / family_name
picture (when provided)
locale
groups (SAML only typically; useful for role mapping)

These flow into the IntelliAuth identity. If your tenant has attribute mapping configured, additional IdP-specific attributes (employee_id, cost_center, etc.) can flow into custom attributes on the identity.

When federation is the right move

For most B2C SaaS, social federation is a UX win — one fewer password for users to remember. Enable Google + GitHub + Apple at minimum; the cost is near-zero (configuration in the tenant admin console), the benefit is materially higher sign-up conversion.

For products selling into enterprise organisations, SAML federation is often a requirement — the buying organisation's IT department mandates SSO before they'll deploy your product internally. Without SAML, you're locked out of enterprise procurement.

The tenant admin enables federation in the admin console; your code doesn't change. The login surface IntelliAuth renders adds the federation buttons automatically based on what's enabled.

When it's not

Three cases where federation might not help:

Your users are consumer-tier, mass-market, mostly mobile. SMS-based sign-in (passwordless) often outperforms social federation here — fewer mental steps.
Your tenant has strict identity-binding requirements (regulated industries) where federation linking introduces too much trust in the upstream IdP.
The buying organisation's IT department is SCIM-mature and wants full provisioning, not just SSO. SAML SSO is necessary but not sufficient — you'd add SCIM on top.

Most apps benefit from federation. Plan to support it from launch.

Connection management

Federation connections are configured per-tenant in the admin console. Each connection has:

A type (Google, Microsoft, custom-oidc, custom-saml).
Credentials (client id + secret for OIDC, certificate + metadata for SAML).
Attribute mapping rules.
An active / inactive toggle.

End-users see only active connections. Tenant admins flip these per-connection; you don't need to change code when a connection comes or goes.