Security · Lesson 07

OpenID Connect & SAML

OAuth 2.0 answers "what may this app do?" — but it says nothing about who is logged in. OpenID Connect adds that identity layer. SAML solves the same problem with XML in enterprise environments. Both power the "sign in with…" buttons you use every day.

The missing piece in OAuth 2.0

Imagine you hand your valet key (from the previous lesson) to a parking attendant, and then you ask: "Did a human hand you this key, or was it passed through a relay?" The valet key says nothing about its owner — only what doors it can open. OAuth 2.0 has the same blind spot: an access token proves what a client may do, but not which human granted it, or even whether a human was involved at all.

OpenID Connect (OIDC) fills that gap by adding one new token — the ID token — and a standard way to ask "who is this user?" It is OAuth 2.0 underneath, with an identity contract bolted on top. You get both an access token (for API calls) and an ID token (for your app to know who logged in).

The ID token: a JWT about the user

An ID token is a JSON Web Token (JWT) signed by the identity provider. Its payload always includes a standard set of claims:

// ID token payload (decoded — the actual token is Base64URL-encoded)
{
  "iss": "https://accounts.example.com",  // issuer
  "sub": "user_7f3a9c",                   // subject (stable user id)
  "aud": "client_app_xyz",               // audience — must match your client_id
  "exp": 1750000000,                    // expiry (Unix timestamp)
  "iat": 1749996400,                    // issued-at
  "nonce": "k9sRt2pQ",                   // replay-attack protection
  "email": "ada@example.com",            // profile scope granted
  "name":  "Ada Lovelace"
}

Your app verifies the signature, checks the aud matches your own client ID, and confirms the token has not expired — then you know exactly who logged in. The access token is still used for API calls; the ID token is for your app's session. Never send the ID token to an API as a Bearer token — it is for the client, not the resource server.

SSO: one login, many apps

Single Sign-On (SSO) means logging in once to an identity provider and then gaining seamless access to multiple connected services without re-entering credentials. The identity provider authenticates you; each service trusts the IdP's assertion.

SAML: SSO the enterprise way

Security Assertion Markup Language (SAML 2.0) is an older XML-based standard that predates OAuth. It is still dominant in large enterprises because it integrates tightly with Active Directory / LDAP identity stores and legacy applications.

The flow is conceptually similar to OIDC: a Service Provider (the app) redirects the user to an Identity Provider (e.g. Okta, Microsoft AD FS), the IdP authenticates the user and returns a signed XML assertion to the SP, and the SP validates the assertion and creates a session.

Under the hood: how OIDC actually works

OpenID Connect is OAuth 2.0 authorization-code flow with two additions: the openid scope in the initial redirect, and an id_token returned alongside the access token. Everything else — PKCE, state, the token exchange — is identical to OAuth. The identity layer is thin; the transport layer is already OAuth.

# ① /authorize request — identical to OAuth but adds "openid" scope
GET https://accounts.example.com/authorize
  ?response_type=code
  &client_id=my_app
  &redirect_uri=https://app.example.com/callback
  &scope=openid profile email   // "openid" triggers OIDC; "profile"/"email" request claims
  &state=r8tQmZ4k
  &nonce=k9sRt2pQ               // OIDC-specific: client stores this; IdP must echo it in id_token
  &code_challenge=E9Melhoa2Ow...
  &code_challenge_method=S256

# ② POST /token exchange (same as OAuth) returns TWO tokens:
HTTP/1.1 200 OK
{
  "access_token":  "eyJhbGci...",   // for API calls
  "id_token":      "eyJhbGci...",   // for your app to know who logged in
  "token_type":    "Bearer",
  "expires_in":    3600
}

Decoded ID token and client-side validation

An ID token is a signed JWT. Its payload contains a fixed set of claims the client must validate in strict order before trusting the identity. Skipping any step leaves the app vulnerable to token substitution or replay.

# Decoded id_token payload (the actual token is three Base64URL segments joined by dots)
{
  "iss":   "https://accounts.example.com",  // issuer
  "sub":   "user_7f3a9c",                   // stable, opaque user ID — use as primary key
  "aud":   "my_app",                        // MUST match your client_id exactly
  "exp":   1750003600,                      // reject if exp < now()
  "iat":   1750000000,                      // issued-at; reject if too far in the past
  "nonce": "k9sRt2pQ",                     // MUST match the nonce the client sent in ①
  "email": "ada@example.com",
  "name":  "Ada Lovelace",
  "email_verified": true
}

# Client validation algorithm — in this exact order
1. Fetch the IdP's JWKS from /.well-known/openid-configuration → jwks_uri
2. Match the token's "kid" header claim against a key in the JWKS
3. Verify the signature using that public key and the pinned algorithm ("RS256" typical)
4. Assert iss == expected issuer URL (prevents cross-IdP token substitution)
5. Assert aud contains your client_id (prevents tokens meant for other apps)
6. Assert exp > now()  (token not expired)
7. Assert nonce == nonce you stored in session before the redirect  (replay protection)
8. Optionally assert iat is recent (e.g. within 5 minutes)
# Only after all 8 checks pass: trust the sub and create your app session

SAML assertion exchange at a protocol level

SAML uses XML POSTed through the browser as the transport mechanism. The browser never touches the assertion content — it just carries an opaque base64-encoded blob from the IdP to the Service Provider (SP). The core exchange has three steps:

The SAMLResponse is a base64-encoded, XML-signed document. It contains the user's NameID (usually an email or opaque ID), attribute statements (department, role, groups), and validity timestamps (NotBefore, NotOnOrAfter). The SP must validate the XML signature against the IdP's public certificate, check the NotOnOrAfter timestamp, and verify the Recipient matches its own ACS URL.

How to debug & inspect it

OIDC and SAML failures almost always fall into three categories: token validation errors, clock-skew issues, and configuration mismatches. Here is how to find each one in practice.

OIDC / SAML debug checklist:

1. Decode the id_token or SAMLResponse payload (shell commands above) — read the raw claims before touching library-level errors.
2. Check exp / NotOnOrAfter against date -d @<timestamp>. If the token is already expired, the clock difference is the root cause, not the token itself.
3. For OIDC: confirm iss exactly matches your pinned issuer URL and aud exactly matches your client_id.
4. For OIDC: confirm the nonce in the token equals what you stored in the session before the redirect.
5. For signature errors: fetch the IdP's JWKS, find the key whose kid matches the token header, and verify it is current (not expired or replaced).
6. For SAML: decode the SAMLResponse with base64 -d | xmllint and check Recipient, NotOnOrAfter, and the Issuer element.

Sources & further reading

• openid.net — OpenID Connect Core 1.0 specification
• RFC 8414 — OAuth 2.0 Authorization Server Metadata
• OASIS — SAML 2.0 Core Specification
• Okta — Understanding SAML