Federate Keycloak with Entra ID
Design Entra ID as an upstream identity provider for Keycloak, including tenant boundaries, first-login linking, downstream claims and session revocation.
Last updated
In short
- Brokering centralizes application trust but adds a second session boundary.
- Existing-account linking requires an explicit verified identity rule.
- Upstream group removal must be checked in downstream applications.
On this page (7)
Integrations · Part of SSO and identity
Give the broker a clear purpose
Federating Keycloak with Entra ID allows applications to trust Keycloak while employees continue authenticating through their established Microsoft directory. The broker can normalize claims or connect several upstream identity sources. It also introduces another database, signing-key set, session layer and recovery responsibility.
Choose this arrangement when those functions solve a concrete problem. For a single application with a supported direct integration, direct Nextcloud sign-in may involve fewer moving parts. This page is a reference design based on upstream documentation, not evidence that a specific tenant and Keycloak release have been tested together.
Understand the two trust relationships
The browser starts at a downstream application. The application redirects to Keycloak, which redirects to Entra for authentication. Entra returns its result to Keycloak. Keycloak then issues a separate token for the application. The application should validate Keycloak’s issuer and audience; it should not treat the upstream Entra token as interchangeable with the downstream one.
| Relationship | Client | Provider | Configuration owner |
|---|---|---|---|
| Upstream login | Keycloak broker | Entra ID | Directory and identity administrators |
| Downstream application | Individual application | Keycloak realm | Application and identity administrators |
| Account lifecycle | Defined provisioning process | Authoritative employee directory | Organization’s identity owner |
| Recovery access | Controlled local administrator | Keycloak or application | Designated operational owner |
Microsoft documents tenant-scoped OIDC discovery and endpoints. Use the intended tenant authority for an organizational deployment. Accepting identities from a broader authority requires a separate, deliberate tenant-validation policy.
Establish a version and entitlement record
Record the Keycloak server release, deployment method, database version, Entra tenant type and downstream application releases. OIDC itself does not imply that every desired feature is free in the application or identity provider. Conditional access, automated provisioning and application-side role synchronization may depend on separate editions or contracts.
Use the Keycloak identity-brokering documentation for the selected release. Menu names, first-login flow options and mapper behavior should be checked against that release rather than copied from a screenshot for another version. Export a sanitized configuration record without client secrets.
Configure the upstream connection in a pilot realm
Create a dedicated Entra application registration for the broker. Obtain the redirect URI from Keycloak’s identity-provider configuration and register that exact URI. Keep the client secret or supported credential in the secret-management process, with an owner and expiry alert. Do not use a wildcard redirect as a shortcut around hostname problems.
Configure the upstream discovery endpoint, client identity and required scopes. Then decide which attributes are imported and whether they update on later logins. Start with a small pilot population and minimal downstream claims. A token carrying every directory group can be unnecessarily large and expose organizational information to applications that do not need it.
| Mapping | Recommended design question | Failure to test |
|---|---|---|
| Upstream subject | What immutable identifier binds the person? | Email change creates another account |
| Display name | Should later logins refresh it? | Stale profile after directory change |
| Is the value verified and authoritative? | Unverified email links to an existing privileged account | |
| Group or role | Which applications need which values? | Broad group becomes application administrator |
| Tenant | Which organizational authority is accepted? | Another tenant gains unintended access |
Treat first login as a security decision
Existing Keycloak accounts may already own documents or application data. Automatically linking a new upstream identity to an existing account by email can be dangerous if the email is not authoritative or account ownership has not been verified. Choose an account-linking flow that proves the relationship, and rehearse collisions with synthetic accounts.
Document what happens when the same person arrives through two identity providers, when a contractor becomes an employee and when an address is recycled. These are identity-lifecycle cases, not cosmetic profile updates. Keep a mapping register for accounts that require manual reconciliation.
Measure logout and revocation end to end
There are at least three session states: Entra, Keycloak and the application. Logging out of one does not automatically prove termination of the others. Define how long downstream access may remain after upstream disablement and which mechanisms enforce that limit.
Test a fresh login, a refreshed token and an already-open application session after removing an upstream group. Repeat after disabling the person in Entra. Inspect application API tokens and machine credentials separately; many are intentionally independent of browser SSO. A useful acceptance record states the actual observed delay and the remaining credential types, rather than saying simply that offboarding works.
Also exercise upstream unavailability. The broker should not create an unplanned local-password bypass when Entra is down. Recovery administrators need an approved path with independent controls and recorded use.
Recover without changing identity accidentally
Back up the Keycloak database, realm configuration, signing-key material and the information needed to restore secret references. A realm export is useful configuration evidence but should not be assumed to replace every operational backup requirement. Restore into an isolated environment and validate issuer URLs and client registrations before any application trusts it.
For rollback, keep the previous identity-provider configuration and a documented way to restore application login. Reverting a broker setting does not undo accounts created or linked during the pilot. Reconcile those identities before deleting anything. The federation is ready when account linking, tenant restriction, least-privilege claims, revocation and recovery all have evidence for the selected versions.
Sources and further reading
Use the linked documentation to confirm the version, edition and contract that apply to your project.
