AKS-managed Azure Active Directory integration

AKS-managed Azure AD integration is designed to simplify the Azure AD integration experience, where users were previously required to create a client app, a server app, and required the Azure AD tenant to grant Directory Read permissions. In the new version, the AKS resource provider manages the client and server apps for you.

Azure AD authentication overview

Cluster administrators can configure Kubernetes role-based access control (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 on the Azure Active Directory integration concepts documentation.

Region availability

AKS-managed Azure Active Directory integration is available in public regions where AKS is supported.

  • Azure Government isn't currently supported.
  • Azure China 21Vianet isn't currently supported.

Limitations

  • AKS-managed Azure AD integration can't be disabled
  • non-RBAC enabled clusters aren't supported for AKS-managed Azue AD integration
  • Changing the Azure AD tenant associated with AKS-managed Azure AD integration isn't supported

Prerequisites

  • The Azure CLI version 2.11.0 or later
  • Kubectl with a minimum version of 1.18.1 or kubelogin
  • If you are using helm, minimum version of helm 3.3.

Important

You must use Kubectl with a minimum version of 1.18.1 or kubelogin. If you don't use the correct version, you will notice authentication issues.

To install kubectl and kubelogin, use the following commands:

sudo az aks install-cli
kubectl version --client
kubelogin --version

Use these instructions for other operating systems.

Before you begin

For your cluster, you need an Azure AD group. This group is needed as admin group for the cluster to grant cluster admin permissions. You can use an existing Azure AD group, or create a new one. Record the object ID of your Azure AD group.

# List existing groups in the directory
az ad group list --filter "displayname eq '<group-name>'" -o table

To create a new Azure AD group for your cluster administrators, use the following command:

# Create an Azure AD group
az ad group create --display-name myAKSAdminGroup --mail-nickname myAKSAdminGroup

Create an AKS cluster with Azure AD enabled

Create an AKS cluster by using the following CLI commands.

Create an Azure resource group:

# Create an Azure resource group
az group create --name myResourceGroup --location centralus

Create an AKS cluster, and enable administration access for your Azure AD group

# Create an AKS-managed Azure AD cluster
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"
  }

Once the cluster is created, you can start accessing it.

Access an Azure AD enabled cluster

You'll need the Azure Kubernetes Service Cluster User built-in role to do the following steps.

Get the user credentials to access the cluster:

 az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

Follow the instructions to sign in.

Use the kubectl get nodes command to view nodes in the cluster:

kubectl get nodes

NAME                       STATUS   ROLES   AGE    VERSION
aks-nodepool1-15306047-0   Ready    agent   102m   v1.15.10
aks-nodepool1-15306047-1   Ready    agent   102m   v1.15.10
aks-nodepool1-15306047-2   Ready    agent   102m   v1.15.10

Configure Azure role-based access control (Azure RBAC) to configure additional security groups for your clusters.

Troubleshooting access issues with Azure AD

Important

The steps described below are bypassing 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 obtain the admin credentials to access the cluster directly.

To do these steps, you'll need to have access to the Azure Kubernetes Service Cluster Admin built-in role.

az aks get-credentials --resource-group myResourceGroup --name myManagedCluster --admin

Enable AKS-managed Azure AD Integration on your existing cluster

You can enable AKS-managed Azure AD Integration on your existing RBAC enabled cluster. Ensure 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> [--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"
  }

Download user credentials again to access your cluster by following the steps here.

Upgrading to AKS-managed Azure AD Integration

If your cluster uses legacy Azure AD integration, you can upgrade to AKS-managed Azure AD Integration.

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"
  }

If you want to access the cluster, follow the steps here.

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 access the cluster with non-interactive service principal sign-in.

Next steps