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.

Azure AD authentication overview

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 is not supported.
• Clusters without Kubernetes RBAC enabled aren't supported with AKS-managed Azure AD integration.

Prerequisites

Before getting started, make sure you have the following prerequisites:

• Azure CLI version 2.29.0 or later.
• kubectl, with a minimum version of 1.18.1 or kubelogin.
• If you're using helm, you need a minimum version of helm 3.3.

Important

You must use 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 1 version. You'll experience authentication issues if you don't use the correct version.

Use the following commands to install kubectl and kubelogin:

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

Use these instructions for other operating systems.

Before you begin

You need an Azure AD group for your cluster. This group will be registered as an admin group on the cluster to grant cluster admin permissions. You can use an existing Azure AD group or create a new one. Make sure to 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

Use the following command to create a new Azure AD group for your cluster administrators:

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

Create an AKS cluster with Azure AD enabled

1. Create an Azure resource group.

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

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

Access an Azure AD enabled cluster

Before you access the cluster using an Azure AD defined group, you'll need the Azure Kubernetes Service Cluster User built-in role.

1. Get the user credentials to access the cluster.

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

1. Follow the instructions to sign in.

2. 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

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

Troubleshooting access issues with 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 obtain the admin credentials to access the cluster directly.

To do these steps, you 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 Kubernetes RBAC enabled cluster. 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> [--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 by running the following 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"
  }

In order to access the cluster, follow the steps here to update kubeconfig.

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.

Disable local accounts

When you deploy an AKS cluster, local accounts are enabled by default. Even when enabling RBAC or Azure AD integration, --admin access still exists as a non-auditable backdoor option. You can disable local accounts using the parameter disable-local-accounts. The properties.disableLocalAccounts field has been added to the managed cluster API to indicate whether the feature is enabled or not on the cluster.

Note

• On clusters with Azure AD integration enabled, users assigned to an Azure AD administrators group specified by aad-admin-group-object-ids can still gain access using non-administrator credentials. On clusters without Azure AD integration enabled and properties.disableLocalAccounts set to true, any attempt to authenticate with user or admin credentials will fail.

• After disabling local user accounts on an existing AKS cluster where users might have authenticated with local accounts, the administrator must rotate the cluster certificates to revoke certificates they might have had access to. If this is a new cluster, no action is required.

Create a new cluster without local accounts

To create a new AKS cluster without any local accounts, use the az aks create command with the disable-local-accounts flag.

az aks create -g <resource-group> -n <cluster-name> --enable-aad --aad-admin-group-object-ids <aad-group-id> --disable-local-accounts

In the output, confirm local accounts have been disabled by checking the field properties.disableLocalAccounts is set to true.

"properties": {
    ...
    "disableLocalAccounts": true,
    ...
}

Attempting to get admin credentials will fail with an error message indicating the feature is preventing access:

az aks get-credentials --resource-group <resource-group> --name <cluster-name> --admin

Operation failed with status: 'Bad Request'. Details: Getting static credential isn't allowed because this cluster is set to disable local accounts.

Disable local accounts on an existing cluster

To disable local accounts on an existing AKS cluster, use the az aks update command with the disable-local-accounts parameter.

az aks update -g <resource-group> -n <cluster-name> --enable-aad --aad-admin-group-object-ids <aad-group-id> --disable-local-accounts

In the output, confirm local accounts have been disabled by checking the field properties.disableLocalAccounts is set to true.

"properties": {
    ...
    "disableLocalAccounts": true,
    ...
}

Attempting to get admin credentials will fail with an error message indicating the feature is preventing access:

az aks get-credentials --resource-group <resource-group> --name <cluster-name> --admin

Operation failed with status: 'Bad Request'. Details: Getting static credential isn't allowed because this cluster is set to disable local accounts.

Re-enable local accounts on an existing cluster

AKS supports enabling a disabled local account on an existing cluster with the enable-local parameter.

az aks update -g <resource-group> -n <cluster-name> --enable-aad --aad-admin-group-object-ids <aad-group-id> --enable-local

In the output, confirm local accounts have been re-enabled by checking the field properties.disableLocalAccounts is set to false.

"properties": {
    ...
    "disableLocalAccounts": false,
    ...
}

Attempting to get admin credentials will succeed:

az aks get-credentials --resource-group <resource-group> --name <cluster-name> --admin

Merged "<cluster-name>-admin" as current context in C:\Users\<username>\.kube\config

Use Conditional Access with Azure AD and AKS

When integrating Azure AD with your AKS cluster, you can also use Conditional Access to control access to your cluster.

Note

Azure AD Conditional Access is an Azure AD Premium capability.

Complete the following steps to create an example Conditional Access policy to use with AKS:

1. In the Azure portal, navigate to the Azure Active Directory page.
2. From the left-hand pane, select Enterprise applications.
3. On the Enterprise applications page, from the left-hand pane select Conditional Access.
4. On the Conditional Access page, from the left-hand pane select Policies and then select New policy.
5. Enter a name for the policy, for example aks-policy.
6. Under Assignments select Users and groups. Choose your users and groups you want to apply the policy to. In this example, choose the same Azure AD group that has administrator access to your cluster.
7. Under Cloud apps or actions > Include, select Select apps. Search for Azure Kubernetes Service and then select Azure Kubernetes Service AAD Server.
8. Under Access controls > Grant, select Grant access, Require device to be marked as compliant, and select Select.
9. Confirm your settings and set Enable policy to On.
10. Select Create to create and enable your policy.

After creating the Conditional Access policy, perform the following steps to verify it has been successfully listed.

11. To get the user credentials to access the cluster, run the following command:

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

12. Follow the instructions to sign in.

13. View nodes in the cluster with the kubectl get nodes command:

    kubectl get nodes
    

14. In the Azure portal, navigate to Azure Active Directory. From the left-hand pane select Enterprise applications, and then under Activity select Sign-ins.

15. Notice in the top of the results an event with a status of Failed, and under the Conditional Access column, a status of Success. Select the event and then select Conditional Access tab. Notice your Conditional Access policy is listed.

Configure just-in-time cluster access with Azure AD and AKS

Another option for cluster access control is to use Privileged Identity Management (PIM) for just-in-time requests.

Note

PIM is an Azure AD Premium capability requiring a Premium P2 SKU. For more on Azure AD SKUs, see the pricing guide.

To integrate just-in-time access requests with an AKS cluster using AKS-managed Azure AD integration, complete the following steps:

1. In the Azure portal, navigate to Azure Active Directory.
2. Select Properties. Scroll down to the Tenant ID field. Your tenant ID will be in the box. Note this value as it's referenced later in a step as <tenant-id>.
3. From the left-hand pane, under Manage, select Groups and then select New group.
4. Verify the group type Security is selected and specify a group name, such as myJITGroup. Under the option Azure AD roles can be assigned to this group (Preview), select Yes and then select Create.
5. On the Groups page, select the group you just created and note the Object ID. This will be referenced in a later step as <object-id>.
6. Create the AKS cluster with AKS-managed Azure AD integration using the az aks create command with the --aad-admin-group-objects-ids and --aad-tenant-id parameters and include the values noted in the steps earlier.

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

7. In the Azure portal, select Activity from the left-hand pane. Select Privileged Access (Preview) and then select Enable Privileged Access.
8. To grant access, select Add assignments.
9. From the Select role drop-down list, select the users and groups you want to grant cluster access. These assignments can be modified at any time by a group administrator. Then select Next.
10. Under Assignment type, select Active and then specify the desired duration. Provide a justification and then select Assign. For more information about assignment types, see Assign eligibility for a privileged access group (preview) in Privileged Identity Management.

Once the assignments have been made, verify just-in-time access is working by accessing the cluster. For example:

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

Follow the steps to sign in.

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

kubectl get nodes

Note the authentication requirement and follow the steps to authenticate. If successful, you should see an output similar to the following output:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code AAAAAAAAA to authenticate.
NAME                                STATUS   ROLES   AGE     VERSION
aks-nodepool1-61156405-vmss000000   Ready    agent   6m36s   v1.18.14
aks-nodepool1-61156405-vmss000001   Ready    agent   6m42s   v1.18.14
aks-nodepool1-61156405-vmss000002   Ready    agent   6m33s   v1.18.14

Apply Just-in-Time access at the namespace level

1. Integrate your AKS cluster with Azure RBAC.
2. Associate the group you want to integrate with Just-in-Time access with a namespace in the cluster through role assignment.

az role assignment create --role "Azure Kubernetes Service RBAC Reader" --assignee <AAD-ENTITY-ID> --scope $AKS_ID/namespaces/<namespace-name>

1. Associate the group you configured at the namespace level with PIM to complete the configuration.

Troubleshooting

If kubectl get nodes returns an error similar to the following error:

Error from server (Forbidden): nodes is forbidden: User "aaaa11111-11aa-aa11-a1a1-111111aaaaa" cannot list resource "nodes" in API group "" at the cluster scope

Make sure the admin of the security group has given your account an Active assignment.

Next steps

• Learn about Azure RBAC integration for Kubernetes Authorization.
• Learn about Azure AD integration with Kubernetes RBAC.
• Use kubelogin to access features for Azure authentication that aren't available in kubectl.
• Learn more about AKS and Kubernetes identity concepts.
• Use Azure Resource Manager (ARM) templates to create AKS-managed Azure AD enabled clusters.