[HOWTO] Add Entra ID as an OIDC identity provider in Keycloak using client assertion

This post describes the setup and configuration of an OpenID Connect (OIDC) Identity provider in Keycloak for federation with Microsoft Entra ID.

Keycloak version: 26.7.3

Goals

• Allow users of a specific Entra ID tenant to sign in to Keycloak using their Entra ID account
• Restrict sign in / access to member users of the specified Entra ID tenant

Concept

Step-by-Step Instructions

NOTE

The optional claim acct (see Optional claims reference) is configured to pass the users account status to Keycloak (if the user is a Member of the Entra ID tenant or a Guest). The identity provider in Keycloak for federation with Entra ID is then configured to require the acct claim to be 0 (0 = Member of the Entra ID tenant, 1 = Guest) for successful authentication (see essential claim configuration below).

1. Log in to the Azure Portal
2. Search for App registrations in the search bar on the top and select it from the results
3. Create a new app registration by clicking on New registration
4. Log in to the Keycloak admin console with an account that has administrative privileges (at least for the corresponding realm)
5. Ensure the current realm is set correctly before proceeding
6. Navigate to the Identity providers section in the menu on the left-hand side
7. Click on the Add provider button and select OpenID Connect v1.0 from the list of available providers
   
   
8. Configure the OpenID Connect provider as follows
   Alias: specify the unique identifier for the identity provider (i.e. entra-oidc)
   Display name: Entra ID
   Use discovery endpoint: On
   Discovery endpoint: https://login.microsoftonline.com/ENTRA_ID_TENANT_ID_HERE/v2.0/.well-known/openid-configuration
   Validate Signatures: On
   Use JWKS URL: On
   Client authentication: JWT signed with private key
   Client ID: CLIENT_ID (Application (client) ID of the app registration in Entra ID created above)
   Client assertion signature algorithm: RS256
   Add X.509 Headers to the JWT: On
9. Click Add
10. Update the identity provider Settings as follows
    Use PKCE: On
    PKCE Method: S256
    Pass login_hint: On (optional)
    Pass current locale: On (optional)
    Send ‘id_token_hint’ in logout requests: On
    Send ‘client_id’ in logout requests: On
    Disable user info: On
    Scopes: openid profile email (adjust according to your needs)
    Trust Email: On (optional)
    Verify essential claim: On
    Essential claim: acct
    Essential claim value: 0
    Sync mode: Force
    Case-sensitive username: On
    Supports client assertions: On
11. Click Save
12. Navigate to the Mappers tab
13. Add mappers if needed
14. Navigate to Realm settings section in the menu on the left-hand side
15. Navigate to the Keys tab
16. Click on the Certificate button on the key with algorithm RS256
17. Create .pem file from the public key part of the downloaded certificate (manually)
18. Log in to the Azure Portal
19. Search for App registrations in the search bar on the top and select it from the results
20. Open the before created app registration
21. Navigate to the Certificates & secrets tab
22. Switch to the Certificates tab
23. Click on the Upload certificate button and select the .pem file created from the Keycloak public key
24. Set description (i.e. Keycloak realm (REALM_NAME) certificate)
25. Click Add
26. Navigate to Authentication (Preview)
27. Click on the Add Redirect URI button
28. Select Web
29. Enter the redirect URI value from the Keycloak identity provider settings
30. Click Save
31. Navigate to Token configuration
32. Click on the Add optional claim button
33. Select ID
34. Select the acct claim
35. Click Add
36. Click on the Add optional claim button again
37. Select Access
38. Select the acct claim
39. Click Add
40. Navigate to API permissions
41. Ensure Microsoft Graph User.Read permission of type Delegated is added and granted for the current tenant

That’s it.