Level 1: Single sign-on

How SAML and OIDC let one authentication event create sessions in multiple services — and what can go wrong when Federation ID is misconfigured

What SSO actually does

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.

SAML SSO: SP-initiated 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.

Step by step

  1. User visits the SP. Jordan Reyes navigates to https://harborpoint.my.salesforce.com and clicks "Log in with Entra ID."
  2. SP generates an AuthnRequest. The SP constructs a SAML AuthnRequest — an XML document identifying the SP and requesting authentication — and redirects Jordan's browser to the IdP's SSO endpoint with the request encoded in the URL.[2]§3.4
  3. IdP authenticates the user. The IdP (Keycloak, standing in for Entra ID) presents a login form. Jordan enters their credentials. The IdP verifies them.
  4. IdP sends a signed SAMLResponse. The IdP constructs a SAMLResponse containing a signed Assertion and POSTs it to the SP's Assertion Consumer Service (ACS) URL through Jordan's browser.[2]§3.5 The assertion is signed with the IdP's private key.
  5. SP validates the assertion. The SP performs several checks before accepting the assertion (see below).
  6. SP creates a session. If validation passes, the SP looks up the local user by Federation ID, creates a session cookie, and Jordan is logged in.

What the SP must validate

Receiving a SAMLResponse is not enough — the SP must verify several properties before trusting it:

The NameID and Federation ID

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: authorization code flow with identity

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.

Step by step

  1. Relying party (RP) redirects the user. The RP sends the browser to the authorization endpoint with response_type=code, client_id, redirect_uri, scope=openid, and a nonce.[3]§3.1.2.1
  2. IdP authenticates the user. The authorization server (Keycloak) authenticates Jordan and obtains consent.
  3. IdP returns an authorization code. The browser is redirected back to the RP's redirect URI with a short-lived code.
  4. RP exchanges the code for tokens. The RP's server POSTs to the token endpoint with the code, client_id, and client_secret. The IdP returns an ID token, an access token, and optionally a refresh token.[3]§3.1.3.3
  5. RP validates the ID token. The RP performs all required validation checks (see below).
  6. RP creates a session. The RP reads the sub claim (or a mapped claim) to identify the user, creates a local session, and Jordan is logged in.

What the RP must validate

The RP must validate the ID token before trusting any claim in it:[3]§3.1.3.7

The nonce and replay prevention

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.

SAML vs. OIDC SSO: comparison

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

Federation ID: the matching field that makes or breaks SSO

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.

In SAML

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.

In OIDC

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.

What happens when there is no match

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.

What Keycloak is doing in this course

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.

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.

Lab: inspect a real OIDC ID token and a SAML NameID

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.

Self-check: test your understanding

Answer these questions to confirm you've grasped single sign-on:

Question 1 of 5: Federation ID

Jordan's manager configures SAML SSO between Microsoft Entra ID and Salesforce. The IdP certificate is uploaded, the ACS URL is set, and the AuthnRequest is working. Jordan tries to log in via SSO and gets an error. The SAML assertion is signed correctly and the audience restriction matches Salesforce. What is the most likely cause?

Question 1 choices

Question 2 of 5: SAML assertion validation

Jordan's browser delivers a SAML assertion to Salesforce's ACS endpoint. Salesforce is the service provider. Which party performs signature validation, and what does it check?

Question 2 choices

Question 3 of 5: OIDC nonce

An OIDC relying party generates a nonce and includes it in the authorization request. The ID token returned by the IdP contains the same nonce value. What attack does this prevent, and how?

Question 3 choices

Question 4 of 5: What happens to the ID token after login

A relying party completes an OIDC login and receives an ID token. The RP has validated the signature, confirmed the audience, checked the expiry, and read the sub claim to create a local session. What should the RP do with the ID token now?

Question 4 choices

Question 5 of 5: SAML vs. OIDC transport

Which of the following correctly describes how the SSO credential reaches the service provider or relying party in each protocol?

Question 5 choices

What's next

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.

← Back to course home

Sources

  1. SAML 2.0 Core Specification, OASIS
  2. SAML 2.0 Bindings Specification, OASIS
  3. OpenID Connect Core 1.0, OpenID Foundation
  4. SAML 2.0 Technical Overview, OASIS
  5. JSON Web Token (JWT), IETF
  6. RFC 7517: JSON Web Key (JWK), IETF
  7. Configure SAML SSO with Microsoft AD FS, Salesforce Help
  8. Set a Federation ID for a User, Salesforce Help
  9. Keycloak OIDC Configuration, Keycloak Documentation

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.