SAML 2.0, OpenID Connect and WS-Federation bridge

FoxIDs can act as a protocol bridge between SAML 2.0, OpenID Connect / OAuth 2.0 and WS-Federation. This lets an application keep using one identity protocol while the external identity provider or partner application uses another.

The bridge is not a separate component that you have to install. It is the normal FoxIDs model: users sign in through an authentication method, and FoxIDs issues the response required by the application registration. When the two sides use different standards, FoxIDs performs the protocol translation, claim mapping, token creation and sign-in routing.

Use the bridge when:

An application already supports OpenID Connect and needs to sign in users from a SAML 2.0 or WS-Federation identity provider.
A SAML 2.0 or WS-Federation application needs to use an OpenID Connect identity provider.
A legacy WS-Federation or SAML 2.0 application should be connected to a modern OpenID Connect identity platform without changing the application.
Several applications should trust the same FoxIDs environment even though they use different standards.

Federated Identity Management (FIM) links identities across domains. Single Sign-On (SSO) lets users access applications without signing in again. FoxIDs supports both, and the bridge makes FIM and SSO work across protocol boundaries.

How the bridge works

OpenID Connect, SAML 2.0 and WS-Federation solve many of the same identity problems, but their messages, tokens, metadata, certificates and claim formats are different.

OpenID Connect is built on OAuth 2.0 and is commonly used by modern web, mobile and API-based applications. It uses JSON Web Tokens (JWTs) for identity tokens and access tokens.
SAML 2.0 is XML-based and is widely used for enterprise browser-based SSO. It uses SAML assertions and XML signatures.
WS-Federation is XML-based and is commonly used by enterprise and legacy web applications. It typically uses SAML 1.1 or SAML 2.0 tokens in WS-Federation sign-in responses.

FoxIDs bridges these standards by acting as the trusted party on both sides of the connection:

Towards the external identity provider, FoxIDs is configured as an authentication method.
Towards the application, FoxIDs is configured as an application registration.
Internally, FoxIDs represents claims as JWT claims and maps between JWT claims and SAML claims when needed.
The application receives the protocol response it already understands.

There is no requirement that the inbound and outbound protocols are the same. An OpenID Connect application can use a SAML 2.0 authentication method. A SAML 2.0 application can use an OpenID Connect authentication method. WS-Federation can also be used on either side.

Configure a bridge

A bridge is configured by combining an authentication method with an application registration in the same environment.

Configure the upstream identity provider as an authentication method:
Configure the application as an application registration:
In the application registration, select the authentication method that should handle sign-in.
If more than one authentication method is available, let the application select one directly or let the user select on a home realm discovery (HRD) page.
Review claim mappings, certificates, metadata and logout behaviour for the standards used on each side.

The most important configuration choice is therefore not a special bridge setting. It is the pairing of authentication method and application registration.

SAML 2.0 to OpenID Connect

This bridge is common when an application already supports OpenID Connect, but the organisation or partner identity provider only supports SAML 2.0.

Configure the external IdP as a SAML 2.0 authentication method. Configure the application as an OpenID Connect application registration and select the SAML 2.0 authentication method.

When the application sends an OpenID Connect sign-in request, FoxIDs routes the user to the external SAML 2.0 IdP. The SAML 2.0 response is validated, SAML 2.0 claims are mapped to JWT claims, and FoxIDs returns an OpenID Connect response to the application.

Bridge SAML 2.0 to OpenID Connect

OpenID Connect to SAML 2.0

This bridge is useful when a SAML 2.0 application should use a modern OpenID Connect identity provider.

Configure the external provider as an OpenID Connect authentication method. Configure the application as a SAML 2.0 application registration and select the OpenID Connect authentication method.

When the SAML 2.0 application sends a SAML 2.0 Authn Request, FoxIDs routes the user to the OpenID Provider (OP). The OpenID Connect response is validated, JWT claims are mapped to SAML 2.0 claims, and FoxIDs returns a SAML 2.0 response to the application.

Bridge OpenID Connect to SAML 2.0

FoxIDs supports bridging sign-in, logout and single logout between SAML 2.0 and OpenID Connect.

WS-Federation bridge scenarios

WS-Federation works in the same model as the other standards. It can be configured as an authentication method when the external identity provider is a WS-Federation Security Token Service (STS), and as an application registration when the application expects a WS-Federation sign-in response.

Typical WS-Federation bridge scenarios include:

WS-Federation IdP to OpenID Connect application.
OpenID Connect IdP to WS-Federation application.
WS-Federation IdP to SAML 2.0 application.
SAML 2.0 IdP to WS-Federation application.

This is useful for AD FS replacement scenarios, older ASP.NET applications, SharePoint, Dynamics and other systems that still use WS-Federation, while new applications and APIs can continue to use OpenID Connect and OAuth 2.0.

One environment, one Identity Provider

All bridge functionality can be combined in the same FoxIDs environment. For example, an OpenID Connect application can support sign-in through both SAML 2.0 and OpenID Connect authentication methods at the same time.

It is often simpler to let applications and APIs trust one FoxIDs environment as their Identity Provider (IdP), even if users authenticate through different external protocols. In that model:

Applications are registered in FoxIDs with the protocol they already support.
External identity providers are configured as authentication methods.
FoxIDs performs protocol translation and claim mapping between the two sides.
OpenID Connect clients and OAuth 2.0 APIs can keep using ID tokens and access tokens, even when the original sign-in came from SAML 2.0 or WS-Federation.

This model is especially useful when modernising an application landscape gradually. Existing SAML 2.0 and WS-Federation systems can continue running while new applications use OpenID Connect and OAuth 2.0.

Token exchange

If a user signs in to a SAML 2.0 application through an external SAML 2.0 IdP, the application receives a SAML 2.0 token for that user. In zero trust architectures, APIs should still be called in the context of the end user.

Use token exchange when a SAML 2.0 token needs to be exchanged for an OAuth 2.0 access token. The resulting access token can be used to call OAuth 2.0-enabled APIs in the context of the signed-in user.

Claim mappings

FoxIDs uses JWT claims internally and maps SAML 2.0 claims to JWT claims. The same SAML/JWT claim mapping model is also used for WS-Federation because WS-Federation tokens contain SAML claims.

By default, standard mappings are applied, for example sub to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier and email to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

You can add additional JWT to SAML claim mappings in FoxIDs Control. If no mapping exists for a claim, FoxIDs keeps the original claim name. This preserves claims across the bridge while still allowing shorter JWT claim names where mappings are configured.