AKS-managed Azure Active Directory integration

AKS-managed Azure Active Directory (Azure AD) integration simplifies the Azure AD integration process. Previously, you were required to create a client and server app, and the Azure AD tenant had to grant Directory Read permissions. Now, the AKS resource provider manages the client and server apps for you.

Cluster administrators can configure Kubernetes role-based access control (Kubernetes RBAC) based on a user's identity or directory group membership. Azure AD authentication is provided to AKS clusters with OpenID Connect. OpenID Connect is an identity layer built on top of the OAuth 2.0 protocol. For more information on OpenID Connect, see the Open ID connect documentation.

Learn more about the Azure AD integration flow in the Azure AD documentation.

Limitations

  • AKS-managed Azure AD integration can't be disabled.
  • Changing an AKS-managed Azure AD integrated cluster to legacy Azure AD isn't supported.
  • Clusters without Kubernetes RBAC enabled aren't supported with AKS-managed Azure AD integration.

Before you begin

  • Make sure you have Azure CLI version 2.29.0 or later is installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
  • You need kubectl with a minimum version of 1.18.1 or kubelogin. The difference between the minor versions of Kubernetes and kubectl shouldn't be more than one version. You'll experience authentication issues if you don't use the correct version.
  • If you're using helm, you need a minimum version of helm 3.3.
  • This configuration requires you have an Azure AD 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 Azure AD group, you can create one using the az ad group create command.

Enable AKS-managed Azure AD integration on your AKS cluster

Create a new cluster

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

    az group create --name myResourceGroup --location centralus
    
  2. Create an AKS cluster and enable administration access for your Azure AD group using the az aks create command.

    az aks create -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]
    

    A successful creation of an AKS-managed Azure AD cluster has the following section in the response body:

    "AADProfile": {
        "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
        ],
        "clientAppId": null,
        "managed": true,
        "serverAppId": null,
        "serverAppSecret": null,
        "tenantId": "72f9****-****-****-****-****d011db47"
    }
    

Use an existing cluster

Enable AKS-managed Azure AD integration on your existing Kubernetes RBAC enabled cluster using the az aks update command. Make sure to set your admin group to keep access on your cluster.

az aks update -g MyResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]

A successful activation of an AKS-managed Azure AD cluster has the following section in the response body:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Upgrade a legacy Azure AD cluster to AKS-managed Azure AD integration

If your cluster uses legacy Azure AD integration, you can upgrade to AKS-managed Azure AD integration with no downtime using the az aks update command.

az aks update -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

A successful migration of an AKS-managed Azure AD cluster has the following section in the response body:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Access your AKS-managed Azure AD enabled cluster

  1. Get the user credentials to access your cluster using the az aks get-credentials command.

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
    
  2. Follow the instructions to sign in.

  3. View the nodes in the cluster using the kubectl get nodes command.

    kubectl get nodes
    

Non-interactive sign-in with kubelogin

There are some non-interactive scenarios, such as continuous integration pipelines, that aren't currently available with kubectl. You can use kubelogin to connect to the cluster with a non-interactive service principal credential.

Azure AD integrated clusters using a Kubernetes version newer than version 1.24 automatically use the kubelogin format. Starting with Kubernetes version 1.24, the default format of the clusterUser credential for Azure AD clusters is exec, which requires kubelogin binary in the execution PATH.

  • When getting the clusterUser credential, you can use the format query parameter to overwrite the default behavior. You can set the value to azure to use the original kubeconfig format:

    az aks get-credentials --format azure
    
  • If your Azure AD integrated cluster uses Kubernetes version 1.24 or lower, you need to manually convert the kubeconfig format.

    export KUBECONFIG=/path/to/kubeconfig
    kubelogin convert-kubeconfig
    

Note

If you receive the message error: The Azure auth plugin has been removed., you need to run the command kubelogin convert-kubeconfig to convert the kubeconfig format manually.

Troubleshoot access issues with AKS-managed Azure AD

Important

The steps described in this section bypass the normal Azure AD group authentication. Use them only in an emergency.

If you're permanently blocked by not having access to a valid Azure AD group with access to your cluster, you can still get admin credentials to directly access the cluster. You need to have access to the Azure Kubernetes Service Cluster Admin built-in role.

Next steps