Introduction

Modern enterprise applications rarely rely on a single identity provider. Organizations often integrate with multiple external systems such as partners, SAML providers, and OIDC providers. Managing these integrations directly within an application or a single IAM system can quickly become complex, brittle, and difficult to scale.

In our implementation, we initially used Duende IdentityServer as the central IAM system. While Duende is powerful for OAuth2/OpenID Connect scenarios, we encountered challenges when integrating with diverse external identity providers—especially those using SAML.

To address these challenges, we introduced Keycloak as an IAM broker, transforming our architecture into a unified, scalable, and flexible identity federation model.

This article explains the problem we faced, the solution we implemented, and how Keycloak helped us build a unified IAM layer.

By introducing Keycloak as a broker, we decoupled identity federation from application logic, enabling scalable onboarding of new identity provider without code changes.

Problem Statement

1. Multiple External Identity Providers

Our system needed to support authentication from multiple sources:

Each provider had:

2. Limitations with Duende IAM

Duende IdentityServer is primarily designed for:

However, we faced several challenges:

❌ SAML Support

Duende does not natively support SAML federation.
We had to rely on external components or custom implementations.

❌ Complex Federation Logic

All mapping logic had to be implemented manually:

❌ No Central Federation Layer

Each new partner integration required:

❌ Lack of Standardized Identity Contract

Different IdPs returned different attributes, leading to:

3. Real-World Example of the Problem

We received SAML assertions like:

<saml:Attribute Name="userid">userId123</saml:Attribute>
<saml:Attribute Name="email">[email protected]</saml:Attribute>
<saml:Attribute Name="phone">123456789</saml:Attribute>

Each partner could send:

Handling this directly in Duende became difficult and error-prone.

Solution: Introducing Keycloak as IAM Broker

To solve these problems, we introduced Keycloak as an identity broker between external IdPs and Duende.

High-Level Architecture

mermaid-diagram
External IdP (SAML/OIDC)
        ↓
   Keycloak (Broker)
        ↓
   Duende IAM (OIDC)
        ↓
   Application / Mobile

Why Keycloak?

Keycloak provides:

How the Solution Works

mermaid-diagram (1)

Step 1: External Authentication (SAML)

User logs in via partner IdP.

User → Partner IdP → Keycloak Broker

Step 2: Keycloak as Broker

Keycloak:

Step 3: Canonical Identity Mapping

We defined a canonical identity contract:

{
  "sub": "userId123",  
  "userid": "userId123",
  "phone": "123456789",
  "email": "[email protected]"
}

Keycloak maps incoming SAML attributes into this structure.

Step 4: OIDC Token Issued to Duende

Keycloak acts as an OIDC Identity Provider for Duende.

Keycloak → Duende (/authorize → /token)
mermaid-diagram (2)

Duende receives:

Step 5: Application Authentication

Duende validates the token and:

Key Feature: kc_idp_hint (HRD Bypass)

To avoid login selection screens, we use:

kc_idp_hint=test-saml-hint

This allows:

Implementation Details

1. Keycloak Identity Provider Configuration

{
  "alias": "test-saml-hint",
  "providerId": "saml",
  "enabled": true
}

2. Attribute Mapping

Example:

SAML AttributeCanonical Claim
usernameuserid
useriduserid
subuserid
firstnamefirstname
lastnamelastname

3. Client Configuration (Duende)

Client: keycloak-oidc-client
Protocol: OIDC
Redirect URI: https://app/callback

Benefits of This Approach

✅ Unified Identity Layer

All IdPs are handled in one place (Keycloak).

✅ Protocol Abstraction

Applications only deal with OIDC — not SAML.

✅ Scalability

Adding a new partner:

✅ Centralized Mapping

All claim transformations handled in Keycloak.

✅ Reduced Complexity in Application Layer

Duende remains clean and focused on:

✅ Improved Security

Comparison: Before vs After

FeatureBefore (Duende Only)After (Keycloak + Duende)
SAML Support❌ Manual✔ Native
Claim Mapping❌ Custom Code✔ Configurable
Multi-IdP❌ Complex✔ Simple
Scalability❌ Low✔ High
Maintainability❌ Hard✔ Easy

Conclusion

Introducing a broker layer like Keycloak fundamentally simplifies enterprise IAM architecture. Instead of tightly coupling applications with multiple identity providers, a broker enables protocol abstraction, centralized mapping, and scalable onboarding. In our case, separating federation (Keycloak) from token issuance (Duende) allowed us to build a flexible and future-proof IAM solution without rewriting application logic.

Using Keycloak as a unified IAM broker significantly improved our identity architecture by:

This hybrid approach—Keycloak for federation + Duende for token issuance—provides a powerful and flexible IAM solution for modern enterprise applications.

Final Thoughts

If your system needs to support:

Then using Keycloak as an IAM broker is a highly effective and scalable approach.