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:
Different attribute formats
Different authentication flows
Different security requirements
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:
Attribute transformation
Claim normalization
Partner-specific logic
❌ 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:
✔ Native SAML and OIDC support
✔ Built-in identity brokering
✔ Flexible attribute mapping
✔ Protocol translation (SAML → OIDC)
✔ Centralized identity management
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:
ID Token
Access Token
Normalized claims
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 Attribute | Canonical Claim |
|---|
| username | userid |
| userid | userid |
| sub | userid |
| firstname | firstname |
| lastname | lastname |
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:
No code change in Duende
Just add IdP in Keycloak
✅ Centralized Mapping
All claim transformations handled in Keycloak.
✅ Reduced Complexity in Application Layer
Duende remains clean and focused on:
Token issuance
Authorization
✅ Improved Security
SAML validation handled at broker layer
OIDC validation handled at Duende
Clear separation of concerns
Comparison: Before vs After
| Feature | Before (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:
Decoupling federation logic from application logic
Standardizing identity contracts
Enabling seamless integration with multiple external IdPs
Reducing complexity and improving scalability
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.