(TokenThis guide explains how to configure Microsoft Entra ID (formerly Azure AD) as an OpenID Connect v1.0 identity provider for Apporto NextGen through Keycloak. Use it as an end-to-end setup checklist to create the Keycloak OIDC broker, configure the Entra app registration, collect endpoint and credential values, map user attributes, and validate sign-in.
Overview
Keycloak acts as the identity broker for Apporto NextGen. Microsoft Entra ID authenticates users and sends OIDC tokens to Keycloak.
|
System |
Purpose |
|---|---|
|
Keycloak |
Hosts the tenant realm and identity provider configuration. |
|
Microsoft Entra ID |
Hosts the app registration, client credentials, token claims, endpoints, and optional group or role assignments. |
Before you begin
-
Confirm you have administrator access to the Keycloak realm for the customer tenant.
-
Confirm you have a Microsoft Entra administrator account that can create and manage app registrations.
-
Have a test Entra user available for validation.
-
Decide whether authorization will be driven by Entra app roles, group claims, or only by the user profile.
-
Keep both Keycloak and the Microsoft Entra administration consoles open during setup so you can copy values between them.
Configuration flow
-
Add an OpenID Connect v1.0 identity provider in Keycloak and collect the Keycloak Redirect URI.
-
Create an app registration in Microsoft Entra ID.
-
Configure the Keycloak Redirect URI on the Entra app registration.
-
Add ID token claims for username and email values.
-
Collect endpoint values from Microsoft Entra ID.
-
Configure the OIDC endpoints, client ID, and client secret in Keycloak.
-
Optionally enable permissions and claims for group sync.
-
Review advanced Keycloak settings.
-
Create Keycloak mappers for username, email, and optional roles.
-
Test sign-in end to end.
Instructions
Step 1: Add the OpenID Connect provider in Keycloak
-
Sign in to the Keycloak administration console.
-
Select the customer realm.
-
Go to Identity Providers.
-
If no providers exist, use the wizard. Otherwise, click Add provider.
-
Select OpenID Connect v1.0.
Set the provider alias
Enter a short, unique alias for the provider. Do not use spaces.
Example:
entraid-oidc
Do not use a discovery endpoint at this stage. You will provide endpoint values later.
Keep this Keycloak page open and copy the generated Redirect URI. You will need it when creating the Entra app registration.
Collect Keycloak service provider values
Copy the Redirect URI generated by Keycloak. The provider alias becomes part of the callback URI.
Example Redirect URI:
https://<keycloak-host>/realms/<realm-name>/broker/<alias>/endpoint
The provider alias becomes part of the Keycloak broker endpoint.
If the alias is entraid-oidc, Entra ID must redirect to /broker/entraid/endpoint exactly.
Step 2: Create the app registration in Entra ID
Create a new app registration in Microsoft Entra ID. This app authenticates users and redirects them to Apporto NextGen after successful sign-in.
-
Sign in to Entra ID at
https://entra.microsoft.com. If your Azure account has multiple Directories, make sure to Switch to the correct one before proceeding further. -
Go to App registrations → New registration.
-
Name the app after the tenant realm, for example
tenant-my-school-realm. -
Select Single tenant.
-
Under Redirect URI, select Web.
-
Paste the Redirect URI from Keycloak. Example:
https://<your-keycloak-host>/realms/<your-realm>/broker/entraid/endpoint -
Click Register.
Step 3: Configure ID token claims
On the app registration (Token configuration), add the following claims of type ID:
-
email
-
family_name
-
given_name
-
upn
Ensure to also add Graphs as option during the above selection.
These claims allow Keycloak to map the user’s username and email address reliably.
Step 4: Collect endpoint values from Entra ID
On the app registration Overview page, click Endpoints. Use these values to configure the Keycloak identity provider.
Step 5: Configure OIDC endpoints in Keycloak
You can configure the endpoints in either of the following ways.
Option A: Discovery
|
Keycloak field |
Value |
|---|---|
|
Use discovery endpoint |
On |
|
Discovery endpoint |
|
|
Client authentication |
Client secret sent as HTTP Basic authentication |
|
Client ID |
Application (Client) ID from the Entra ID OIDC application |
|
Client Secret |
Copy the secret Value from Certificates & secrets. |
|
Client assertion signature algorithm |
Algorithm not specified |
Option B: Manual endpoint configuration
Use the Authority URL from Entra ID and build the Keycloak endpoint values as follows:
Authorization URL = <AUTHORITY_URL>/oauth2/v2.0/authorize
Token URL = <AUTHORITY_URL>/oauth2/v2.0/token
User Info URL = https://graph.microsoft.com/oidc/userinfo
Issuer = <AUTHORITY_URL>/v2.0
JWKS URL = <AUTHORITY_URL>/discovery/v2.0/keys
Do not populate the logout URL for Entra ID. Doing so signs the user out of Microsoft entirely, not just Keycloak, and may also sign them out of other applications using the same credentials.
Step 6: Complete the Keycloak configuration
-
Back in Keycloak, enter the endpoint values from Step 5.
-
Turn Validate Signature on.
-
In Entra ID, go to Certificates & secrets → New client secret.
-
For Client ID, copy the Application (client) ID from the app Overview. Do not use the secret ID.
-
For Client Secret, copy the secret Value from Certificates & secrets.
-
Enter the Client ID and Client Secret in Keycloak.
-
Click Add.
Step 7: Review advanced Keycloak settings
After the Entra identity provider is added, review the advanced settings in Keycloak. Configure only the following fields unless your tenant requires something different.
-
Enable send id_token_hint in logout requests.
-
Turn on Disable User Info.
-
Set Scopes to
openid profile email.
-
Turn on Trust Email.
-
Set First login flow override to Apporto first broker login. This flow is provisioned with the realm.
-
Click Save.
Step 8: Add identity provider mappers
Add the required mappers to ensure Keycloak receives and stores the correct username and email values.
-
In Keycloak, go to Identity Providers → Your Entra ID Provider → Mappers.
-
Click Add mapper.
-
Create the recommended mappers listed below.
|
User field |
Mapper type |
Claim |
Keycloak user attribute name |
|---|---|---|---|
|
Username Mapper |
Username mapper |
|
Username |
|
Email Attribute |
Attribute Importer |
|
|
|
First Name Mapper |
Attribute Importer |
|
|
|
Last Name Mapper |
Attribute Importer |
|
|
Username mapper
Entra ID does not send the email in a form that Keycloak can reliably use as the username. Map the preferred username instead.
-
Mapper type: username mapper
-
Template:
${CLAIM.preferred_username}
Email mapper
Use an Attribute Importer because Entra sends the email value as upn.
-
Mapper type: Attribute Importer
-
Claim:
upn -
Attribute name:
email
First Name Mapper
-
Map the
given_nameclaim to the KeycloakfirstNameuser attribute.
Last Name Mapper
-
Map the
family_nameclaim to the KeycloaklastNameuser attribute.
Step 9: Optional group and role mapping in Entra ID
Complete this section only if Entra groups or app roles will be used for authorization.
Group mapping
If you plan to sync groups using the Apporto group mapper, grant Keycloak permission to read groups from Microsoft Graph.
-
In Entra ID, go to API permissions → Add a permission.
-
Choose Microsoft Graph → Application permissions → Group.Read.All.
-
Click Grant admin consent.
-
Go to Token configuration → Add groups claim.
-
Select Group ID for all group types.
-
If the tenant has a very large number of groups, restrict the claim to groups assigned to the app. Otherwise, keep the default.
-
Click Add.
Role mapping
If your environment uses direct role claims instead of groups, define App Roles on the app registration, then assign users or groups to those roles on the enterprise application. Entra emits the assigned roles in the roles claim automatically.
Supported role names are:
-
administrator -
sub-admin -
faculty -
tech-support
msp and super-admin are Apporto-internal and cannot be assigned from an identity provider.
Step 10: Optional group and role mapping in Keycloak
Complete this section only if Entra sends groups or roles in the token.
Group mapping
If Entra sends group memberships, configure Keycloak to map the incoming group claim according to the tenant’s Apporto group mapping requirements.
Creating an Entra group alone is not enough. The group must be included in the token before Keycloak can map it.
Role mapping
You can map a role from Entra ID to a role in your Apporto NextGen tenant. NextGen recognizes these role names: administrator, sub-admin, faculty, and tech-support.
Prerequisite: role mapping takes effect only when Allow SSO to override locally-assigned roles is enabled on Setup → Identity Management in Apporto. While it is off by default, NextGen keeps each user’s locally assigned role and ignores roles sent by Entra ID.
Manage each user’s role in one place, either Entra ID or NextGen, not both. When Entra sends a role it is used. If it does not send one for a user, the role assigned manually in NextGen applies.
-
Confirm the target role exists as a client role on your tenant’s OIDC client in Clients → your tenant client → Roles, named exactly one of the role names above.
-
In Entra ID, define App Roles on the app registration, then assign users or groups to them on the enterprise application. Entra emits the assigned roles in the
rolesclaim automatically. -
On the Entra identity provider in Keycloak, go to Mappers → Add mapper and choose Claim to Role.
|
Setting |
Value |
|---|---|
|
Claim |
|
|
Claim Value |
The Entra app-role value that should grant it, for example |
|
Role |
The client role on your tenant client, for example |
|
Sync Mode Override |
|
Use Advanced Claim to Role for multiple values or pattern matching.
Do not enable Lightweight Access Tokens on the tenant client. The role is delivered under resource_access.{client}.roles, which lightweight tokens strip.
For the full role model, including SAML providers, LDAP/AD group-to-role assignment, and group syncing, see Single Sign-On (SSO) with Keycloak.
Step 11: Test the configuration
-
Open the Apporto NextGen sign-in flow for the configured tenant.
-
Choose the Microsoft Entra identity provider option if prompted.
-
Sign in with a user allowed to access the Entra application.
-
Confirm Entra redirects the browser back to the Keycloak broker endpoint successfully.
-
Confirm the user profile includes the expected username and email address.
-
If groups or roles are configured, confirm the expected Keycloak or Apporto role is applied.
Troubleshooting
|
Issue |
What to check |
|---|---|
|
Page not found or invalid redirect |
The Entra Redirect URI must exactly match the Keycloak Redirect URI, including the broker alias. |
|
Invalid issuer or endpoint error |
Confirm the v2.0 endpoints and issuer are used consistently. |
|
Invalid signature |
Confirm Validate Signature is enabled and Keycloak can access the current Entra signing keys. |
|
Missing email address |
The Entra token must include the expected |
|
User cannot access the application |
Confirm the user is allowed to access the Entra enterprise application and the app registration is configured for the correct tenant. |
|
Group is not in the token |
Entra group membership alone may not emit a group claim. Configure the groups claim in the app registration token configuration. |
|
Group or role mapping does not work |
The token claim name and value in Keycloak must exactly match the values sent by Entra ID. |
|
Role not applied in Apporto |
Confirm Allow SSO to override locally-assigned roles is enabled if roles should be managed by Entra ID. |
Final checklist
- OpenID Connect v1.0 identity provider created in Keycloak
- Provider alias added without spaces
- Keycloak Redirect URI copied to the Entra app registration
- Entra app registration created as a single-tenant Web application
- ID token claims configured for UPN and email
- Endpoint values collected from Entra ID
- OIDC endpoints configured in Keycloak
- Client ID and client secret added to Keycloak
- Optional group claims configured if group mapping is required
- Advanced Keycloak settings reviewed and saved
- Username and email mappers created in Keycloak
- Optional group or role mappers created, if required
- Sign-in tested successfully
The Microsoft Entra OpenID Connect identity provider is configured when users can sign in to Apporto NextGen through Entra ID and receive the expected profile and authorization values.