How SAML and OIDC let one authentication event create sessions in multiple services — and what can go wrong when Federation ID is misconfigured
Single sign-on is not magic. It is a trust relationship: one party (the identity provider, IdP) authenticates the user and issues a signed credential. Another party (the service provider or relying party) trusts that credential and creates a local session without asking the user to authenticate again.
The browser is the messenger. It carries the credential between the IdP and the SP — the two parties never talk directly in the browser-based flows. This is why the credential must be signed: the SP has no way to verify the channel, only the signature.
Two protocols dominate enterprise SSO:
Both achieve the same goal through different means. Level 0 introduced both protocols; this level goes inside each flow.
The most common enterprise pattern is SP-initiated SSO: the user visits the service provider first, the SP redirects them to the IdP, and the IdP sends back a signed assertion.
https://harborpoint.my.salesforce.com and clicks "Log in with Entra ID."Receiving a SAMLResponse is not enough — the SP must verify several properties before trusting it:
<AudienceRestriction> element. The SP must reject any assertion whose audience does not include the SP's own entity ID.[1]§2.5.1.4 This prevents an assertion issued for one SP from being replayed at another.<Conditions> element carries NotBefore and NotOnOrAfter timestamps.[1]§2.5.1 The SP must reject assertions outside this window to limit the replay window.After signature validation, the SP needs to know which local user this assertion represents. It reads the <NameID> element from the assertion's subject:
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
jordan.reyes@harborpoint.example
</saml:NameID>
</saml:Subject>
Salesforce takes this NameID value and looks for a User record whose FederationIdentifier field matches it exactly. If a match is found, that user gets a session. If no match is found, login is rejected — even though the assertion is cryptographically valid and the IdP is trusted.
This is a common misconfiguration: the IdP is set up correctly, the certificate is trusted, but the administrator forgot to populate FederationIdentifier on the Salesforce User records. The result is a "user not found" error that looks like an SSO failure but is actually a data mapping problem.
OIDC SSO uses the same browser-redirect pattern as the OAuth authorization code flow, but the authorization server returns an ID token alongside the access token. The ID token is the SSO credential.
response_type=code, client_id, redirect_uri, scope=openid, and a nonce.[3]§3.1.2.1client_id, and client_secret. The IdP returns an ID token, an access token, and optionally a refresh token.[3]§3.1.3.3sub claim (or a mapped claim) to identify the user, creates a local session, and Jordan is logged in.The RP must validate the ID token before trusting any claim in it:[3]§3.1.3.7
iss): The iss claim must match the IdP's expected issuer URL exactly.aud): The aud claim must include the RP's client_id. An ID token addressed to a different client must be rejected.exp): The current time must be before the exp timestamp.nonce claim. A mismatch means the token was not issued in response to this specific request.The nonce is a random value the RP generates, includes in the authorization request, and then looks for in the returned ID token. Because the IdP must echo the nonce back, an attacker who intercepts a valid ID token cannot replay it at a different RP session — the nonce will not match the one the RP generated for that session.[3]§3.1.2.1
SAML's replay prevention uses assertion ID tracking. OIDC's replay prevention uses the nonce. Both serve the same purpose: ensuring a credential can only be used once and only by the intended recipient.
| Dimension | SAML 2.0 | OIDC |
|---|---|---|
| Credential format | Signed XML Assertion | Signed JWT (ID token) |
| Browser transport | HTTP POST binding — form field SAMLResponse |
Authorization code in URL query param; token exchange is back-channel |
| Trust material | X.509 certificate registered at the SP | JWKS URI in discovery document |
| SP/RP validation | XML signature, audience, validity window, assertion ID | JWT signature, iss, aud, exp, nonce |
| Credential lifetime | Consumed at login; assertion ID tracked to prevent replay | Consumed at login; nonce prevents replay in a different session |
| User identifier | NameID → Salesforce FederationIdentifier |
sub (or mapped claim) → Salesforce FederationIdentifier |
| API access | None — SSO only; a separate OAuth flow is required | Access token is returned alongside the ID token |
| Typical use case | Enterprise web SSO (Salesforce, Workday, legacy SaaS) | Modern apps, mobile, APIs that need both identity and access tokens |
Both SAML and OIDC require a way to map the external identity to a local user record. In Salesforce, this is the FederationIdentifier field on the User object.
The NameID value in the assertion is compared against User.FederationIdentifier. The NameID format (email address, persistent, transient) determines what value the IdP sends. The SP administrator must configure both sides to agree on the format and value.
By default, Salesforce maps the sub claim from the ID token to FederationIdentifier. The sub claim is a stable, IdP-unique identifier for the user — typically an opaque string, not an email address. Salesforce Auth Providers can be configured to map a different claim (such as email) instead.
If the SP processes a valid, signed assertion or ID token but finds no User record with a matching FederationIdentifier, the login is rejected. The user sees an error. The error is not a protocol failure — the credential was valid — it is a configuration problem. This is one of the most common SSO support issues.
Verify in your org: In Salesforce Setup, search for Users, open any user record, and look for the Federation ID field under "Single Sign-On Information." For SSO to work, this field must contain the exact value the IdP will send as the NameID (SAML) or sub claim (OIDC). If the field is blank, that user cannot log in via SSO.
The live Keycloak instance at follow-the-token-keycloak-289e35d64769.herokuapp.com acts as the IdP for all labs in this course. It stands in for Microsoft Entra ID — the protocols are identical, so everything you observe here applies directly to real enterprise deployments.
learning — equivalent to an Entra ID tenant. All users and clients are scoped to this realm.agent365-integration — the registered application. In a real deployment this would be your Salesforce Connected App or External Client App registration in Entra ID.testuser — the subject of all assertions in the labs. In a real deployment this is a licensed user in both the IdP tenant and the Salesforce org, with matching FederationIdentifier.In a real Salesforce deployment, the Keycloak role is played by Microsoft Entra ID. The SAML assertion structure, the OIDC discovery document, the JWKS endpoint, the NameID format — all of these work the same way. The only differences are operational: Entra ID manages users through Azure Active Directory, requires application registration, and handles Conditional Access policies.
Exercise 1: Decode the ID token from the Keycloak lab and verify its signing key.
First, run Flow 1 (Authorization code grant) in the Keycloak lab to get a live ID token. Copy the raw token value from the page (the full dot-separated string before the masking — or decode the masked prefix to get it from the claims panel).
Then fetch Keycloak's discovery document to find the JWKS URI:
curl -s https://follow-the-token-keycloak-289e35d64769.herokuapp.com/realms/learning/.well-known/openid-configuration \
| python3 -c "import sys,json; d=json.load(sys.stdin); print('issuer:', d['issuer']); print('jwks_uri:', d['jwks_uri'])"
Then fetch the JWKS and find the key whose kid matches the kid in your ID token's header:
curl -s https://follow-the-token-keycloak-289e35d64769.herokuapp.com/realms/learning/protocol/openid-connect/certs \
| python3 -c "import sys,json; [print(k['kid'], k['alg']) for k in json.load(sys.stdin)['keys']]"
Decode your ID token's header to find its kid and alg:
python3 -c "import sys,base64,json; h=sys.argv[1].split('.')[0]; print(json.dumps(json.loads(base64.urlsafe_b64decode(h+'==')),indent=2))" "YOUR_ID_TOKEN"
The kid in the token header should match a key in the JWKS. The alg will likely be RS256. This is the key the relying party would use to verify the signature — without fetching it, there is no way to know the token is genuine.
Exercise 2: Understand NameID in a SAML assertion.
SAML assertions carry the user identity in the <NameID> element. Here is a minimal example showing where the Federation ID value lives:
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
jordan.reyes@harborpoint.example <!-- This value must match User.FederationIdentifier in Salesforce -->
</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData
NotOnOrAfter="2026-11-17T01:30:00Z"
Recipient="https://harborpoint.my.salesforce.com" />
</saml:SubjectConfirmation>
</saml:Subject>
The Format attribute tells the SP how to interpret the NameID value. Common formats are email address, persistent (an opaque IdP-assigned identifier), and transient (a session-scoped temporary identifier). Salesforce supports all three, but the format must be agreed upon in the SP and IdP configuration.
The SubjectConfirmationData element shows two more validation targets: NotOnOrAfter (the validity window) and Recipient (the ACS URL — another audience check). Salesforce validates both before accepting the assertion.
Answer these questions to confirm you've grasped single sign-on:
Next: Level 2 (in development). Level 2 covers OAuth 2.0 core flows with Salesforce as the authorization server — authorization code with PKCE, client credentials, refresh, JWT bearer, device, and External Client Apps.
All company names, tokens, and identifiers in this course are fictional. Harbor Point Financial is a teaching example for Salesforce colleagues learning identity and OAuth fundamentals.