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
Email 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.

Design our federation

Bring downstream applications, the authoritative user identifier and the required disablement-to-denial interval.