How Identity Provider Bridging Works: SAML-to-OIDC Token Translation

The modern web faces a fragmentation problem: legacy enterprise systems rely on SAML 2.0, while modern single-page applications and mobile clients demand OAuth 2.0 and OpenID Connect (OIDC). A naive integration attempt fails because the message formats are structurally incompatible. SAML assertions are XML-based, signed by X.509 certificates, and rely on HTTP POST bindings with stateful session cookies. OIDC tokens are JSON Web Tokens (JWTs), signed with RS256 or ES256, and designed for stateless, bearer-token authentication.

Identity provider bridging solves this not by translating the protocols in transit, but by introducing an intermediary actor—the Identity Broker. This broker, such as Keycloak, acts as a "man-in-the-middle" that is simultaneously a SAML Relying Party (RP) and an OIDC Identity Provider. It does not merely forward packets; it terminates the SAML session, authenticates the user, and initiates a fresh OIDC session.

The Architecture of the Bridge

Consider a scenario involving three named actors: a legacy application called LegacyHR, an identity broker named Broker-Alpha, and a modern mobile app called App-X.

LegacyHR is a SAML Service Provider (SP). It expects a SAML Assertion from an Identity Provider (IdP) named Corp-IdP. App-X is an OIDC client expecting an ID Token from an OIDC provider. Broker-Alpha sits between them.

For this to work, Broker-Alpha must hold two distinct trust relationships:

1. Trust as a SAML RP: Broker-Alpha trusts Corp-IdP. It has the public certificate to verify signatures on SAML assertions.
2. Trust as an OIDC IdP: App-X trusts Broker-Alpha. It has the public key to verify the OIDC ID Token issued by the broker.

In this architecture, Corp-IdP never speaks directly to App-X. The bridge isolates the legacy protocol from the modern one. The broker effectively becomes the "IdP" for App-X and the "SP" for Corp-IdP.

The SAML Ingestion Mechanism

The process begins when a user attempts to access LegacyHR. LegacyHR redirects the user's browser to Broker-Alpha with a SAML Authentication Request. Broker-Alpha sees that the user is not authenticated locally. Instead of asking for a password, Broker-Alpha realizes it needs a SAML assertion from Corp-IdP.

Broker-Alpha constructs a SAML Authentication Request. This is an XML document containing a <samlp:AuthnRequest> element. Crucially, Broker-Alpha includes its own entity ID (e.g., urn:keycloak:broker-alpha) as the Issuer and sets the Destination to the SSO URL of Corp-IdP.

The user's browser follows a standard SAML Redirect or POST binding. The browser sends this request to Corp-IdP. Corp-IdP checks its local directory, finds the user, and generates a SAML Assertion. This assertion is an XML blob containing:

• A <saml:Subject> with a NameID (e.g., user@corp.com).
• A set of <saml:Attribute> statements (e.g., email, groups).
• A digital signature over the entire assertion using the Corp-IdP's private key.

Corp-IdP posts this assertion back to Broker-Alpha's Assertion Consumer Service (ACS) endpoint.

The OIDC Translation Mechanism

Here is where the mechanism diverges from simple forwarding. Broker-Alpha receives the raw XML. It performs strict validation:

1. Signature Verification: It uses the pre-configured X.509 certificate of Corp-IdP to verify the XML signature. If the signature fails, the request is rejected immediately.
2. Assertion Validation: It checks the NotBefore and NotOnOrAfter timestamps to ensure the assertion is fresh and within the valid window.
3. Subject Extraction: It parses the NameID from the <saml:Subject>.

At this point, Broker-Alpha has authenticated the user. It now enters the translation phase. It creates an internal user session. The core mechanism is the claim mapping engine.

The broker takes the SAML NameID and maps it to the OIDC sub (subject) claim. For example, if the SAML NameID is 12345 and the SAML attribute email is user@corp.com, the broker might decide to use the email as the sub claim for better uniqueness, or stick to the NameID if the policy requires it.

{
  "iss": "https://broker-alpha.example.com/realms/broker-realm",
  "sub": "user@corp.com",
  "aud": "app-x-client-id",
  "exp": 1715629200,
  "iat": 1715629140,
  "email": "user@corp.com",
  "groups": ["HR_Managers"]
}

The broker then signs this JSON object using its own private key (RS256) to create the OIDC ID Token. The aud (audience) claim is critical here; it is set to the client_id of App-X, ensuring that unauthorized OIDC clients cannot use the token.

The Token Exchange Flow

Once the ID Token is generated, Broker-Alpha redirects the user's browser back to LegacyHR (the original redirect URI), typically via the OIDC Implicit Flow or Authorization Code Flow. The ID Token is included in the query parameter id_token or the fragment.

LegacyHR receives the token. It does not know that the user was authenticated via SAML. To LegacyHR, Broker-Alpha is simply the Identity Provider. LegacyHR validates the signature of the ID Token using the public key published in Broker-Alpha's OIDC discovery document (/.well-known/openid-configuration).

If the signature is valid and the exp claim is not expired, LegacyHR grants access. The user is logged in.

Notice the absence of a "handshake" between Corp-IdP and LegacyHR. The bridge is complete. The SAML session with Corp-IdP is terminated by the browser redirection, and a new OIDC session is established with Broker-Alpha.

Security and Trust Boundaries

This architecture introduces a specific security dynamic known as the "double hop." The user authenticates to Corp-IdP, which is trusted by Broker-Alpha. Broker-Alpha then authenticates to LegacyHR.

A critical failure mode occurs if the trust relationship is misconfigured. If Broker-Alpha does not strictly validate the NameID format or fails to map attributes correctly, LegacyHR might grant access to a user who is not authorized in the legacy system. For instance, if Corp-IdP asserts a user is in the Finance group, but Broker-Alpha fails to map the SAML attribute role to the OIDC roles claim, LegacyHR might allow the user to access financial data they shouldn't have.

Furthermore, the aud (audience) claim in the OIDC token must be strictly enforced. If Broker-Alpha issues a token with a generic audience (e.g., *), any client could replay that token. The broker must dynamically set the aud claim based on the client_id requested by LegacyHR.

Opinion: While this bridging solves interoperability, it adds latency. Every login now requires two round-trips: one to the legacy IdP and one to the broker. In high-throughput environments, caching the SAML assertion or the internal user session is necessary to prevent the IdP from becoming a bottleneck.

Implementation Nuances in Keycloak

In Keycloak specifically, this is configured via the "Identity Broker" feature. You add a SAML provider configuration (pointing to Corp-IdP) and an OIDC provider configuration (for LegacyHR).

When a user logs in via the SAML broker, Keycloak creates a local identity link. The syncMode setting determines how attributes are handled. In FORCE, Keycloak overwrites local attributes with SAML data. In LEGACY, it merges them. For a clean bridge, FORCE is often preferred to ensure the OIDC token reflects the exact state of the legacy assertion.

The translation happens in the Keycloak event listeners or the internal identity provider mapper. You configure a "SAML Subject Mapper" to map the SAML NameID to the OIDC sub claim, and "SAML Attribute Mapper" to map email to email. Keycloak then handles the signing of the final JWT automatically using the realm's public/private key pair.

This mechanism allows organizations to migrate to modern standards without forcing every legacy system to upgrade its authentication stack overnight. The bridge absorbs the complexity, presenting a uniform API to the modern client while preserving the security guarantees of the legacy IdP.

Common Pitfalls

Implementing SAML-to-OIDC bridging introduces specific failure modes that require careful attention during deployment:

• NameID Format Mismatch: SAML supports various NameID formats (Email, Persistent, Unspecified). If the broker expects a specific format (e.g., Email) but the IdP provides a Persistent ID, the subject extraction will fail unless a transformation rule is explicitly configured.
• Clock Skew Issues: SAML assertions have strict validity windows (NotBefore, NotOnOrAfter). If the clock on the Broker-Alpha server drifts significantly from Corp-IdP, valid assertions may be rejected as expired or not yet valid. Synchronizing time via NTP is mandatory.
• Certificate Rotation Delays: When IdP certificates rotate, the broker must update its local trust store immediately. A gap in rotation can cause authentication failures for hours or days, creating a critical availability risk during the transition.

Practical Takeaways

Architects should consider the following decisions when deploying an identity bridge:

• Subject Claim Strategy: Decide early whether to preserve the SAML NameID as the OIDC sub or map a more stable attribute (like email) to ensure identity consistency across different legacy systems.
• Token Lifetime Configuration: Adjust the OIDC exp (expiration) claim to be shorter than the SAML assertion validity window to minimize the window of opportunity for token replay attacks.
• Caching Strategy: Implement aggressive caching of the internal user session at the broker level to reduce the load on the legacy IdP, especially for high-frequency authentication events.

Conclusion

Identity provider bridging is not magic; it is a deterministic protocol translation layer where an intermediary (the broker) acts as a SAML Relying Party (RP) to fetch an assertion, then re-issues a valid OIDC ID Token using the SAML subject identity as the sub claim, effectively decoupling legacy SPs from modern client apps. By understanding the architecture, the ingestion mechanisms, and the strict security boundaries involved, architects can safely integrate legacy systems with modern applications without compromising security or performance.

FAQ

Q: Can I use the same user credentials for both the SAML and OIDC flows? A: Yes, but it is generally recommended to rely on the IdP's existing session. The broker should act as a pass-through for authentication, leveraging the existing SAML session to avoid prompting the user for credentials twice.

Q: Does the broker need to know the user's password? A: No. The broker acts as a SAML Relying Party. It receives the signed assertion from the IdP and validates the signature. It never sees or stores the user's plaintext password.

Q: Is this approach suitable for high-security environments? A: It is suitable, provided that strict certificate validation and claim mapping rules are enforced. However, the added complexity of the double-hop architecture increases the attack surface, so rigorous auditing of the broker's configuration is essential.