Identity Federation: Mastering SAML and OIDC

Introduction: The Modern Identity Landscape

In the early days of the internet, every application you used required its own unique username and password. If you had twenty different tools for work, you had twenty different sets of credentials to manage, reset, and secure. This model was not only frustrating for users but also a nightmare for security teams, as it increased the surface area for credential theft and made offboarding employees a complex, multi-step process. Identity Federation emerged as the solution to this problem, allowing a user to authenticate with a central identity provider and then access multiple, independent service providers without needing to re-enter credentials.

Identity Federation is the mechanism that enables a user to use a single digital identity across different security domains. By establishing a trust relationship between an Identity Provider (IdP)—the entity that holds the user’s credentials—and a Service Provider (SP) or Relying Party (RP)—the application the user wants to access—we can create a single sign-on (SSO) experience. This lesson explores the two most prominent protocols powering this ecosystem: Security Assertion Markup Language (SAML) and OpenID Connect (OIDC). Understanding these protocols is essential for any modern software architect or systems administrator, as they form the backbone of secure, scalable access management.

Understanding Identity Federation Core Concepts

At its simplest, identity federation is about transferring trust. When a user navigates to an application, they do not present their password to that application. Instead, the application redirects the user to their trusted identity provider. Once the identity provider verifies the user, it sends a cryptographically signed token or assertion back to the application, confirming the user's identity. This process removes the need for applications to store sensitive password data, significantly reducing the security risk for the application owner.

There are three primary actors in any federated identity transaction:

1. The User (Subject): The person attempting to access the application.
2. The Identity Provider (IdP): The system that authenticates the user and issues identity tokens (e.g., Okta, Auth0, Microsoft Entra ID, or an internal Keycloak instance).
3. The Service Provider (SP) or Relying Party (RP): The application that needs to know who the user is to grant them access to resources (e.g., a project management tool, a custom internal dashboard, or a SaaS platform).

Callout: The Difference Between Authentication and Authorization It is vital to distinguish between these two concepts. Authentication (AuthN) is the process of verifying who a user is. Federation is primarily an authentication mechanism. Authorization (AuthZ) is the process of determining what that authenticated user is allowed to do. While OIDC and SAML handle authentication, they often carry authorization data (like group memberships or roles) within the tokens they issue, but the primary goal remains confirming identity.

SAML: The Traditional Standard

Security Assertion Markup Language (SAML) is an XML-based framework for exchanging authentication and authorization data. Developed in the early 2000s, it has become the standard for enterprise SSO, particularly in B2B environments. SAML relies on the exchange of XML documents, known as assertions, between the IdP and the SP.

How SAML Works

The most common flow in SAML is the "SP-Initiated" flow. When a user visits a service provider application, the application realizes the user is not logged in. It generates a SAML Authentication Request (AuthnRequest) and sends it to the user's browser, which then forwards that request to the IdP. The IdP authenticates the user (perhaps via MFA) and generates a SAML Response. This response is an XML document containing the user's attributes, which is then passed back through the browser to the Service Provider. The Service Provider validates the digital signature on the XML document to ensure it hasn't been tampered with and that it truly came from the trusted IdP.

The Role of XML and Signatures

Because SAML is XML-based, it is highly expressive and can carry complex metadata about the user. However, this also makes it verbose and somewhat difficult to debug. Every SAML assertion must be digitally signed using a private key from the IdP. The Service Provider uses the IdP’s public key to verify that the signature is valid. This process ensures the integrity of the data; if a malicious actor tries to alter the user’s email address or role within the XML, the signature validation will fail, and the application will reject the login.

Note: SAML is notoriously difficult to implement from scratch. Because of the complexity of XML parsing, signature validation, and the potential for XML-based vulnerabilities (like XML External Entity attacks), you should always use well-maintained, battle-tested libraries for your specific programming language rather than attempting to write your own parser.

OIDC: The Modern Successor

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 framework. While SAML was designed for the enterprise, OIDC was designed for the web and mobile age. It uses JSON and REST-based interactions rather than XML, making it significantly easier to work with for modern web applications, single-page apps (SPAs), and mobile platforms.

The Components of OIDC

OIDC introduces three primary token types:

1. ID Token: A JSON Web Token (JWT) that contains information about the authentication event, such as the user’s identity, the time of authentication, and the issuer.
2. Access Token: An OAuth 2.0 token used by the client to access protected resources (APIs).
3. Refresh Token: Used to obtain new access tokens without requiring the user to re-authenticate.

Why OIDC is Gaining Traction

The primary reason for OIDC’s dominance in modern development is its compatibility with JSON. Most modern web applications use JSON for data exchange, so parsing ID tokens (which are just base64-encoded JSON objects) is a trivial task for any language. Additionally, because OIDC is built on OAuth 2.0, it feels familiar to developers who have already worked with API authorization. OIDC also handles mobile and browser-based flows much more gracefully than SAML, which often struggles with redirects in constrained environments.

Callout: SAML vs. OIDC Comparison

Feature	SAML	OIDC
Data Format	XML	JSON
Transport	Browser Redirects	REST/HTTP APIs
Primary Use Case	Enterprise/Internal SSO	Mobile/Web/API Auth
Complexity	High	Moderate
Security Model	Assertion-based	Token-based (JWT)

Implementing OIDC: A Practical Example

To implement OIDC, you generally follow the Authorization Code Flow. This is the most secure flow for web applications because the tokens are never exposed directly to the user's browser; they are exchanged server-side.

Step-by-Step Authorization Code Flow

1. Authorization Request: The application redirects the user to the IdP’s authorization endpoint, including a client_id, redirect_uri, and the openid scope.
2. User Authentication: The user logs in at the IdP.
3. Authorization Code: The IdP redirects the user back to the application with a short-lived authorization code in the URL.
4. Token Exchange: The application sends a POST request to the IdP’s token endpoint, exchanging the authorization code and the client_secret for an ID Token and an Access Token.
5. Validation: The application validates the ID Token (checking the signature, the audience, and the expiration time) and extracts the user information.

Code Snippet: Validating an ID Token

In Node.js, you might use a library like jose to validate the ID token received from the IdP.

const { jwtVerify, createRemoteJWKSet } = require('jose');

async function validateIdToken(idToken) {
  // The JWKS (JSON Web Key Set) endpoint is provided by your IdP
  const JWKS = createRemoteJWKSet(new URL('https://idp.example.com/.well-known/jwks.json'));

  try {
    const { payload } = await jwtVerify(idToken, JWKS, {
      issuer: 'https://idp.example.com',
      audience: 'my-client-id',
    });
    
    console.log('User identity:', payload.sub); // The user's unique ID
    return payload;
  } catch (err) {
    console.error('Invalid token:', err.message);
    throw new Error('Unauthorized');
  }
}

This code snippet demonstrates the core of OIDC security. By using the createRemoteJWKSet function, the application automatically fetches the IdP's public keys to verify the token signature. This ensures that even if an attacker generates a fake token, they cannot sign it with the IdP's private key, and the application will reject it.

Best Practices for Identity Federation

Implementing federation is not just about getting the login to work; it is about maintaining a secure posture over time. Follow these best practices to ensure your implementation remains resilient.

1. Use Short-Lived Tokens

Never rely on long-lived ID tokens. If an ID token is stolen, an attacker could impersonate the user until the token expires. Always use short expiration times (e.g., 5 to 15 minutes) and rely on refresh tokens to obtain new ones.

2. Implement Proper Scoping

Only request the user information you actually need. OIDC uses "scopes" to limit the data returned. If you only need the user's email address, only request the email scope. Do not request profile or offline_access unless they are strictly necessary for the application's functionality.

3. Secure Your Redirect URIs

The redirect_uri is a common target for attacks. Always use exact matches for your redirect URIs in the IdP configuration. Never use wildcards, as this can allow an attacker to redirect a user to a malicious site after a successful authentication.

4. Monitor IdP Metadata

Both SAML and OIDC rely on metadata (such as signing certificates). If your IdP rotates its certificates, your application will break if it is not configured to fetch the new metadata automatically. Ensure your application logic is capable of dynamic key rotation.

5. Enforce MFA at the IdP Level

The security of your application is only as strong as the security of the IdP. Always enforce Multi-Factor Authentication (MFA) at the Identity Provider level. This ensures that even if a password is compromised, the attacker cannot complete the authentication process.

Common Pitfalls and How to Avoid Them

Even experienced engineers fall into traps when setting up federation. Awareness of these pitfalls is the first step toward avoiding them.

Pitfall 1: Ignoring Audience Validation

In OIDC, the aud (audience) claim in the ID token tells the application who the token was intended for. A common mistake is failing to verify that the aud matches your client_id. If you skip this, an attacker could potentially use a token issued for another application and present it to yours, tricking your app into granting them access.

Pitfall 2: Over-reliance on Client-Side Logic

Some developers try to handle the entire authentication flow in the browser (the Implicit Flow). This is now considered obsolete and dangerous. Because tokens are exposed in the URL fragment in the Implicit Flow, they are vulnerable to being leaked via browser history, referrer headers, or malicious extensions. Always use the Authorization Code Flow with Proof Key for Code Exchange (PKCE).

Tip: Even if you are building a Single Page Application (SPA), do not use the Implicit Flow. Use the Authorization Code Flow with PKCE. PKCE adds a layer of security by requiring the client to prove it is the same entity that initiated the authorization request, even without a client secret.

Pitfall 3: Improper XML Handling (SAML specific)

If you are using SAML, you must be wary of XML signature wrapping attacks. These attacks involve modifying the XML document to inject a different identity while keeping the original signature intact. Always use a reputable library that handles XML canonicalization and signature verification according to the SAML specification.

The Future of Identity: Beyond Passwords

Identity federation is evolving. We are moving toward a world where the "password" component of authentication is becoming less relevant. Concepts like FIDO2/WebAuthn allow users to authenticate using biometrics (like TouchID or FaceID) or security keys, which are then federated through OIDC or SAML. This "passwordless" future significantly improves both user experience and security.

Furthermore, Decentralized Identity (DID) and Verifiable Credentials are beginning to emerge. In these models, the user holds their own identity data in a digital wallet, and the IdP acts more as an issuer of verifiable claims rather than a central repository of user credentials. While these technologies are still maturing, the fundamental principles of federation—trust, standardized protocols, and secure assertion exchange—will remain the foundation of how we manage access.

Summary: Key Takeaways

1. Federation is Essential: Identity federation is the industry standard for secure, scalable authentication, removing the need for local password storage and simplifying user management.
2. SAML for Enterprise: SAML is a mature, XML-based protocol favored by large enterprises and legacy systems. It is robust but can be complex to implement correctly.
3. OIDC for Modern Apps: OIDC is the preferred protocol for modern web, mobile, and API-driven applications. It is built on JSON and OAuth 2.0, making it easier to integrate and more flexible.
4. Trust the IdP: The security of your application is derived from the trust relationship with your IdP. Always enforce MFA at the IdP level to ensure a high level of assurance.
5. Validation is Non-Negotiable: Whether using SAML or OIDC, you must validate every assertion or token. Check signatures, audiences, expiration times, and issuers rigorously.
6. Prefer the Authorization Code Flow: For OIDC, always use the Authorization Code Flow with PKCE. Avoid legacy flows like Implicit or Resource Owner Password Credentials.
7. Keep Dependencies Updated: Identity protocols are prime targets for security research. Use well-maintained libraries and keep them updated to protect your application from newly discovered vulnerabilities.

By mastering these protocols, you are not just learning how to log a user into an app. You are learning how to build a foundation for secure, reliable, and user-friendly digital systems. Whether you are connecting an internal tool to your company's Active Directory or building a public-facing application that supports "Sign in with Google," the principles of identity federation remain your most powerful tool in the security toolkit.