Keycloak Identity Brokering

The Sovereign Hub of Federation

Identity Brokering is the “Sovereign Hub” of the Keycloak identity ecosystem. It allows Keycloak to act as a Proxy or “Broker” for external Identity Providers (IdPs). Instead of managing thousands of local user accounts, you can “Delegate” authentication to trusted giants like Google, GitHub, or enterprise systems like Okta and Entra ID. When a user logs in via a broker, Keycloak bridges the gap—translating the external identity into a local session and enforcing your own organizational security policies. For the IAM architect, Identity Brokering is the engine of Global Connectivity, enabling seamless entry for partners, customers, and employees through the accounts they already own.

Core Mission

Universal Trust Delegation. Establishing a cryptographically secure framework for accepting external identities while maintaining centralized control over session lifecycle and attribute authorization.

Like a Universal Travel Visa: Imagine you are visiting a foreign country (Your App). Instead of applying for a local ID (A new account), you show your home country's passport (Google/Azure AD). The "Identity Broker" (Keycloak) is the "Sovereign Customs Agent." They check your home passport, verify it's authentic, and issue you a "Temporary Local Visa" (The Keycloak Token). You use that visa to move freely, but the Customs Agent still decides WHICH buildings you can enter based on their own rules.

B2B Partner Integration / Social SSO / Multi-Cloud Identity / Gradual Migration to Keycloak

The Brokering Strategy Matrix

Designing for identity brokering requires aligning the external trust method with your internal security requirements.

Strategic Brokering Profiles

Profile	Strategic Responsibility	IAM Implementation
Social Login	Consumer UX.	Pre-configured connectors for Google, Facebook, Twitter, GitHub.
SAML IdP	Enterprise B2B.	Federated trust with corporate partners using standard XML metadata exchange.
OIDC IdP	Modern Multi-Cloud.	Connecting to Okta, Auth0, or Entra ID via OpenID Connect discovery.
First Login Flow	Attribute Capture.	Designing the workflow to capture missing user data during the initial federated login.

The Brokered Authentication Flow

A brokered transaction is a multi-step “Hand-off” between the application, Keycloak, and the external IdP.

graph LR
    User[Login: Select IdP] --> External[Auth at External IdP]
    External --> Handshake[Protocol Exchange: Keycloak]
    Handshake --> Final[Issue Local Keycloak Token]

Redirect to the Trusted Authority

The user clicks "Login with Google" on the Keycloak login page. Keycloak acts as a **Client** to the external IdP. It redirects the user to Google with a request for specific scopes. The user authenticates using their existing Google credentials and MFA.

The Sovereign Protocol Translation

Google sends a token back to Keycloak. Here, Keycloak acts as the "Sovereign Translator." It validates the Google signature, extracts the user attributes (Email, Name, ID), and maps them into its own internal user model. This ensures that no matter where the user came from, the application receives a consistent format.

First Broker Login & Linking

If this is the user's first time, Keycloak may trigger a "First Login Flow." It asks the user to confirm their email or provide missing info. It then "Links" the external identity to a local Keycloak shadow-account. From now on, the user is part of your realm's ecosystem, subject to your local roles and group policies.

Technical Brokering Implementation

Using ‘Attribute Mappers’ allows you to normalize external data into your internal identity schema.

IdP Attribute Mapper (Conceptual JSON)

# Mapping an Azure AD claim 'roles' to a Keycloak user attribute
{
  "name": "EntraID-Role-Mapper",
  "category": "Attribute Importer",
  "identityProviderAlias": "azure-ad",
  "config": {
    "external.claim": "roles",
    "user.attribute": "external_roles",
    "syncMode": "INHERIT"
  }
}

Brokering Implementation Guides

Master the technical ceremonies of external federation and cross-organization trust.

Next Steps

Explore Keycloak Identity Brokering Guide.
Review OAuth2 Discovery (RFC 8414) for automating broker setup.
Check Broker Event Logs for troubleshooting failed external handshakes.