In today's security landscape, organizations rarely rely on a single identity provider. Users can authenticate through corporate directories such as Active Directory, cloud identity providers like Entra ID, or social providers such as Google. They might come through partner federations or specialized systems. This is true for enterprises, Software-as-a-Service providers, and ISVs.

Managing these diverse identities can be a challenging task. You need to strike a balance between maintaining security and providing a good user experience. This is where a federation gateway becomes essential: an identity broker that orchestrates authentication across all these different sources.

This post explores how to architect and implement a federation gateway using Duende IdentityServer, examine the business requirements that drive these decisions, and provide technical guidance for implementation.

What is a Federation Gateway?

A federation gateway acts as an intermediary between your applications (clients / relying parties) and multiple identity providers (IdPs). Rather than forcing each application to integrate directly with every possible identity provider, the gateway provides a single, consistent integration point for a solution. With a gateway, applications authenticate users through a single protocol, e.g. OpenID Connect. The gateway handles the complexity of routing authentication requests to the appropriate upstream identity provider, regardless of whether that provider supports OpenID Connect (OIDC), SAML, WS-Federation, or another protocol.

graph LR
    A[Client Application] -->|OIDC| B[Federation Gateway<br/>Duende IdentityServer]
    B -->|SAML| C[Corporate ADFS]
    B -->|OIDC| D[Entra ID]
    B -->|OIDC| E[Google]
    B -->|OIDC| F[Partner IdP]
    style B fill:#4A90E2,color:#fff

This architecture delivers several benefits:

• It reduces integration complexity, as your applications only need to integrate with one identity provider, authentication protocol, and technology stack.
• Your users get a consistent experience across authentication methods.
• As business relationships evolve, you can change provider integrations without touching application code.

Why You Need a Federation Gateway

In addition to simplifying your identity architecture while making it more flexible, several other requirements can make a federation gateway a necessity.

Accommodating External Identity Infrastructure: Organizations may need to onboard partners, customers, or acquired companies without forcing them to abandon their existing identity infrastructure. Consider a healthcare network acquiring regional hospitals, where each facility needs to continue using its existing authentication while the network centralizes access management. Or think about a SaaS platform serving multiple enterprise customers, where each customer has their own corporate identity provider. Some may use Entra ID, while others might use Okta. Software vendors may use a federation gateway to make the applications they distribute agnostic to their customers’ authentication systems. Only the gateway needs to be adapted to the customer environment, not the applications.

Operational Agility: A federation gateway enables you to add, remove, or modify provider integrations without requiring changes to application code. This operational agility means your infrastructure adapts as business needs evolve.

Protocol Bridging: External IdPs may use different protocols to authenticate users. Your applications may expect OIDC from the federation gateway, while external IdPs may not support OIDC and instead require SAML or other protocols to be used. A federation gateway bridges these protocols and unifies how your applications authenticate users.

Centralized Compliance Enforcement: Regulatory requirements often mandate specific authentication methods, audit trails, or data handling procedures. A federation gateway provides a single, centralized enforcement point for compliance policies, step-up authentication, and consistent logging across all identity providers. This centralized approach simplifies audit and compliance processes.

Unified User Login Experience: For users, you'll want a predictable login experience regardless of which identity provider authenticates them. The user may be presented a list of external IdPs they can authenticate with, or be routed based on their email domain or other properties. A federation gateway abstracts the underlying complexity, presenting a unified interface while routing to appropriate providers based on business rules.

These considerations and scenarios translate to several business drivers, expected outcomes, and KPIs:

Let's shift our focus to the underlying technology that powers these scenarios. To fully realize the anticipated outcomes, it's crucial to explore the technical and architectural considerations of implementing a federation gateway, examining factors like security protocols, integration patterns, and deployment topologies. This technical deep dive will provide a foundation for your planning.

Configuring and Registering Authentication Providers

The foundation of any federation gateway is its ability to integrate with multiple identity providers dynamically. Duende IdentityServer utilizes ASP.NET Core's authentication handler infrastructure to provide robust support for external authentication. A variety of third-party open source and commercial authentication handlers are available for common providers like Google, Microsoft, Facebook, and specialized enterprise systems such as SAML, WS-Federation, and others. This ecosystem makes it straightforward to add support for new providers as needed.

When building a federation gateway, consider how flexible registration of external providers should be. Are external IdP integrations stable and almost static? Or do they change often enough to require a more dynamic approach where configuration can be changed or providers need to be added/removed at runtime?

Static Provider Configuration

For well-known, stable providers, static configuration through startup code or configuration files works well. It typically involves adding and configuring multiple authentication schemes in the startup code of your federation gateway.

While in practice the configuration will be more elaborate, a minimal configuration that adds both Entra ID and Google as external authentication providers could look like the following:

services.AddAuthentication(options => {
        options.DefaultScheme = "Cookies";
    })
    .AddCookie("Cookies")
    .AddOpenIdConnect("Entra", options => {
        options.SignInScheme = "Cookies";
        options.Authority = "https://login.microsoftonline.com/tenant-id";
        options.ClientId = "client-id";
        options.ClientSecret = "client-secret";
    })
    .AddOpenIdConnect("Google", options => {
        options.SignInScheme = "Cookies";
        options.Authority = "https://accounts.google.com";
        options.ClientId = "google-client-id";
        options.ClientSecret = "google-client-secret";
    });

This static configuration works well for many scenarios; however, it has its limitations. Because configuration is stored in code, a redeployment is required whenever configuration changes are made.

What if you need to add a new identity provider without redeploying your application? What if tenant administrators need to configure their own providers through an administrative interface? This is where dynamic provider registration becomes valuable.

Dynamic Provider Registration

For scenarios where providers are added through administrative interfaces or need to change without redeployment, Duende IdentityServer offers dynamic provider features. This allows tenant administrators to configure new identity providers without requiring application changes.

The dynamic provider feature enables you to build multi-tenant scenarios where each tenant can configure their own identity provider. This is critical for B2B SaaS applications where each customer organization has its own corporate identity system.

Routing Users to the Right Provider

One of the most critical functions of a federation gateway is determining which identity provider should authenticate a given user. This routing decision can be made using a technique called Home Realm Discovery (HRD), or it can be as simple as having the user click a button that selects the correct external identity provider.

Home Realm Discovery (HRD)

Home Realm Discovery is the process of identifying which identity provider owns a user's identity. Common approaches include email domain mapping, using an organizational identifier, or using client hints.

The most common approach for Home Realm Discovery is to map email domains to providers. A user entering john@contoso.com is automatically routed to Contoso's corporate IdP, while jane@fabrikam.com goes to Fabrikam's system. This works well when each organization has a distinct email domain.

flowchart TD
   A[User Enters Email] --> B{Parse Email Domain}
   B -->|"@contoso.com"| C[Route to Contoso AD FS]
   B -->|"@fabrikam.com"| D[Route to Fabrikam Entra ID]
   B -->|"@gmail.com"| E[Route to Google]
   B -->|Unknown| F[Show Provider Selection]

For scenarios where email domains are unreliable, users may provide a company code or select from a list of organizations. For example, a user might enter "CONTOSO" as their organization identifier, or select "Contoso Corporation" from a dropdown list, which then routes them to the appropriate identity provider.

Applications can provide hints about which provider to use through acr_values or custom parameters in the authentication request. A mobile app for Contoso employees, for instance, could automatically include a hint to use the Contoso identity provider, skipping the discovery step entirely.

Another type of hint that is often used relies on the DNS name, where the identity provider is chosen based on the (sub)domain used to access it. For example, users who sign in via contoso.login.example.com may be routed to use the Contoso identity provider.

Provider Selection User Interface

When automatic routing isn't possible or desirable, presenting a provider selection interface is necessary. This UI should display only providers relevant to the user, filtered by client configuration or user context. For example, a mobile banking app might only display corporate SSO and biometric options, while a web portal might show corporate SSO, Google, and Microsoft accounts. The UI should remember previous selections for returning users and provide clear branding for each provider option. Handling error cases gracefully when providers are unavailable is also essential.

Processing Identity Information from Providers

Once a user authenticates with an upstream provider, the federation gateway must process the incoming identity information. This involves mapping, transforming, and potentially storing claims.

Claim Mapping and Transformation

Different identity providers structure claims differently. Entra ID might return upn while Google returns email. Your applications expect consistent claim types regardless of the authentication source:

options.ClaimActions.MapJsonKey("email", "upn");
options.ClaimActions.MapJsonKey("name", "displayName");

You might also need to handle provider-specific scenarios. For instance, mapping different claim names from various providers to a standard set, or transforming nested JSON structures into flat claims:

// Handle different email claim names from various providers
options.ClaimActions.MapJsonKey("email", "mail");
options.ClaimActions.MapJsonKey("email", "emailAddress");

// Extract phone number from nested structure
options.ClaimActions.MapJsonKey("phone_number", "contactInfo.phoneNumber");

Beyond simple mapping, transformation logic might normalize claim values (such as converting email addresses to lowercase), derive additional claims from existing ones (such as extracting the department from an email domain), enrich claims with data from internal systems, or filter sensitive claims that shouldn't flow to applications.

Identity Storage and Correlation

A critical decision is whether to store user identities locally in the identity provider, or not.

One approach is Just-in-Time (JIT) Provisioning, where you create a local user record on first login, linking it to the external provider. This enables consistent user identifiers across sessions, storage of application-specific data, audit trails independent of provider availability, and user correlation when individuals have multiple provider identities. JIT provisioning also allows you to store additional data that the upstream provider may not provide, such as internal employee IDs, department assignments, or custom authorization roles, which the federation gateway can then communicate to client applications through claims.

Alternatively, federation could be stateless and pass claims directly through without local storage, minimizing data retention but limiting profile management capabilities.

A hybrid approach would store minimal correlation data (external provider ID mapped to internal ID) while keeping detailed profile data in upstream systems.

Additional User Experience Steps

Authentication can be more than just logging in. Modern identity scenarios often require additional interactions, such as collecting missing profile information, accepting terms of service, or performing step-up authentication for sensitive operations.

Step-Up Authentication

Applications with sensitive operations may require additional authentication factors even when users are already authenticated. A banking application might allow users to view account balances with simple authentication but require step-up to multi-factor authentication for wire transfers:

// Application requests step-up authentication
var authRequest = new AuthenticationProperties();
authRequest.Items["acr_values"] = "mfa";

The federation gateway evaluates whether the current authentication meets the requested level and initiates step-up if necessary.

Tip: For a detailed guide on implementing step-up authentication challenges in ASP.NET Core client applications with Duende IdentityServer, see our blog post on Step-up Challenges for ASP.NET Core Client Apps.

Additional Profile Data Collection

Some providers return minimal information. The federation gateway might need to collect additional required profile data such as missing email addresses from social providers, terms of service acceptance, marketing preferences, or department and cost center information.

Duende IdentityServer enables customization of every aspect of the UI and UX, making implementation straightforward. You can add custom pages to your authentication flow to collect missing information, such as asking users to provide their phone number if the external provider didn't return one, or requesting their job title and department for internal record-keeping. You might also present a terms of service agreement that users must accept before proceeding, or gather consent for data processing in compliance with regulations.

Invitation and First-Time User Flows

In some applications, there are workflows where new users are invited with an initial login link. The invitation is typically stored with the expected identity based on email domain mapping. When the invitee clicks the invitation link and authenticates, the gateway matches their authenticated identity to the invitation and provisions the user with appropriate permissions and associations.

The gateway must also handle edge cases. What if the user authenticates with a different provider than expected? What if they already have an account? Tools like Duende IdentityServer enable careful UX design to avoid confusion.

Returning vs. New Users

The experience should differ based on whether this is a user's first login or a return visit. First-time users may see welcome messages, profile completion forms, or onboarding workflows. Returning users should skip directly to their application with minimal friction. Users with multiple identities can be offered account linking to consolidate profiles.

Returning Identity Assertions to Client Applications

The last step in the authentication flow is returning identity information to the client application as an OpenID Connect ID token and access token.

Token Content and Claims

The tokens issued by the gateway should contain several types of information. Identity claims tell you who the user is. Claims include the subject identifier, and typically also profile information name, and email.

Authentication context claims describe how and when an authentication occurred, using fields such as amr, acr, and auth_time. Session information includes session identifiers for coordinating single sign-out. Finally, application-specific claims contain roles or other data needed by the application.

Single Sign-Out Coordination

When a user logs out, the gateway may coordinate sign-out across multiple layers. First, terminate the session with the client application. Then terminate the session at the gateway. Finally, you can (optionally) initiate sign-out with the upstream identity provider using either front-channel or back-channel logout.

An important consideration is whether to propagate logout to the upstream provider. Do you want to log out of someone's Microsoft account when they sign out of your application? Or should you only sign out in your app and federation gateway while maintaining the Microsoft account session for SSO with the user's other applications? This decision depends on your security requirements and user expectations. For enterprise scenarios, you might want to maintain the upstream session to enable SSO across multiple applications. For consumer scenarios with shared devices, you might prefer to fully sign out everywhere. Duende IdentityServer provides you with complete control over these details, allowing you to tailor them to match your business requirements.

Implementation Considerations and Best Practices

When implementing a federation gateway with Duende IdentityServer, several practical considerations come into play that can make the difference between a robust production system and one that struggles under real-world conditions.

Performance matters when every authentication requires multiple network round trips to upstream providers. Cache provider discovery documents and validation keys according to their expiration times. This reduces latency and protects against provider slowdowns. Configuration data that changes infrequently should also be cached appropriately to minimize repeated lookups. Additionally, this can help mitigate network issues, reduce maintenance windows, and prevent provider outages.

Your federation gateway sits at a critical security boundary between external identity providers and your applications. Implement comprehensive logging of all authentication attempts, including both successful and failed attempts. Monitor for suspicious patterns such as repeated failures from specific providers or unusual claim values. Maintain strict input validation on all data received from external providers, remembering that a compromised upstream provider could send malicious data.

Testing with real identity providers in staging environments reveals issues that mocks cannot. Protocol implementations vary between providers, claim formats differ in subtle ways, and error conditions manifest differently. Allocate time for thorough integration testing with each provider you plan to support in production.

If you're replacing existing authentication infrastructure, plan for a gradual migration rather than a big-bang cutover. Support both old and new authentication paths during the transition period. This allows you to validate the new gateway with a subset of users or applications before committing fully. It also provides a fallback path if unexpected issues arise.

For more detailed guidance on implementing federation scenarios, see the Duende IdentityServer federation documentation.

Conclusion

A federation gateway built on Duende IdentityServer provides the architectural foundation for modern identity scenarios. By centralizing the complexity of multiple identity providers, protocol translation, and identity orchestration, you create a more secure, maintainable, and agile identity infrastructure.

The business value extends beyond technical elegance: faster partner onboarding, reduced application development complexity, centralized compliance enforcement, and improved user experiences. As your organization's identity requirements evolve (adding new providers, supporting new protocols, or implementing new security requirements), a well-architected federation gateway adapts without requiring changes to every downstream application. Tools like Duende IdentityServer provide complete control over the business logic and user experience when building a federation gateway.

For senior developers planning these implementations, the key is understanding both the business drivers and the technical architecture. Start with clear requirements around which providers you need to support, how users should be routed, what claims your applications require, and what compliance or security policies must be enforced. Then design your gateway implementation to meet these needs while maintaining flexibility for future requirements.

The topics covered in this post represent the core capabilities of a federation gateway. Each organization will weigh these capabilities differently based on its specific requirements; however, understanding the entire landscape enables informed architectural decisions and productive conversations with your identity team and CTO.