Using Keycloak as provider for Azure AD role authorization: Part 2 map AD groups to Keycloak roles

Continuing from my previous article on this topic which covered on Azure AD SSO using Keycloak as IDP, this is the final installement which covers how Keycloak roles can be mapped with Azure AD groups and how to enable a Next JS UI extract roles from the Azure AD groups to which the login user belongs to.

Background

While implementing this solution, I found there was scarce information depitcing exact steps on how to setup Keycloak IDP to achieve this — both in Keycloak documentation and in general — so hopefully this help others who wants to achieve similar goals.

Scenario Overview

The above diagram shows the roles and responsibilities for each component / actor involved.

Assumptions

1. One has an active Azure account with email id registered
2. One has an active Keycloak setup as administrator
3. Keycloak version 24.x

Create Azure AD groups

1. Create a new group in Azure AD — “Planners Access”
2. Note down the object id of the group as it will be required to map to the correct user role

Map Azure AD Groups to App Registration

1. Now go to Enterprise Application list and find the Application Registration entry (shown how to create in the previous article)
2. Go to Users and Groups and add the group you created above.
   NOTE: If you have nested groups with hierarchy, it is advised to map to the topmost available group.

Update Azure App Reg to emit group claims

• Now we need to enable the Azure App Registration client to emit the matching group ids (to a logged user credentials) as part of the claim token.
• Go to Token Configuration and add an optional group claim for ApplicationGroup and for the group id in ID token, Access Token and SAML token

• Once the claim is added to the token config above, next we need to update the App Reg manifest so that it emits the group id as part of the token claims.
  Here update “groupMembershipClaims” to “ApplicationGroup” and save.

Create Keycloak client scope to resolve groups claim

• To accept the groups claim from Azure AD, Keycloak needs to resolve the Azure AD token where the scope is “groups”.

• To do that, go to your realm, add a new client role called “groups” and then add it your UI specific Keycloak client scopes as default scope.

Create Keycloak client specific roles

Now we need to configure the roles for the client (UI app) which is required to control the UI behavior based upon privileges.

• Go to the UI specific Keycloak client and on the Roles tab, add the new roles you need e.g. admin, planner etc.

Map Azure AD groups to Keycloak roles

Next we need to map these respective roles with respective Azure AD groups.

• Go to Identity Providers → your already created provider (Azure AD SSO) → Mappers tab
• Here add new custom claim to role mapper as below:
  NOTE: In the claim value: add the object id of the respective Azure AD group

• Select role → from the filter choose, client specific roles and select the role you added above, assign and then save.
  NOTE: Repeat this group to role mapping for all respective Azure AD groups to Keycloak roles.

Implement Keycloak adapter in Next JS UI app

• Define Keycloak specific variables in config map to instantiate Keycloak adapter

  NEXT_PUBLIC_KEYCLOAK_AUTH_URL: "<hostname>/keycloak"
  NEXT_PUBLIC_KEYCLOAK_REALM: "<keycloak realm name>"
  NEXT_PUBLIC_KEYCLOAK_CLIENT_ID: "<key cloak UI client id>"

• Implement Keycloak config

      keycloakConfig: {
        url: process.env.NEXT_PUBLIC_KEYCLOAK_AUTH_URL || '',
        realm: process.env.NEXT_PUBLIC_KEYCLOAK_REALM || '',
        clientId: process.env.NEXT_PUBLIC_KEYCLOAK_CLIENT_ID || '',
      }

• Implement login

    if (!keycloakAuth.current) {
      const keycloak = new Keycloak(pageProps.keycloakConfig);
      keycloakAuth.current = keycloak;

      const authenticated = await keycloak.init({
        onLoad: 'login-required',
        checkLoginIframe: true,
        enableLogging: true,
      });

NOTE: Any additional guidance look here: Securing Applications and Services Guide (keycloak.org)

Verify Single Sign On works

Should work :)

Verify correct roles mapped to groups retrieval

Capture the token that is returned post SSO call and parse to check if you have received the correct mapped roles assigned to your groups in Azure AD like this:

  "resource_access": {
    "<keycloak UI client id>": {
      "roles": [
        "planners"
      ]
    }

Known Issues and how to fix

User with <email/username> already exists.

Generally, this pops up, if you had a KeyCloak-Azure AD connection made and logged in a user and then you delete the KeyCloak-Azure AD connection.
This doesn’t delete the already synced/logged in users.

User needs to be deleted manually from Users tab from the panel.
Post this, you try to login the user with same email address then fresh Azure AD connection is

Happy to know and learn on how you approached this problem statement!