Cloud Experts Documentation

Configuring Microsoft Entra ID to emit group names

This content is authored by Red Hat experts, but has not yet been tested on every supported configuration.

In this guide, we will configure an existing Microsoft Entra ID (formerly Azure Active Directory) identity provider to emit the group name instead of the group ID for optional group claims. This will allow you to reference group names in your role bindings instead of the group ID.

The ability to emit group names instead of group IDsexternal link (opens in new tab) is a preview feature made available by Microsoft and is subject to their terms and conditions around preview features of their services.

Prerequisites

Before we begin, ensure that you have properly configured Microsoft Entra ID as an identity provider in your cluster following the guide specific to your platform:

In addition, ensure that you have the necessary permissions to modify the Microsoft Entra ID app registration in the Azure Portal.

Microsoft Entra ID Free is not able to emit group names instead of group IDs.

Procedure

  1. Login to the Microsoft Azure portalexternal link (opens in new tab) and navigate to the Microsoft Entra ID service, then click on the App registrations blade. Azure Portal - Microsoft Entra ID with arrow pointing at the App registrations menu item

  2. Locate your App registration and click on it.

  3. Expand the Manage sidebar menu, and click on the Manifest blade. Azure Portal - App registration overview page with arrow pointing at the Manage sidebar menu and the Manifest blade

  4. Download the Microsoft Graph App Manifest to keep as a backup, just in case. Azure Portal - App registration manifest with arrow pointing at the Download button

  5. Locate the setting groupMembershipClaims and ensure it is set to ApplicationGroup. This option includes only groups that are assigned to the application.

    Before changing this value, ensure that the groups you wish to include in your claims are attached to your Microsoft Entra ID application. Failure to do so may result in unexpected behavior including the removal of group memberships used for role bindings. For more information on how to add groups to your Microsoft Entra ID application, see the Microsoft documentationexternal link (opens in new tab) .

    Azure Portal - App registration manifest with groupMembershipClaims value highlighted
  6. Locate the groups claims under the optionalClaims section of the manifest. There should be three, one under accessToken, one under idToken, and one under saml2Token. Edit the additionalProperties field of the groups claims for the idToken only. You will change the additionalProperties field to look like this:

    ...
        "optionalClaims": {
            "idToken": [
                {
                    "name": "groups",
                    "source": null,
                    "essential": false,
                    "additionalProperties": [
                        "sam_account_name",
                        "cloud_displayname"
                    ]
                }
            ],
    ...
    
  7. Save your changes. Azure Portal - App registration manifest with arrow pointing at the Save button

  8. If you are already logged into the OpenShift Web Console, logout. Once you are logged out of the cluster, log back in using the Microsoft Entra ID. You should now see group membership populated with group names instead of group IDs. OpenShift Web Console - Groups page demonstrating Entra ID created groups

    You can see these groups were synced from Microsoft Entra ID by running the oc get groups -o yaml command. Your output will look something like this (note the oauth.openshift.io annotations):

    apiVersion: v1
    items:
    - apiVersion: user.openshift.io/v1
      kind: Group
      metadata:
        annotations:
          oauth.openshift.io/generated: "true"
          oauth.openshift.io/idp.EntraID: synced
        name: group-1
      users:
      - michael@demo
    - apiVersion: user.openshift.io/v1
      kind: Group
      metadata:
        annotations:
          oauth.openshift.io/generated: "true"
          oauth.openshift.io/idp.EntraID: synced
        name: group-2
      users:
      - michael@demo
    kind: List
    metadata:
      resourceVersion: ""
    

Congratulations! You are now able to reference your group names in role bindings instead of group IDs.

Interested in contributing to these docs?

Collaboration drives progress. Help improve our documentation The Red Hat Way.

Red Hat logo LinkedIn YouTube Facebook Twitter

Products

Tools

Try, buy & sell

Communicate

About Red Hat

We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Subscribe to our newsletter, Red Hat Shares

Sign up now
© 2023 Red Hat, Inc.