Edit

Share via

Enable Microsoft Entra authentication for Kubernetes clusters

  • Article

Applies to: AKS on Azure Local, version 23H2

AKS enabled by Azure Arc simplifies the authentication process with Microsoft Entra ID integration. For authorization, cluster administrators can configure Kubernetes role-based access control (Kubernetes RBAC) or Azure role-based access control (Azure RBAC) based on the directory group membership of the Microsoft Entra ID integration.

Microsoft Entra authentication is provided to AKS Arc clusters with OpenID Connect. OpenID Connect is an identity layer built on top of the OAuth 2.0 protocol. For more information about OpenID Connect, see the OpenID Connect documentation. For more information about the Microsoft Entra integration flow, see the Microsoft Entra documentation.

This article describes how to enable and use Microsoft Entra ID authentication for Kubernetes clusters.

Before you begin

  • This configuration requires that you have a Microsoft Entra group for your cluster. This group is registered as an admin group on the cluster to grant admin permissions. If you don't have an existing Microsoft Entra group, you can create one using the az ad group create command.
  • To create or update a Kubernetes cluster, you need the Azure Kubernetes Service Arc Contributor role.
  • To access the Kubernetes cluster directly using the az aksarc get-credentials command and download the kubeconfig file, you need the Microsoft.HybridContainerService/provisionedClusterInstances/listUserKubeconfig/action, which is included in the Azure Kubernetes Service Arc Cluster User role permission.
  • Once your Microsoft Entra group is enabled with admin access to your AKS cluster, this Microsoft Entra group can interact with Kubernetes clusters. You must install kubectl and kubelogin.
  • Integration can't be disabled once added. You can still use az aksarc update to update the aad-admin-group-object-ids if needed.

Enable Microsoft Entra authentication for Kubernetes cluster

Create a new cluster with Microsoft Entra authentication

  1. Create an Azure resource group using the az group create command:

    az group create --name $resource_group --location centralus

  2. Create an AKS Arc cluster and enable admin access for your Microsoft Entra group using the --aad-admin-group-object-ids parameter in the az aksarc create command:

    az aksarc create -n $aks_cluster_name -g $resource_group --custom-location $customlocationID --vnet-ids $logicnetId --aad-admin-group-object-ids $aadgroupID --generate-ssh-keys

Use an existing cluster with Microsoft Entra authentication

Enable Microsoft Entra authentication on your existing Kubernetes cluster using the --aad-admin-group-object-ids parameter in the az aksarc update command. Make sure to set your admin group to retain access on your cluster:

az aksarc update -n $aks_cluster_name -g $resource_group --aad-admin-group-object-ids $aadgroupID

Access your Microsoft Entra-enabled cluster

  1. Get the user credentials to access your cluster using the az aksarc get-credentials command. You need the Microsoft.HybridContainerService/provisionedClusterInstances/listUserKubeconfig/action, which is included in the Azure Kubernetes Service Arc Cluster User role permission:

    az aksarc get-credentials --resource-group $resource_group --name $aks_cluster_name

  2. View the nodes in the cluster with the kubectl get nodes command and follow the instructions to sign in. You need to be in the Microsoft Entra ID group specified with the AKS cluster when you pass the --aad-admin-group-object-ids $aadgroupID parameter:

    kubectl get nodes

Next steps