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 orkubelogin
.- 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
- 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"
}
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.
- 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 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 andproperties.disableLocalAccounts
set totrue
, 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:
- In the Azure portal, navigate to the Azure Active Directory page.
- From the left-hand pane, select Enterprise applications.
- On the Enterprise applications page, from the left-hand pane select Conditional Access.
- On the Conditional Access page, from the left-hand pane select Policies and then select New policy.
- Enter a name for the policy, for example aks-policy.
- 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.
- Under Cloud apps or actions > Include, select Select apps. Search for Azure Kubernetes Service and then select Azure Kubernetes Service AAD Server.
- Under Access controls > Grant, select Grant access, Require device to be marked as compliant, and select Select.
- Confirm your settings and set Enable policy to On.
- 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.
To get the user credentials to access the cluster, run the following command:
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
Follow the instructions to sign in.
View nodes in the cluster with the
kubectl get nodes
command:kubectl get nodes
In the Azure portal, navigate to Azure Active Directory. From the left-hand pane select Enterprise applications, and then under Activity select Sign-ins.
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:
- In the Azure portal, navigate to Azure Active Directory.
- 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>
. - From the left-hand pane, under Manage, select Groups and then select New group.
- 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.
- 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>
. - 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>
- In the Azure portal, select Activity from the left-hand pane. Select Privileged Access (Preview) and then select Enable Privileged Access.
- To grant access, select Add assignments.
- 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.
- 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
- Integrate your AKS cluster with Azure RBAC.
- 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>
- 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.
Feedback
Submit and view feedback for