Integrate Azure Active Directory with Azure Kubernetes Service using the Azure CLI (legacy)
Warning
**The feature described in this document, Azure AD Integration (legacy), will be deprecated on June 1st, 2023.
AKS has a new improved AKS-managed Azure AD experience that doesn't require you to manage server or client application. If you want to migrate follow the instructions here.
Azure Kubernetes Service (AKS) can be configured to use Azure Active Directory (AD) for user authentication. In this configuration, you can log into an AKS cluster using an Azure AD authentication token. Cluster operators can also configure Kubernetes role-based access control (Kubernetes RBAC) based on a user's identity or directory group membership.
This article shows you how to create the required Azure AD components, then deploy an Azure AD-enabled cluster and create a basic Kubernetes role in the AKS cluster.
For the complete sample script used in this article, see [Azure CLI samples - AKS integration with Azure AD][complete-script].
The following limitations apply:
- Azure AD can only be enabled on Kubernetes RBAC-enabled cluster.
- Azure AD legacy integration can only be enabled during cluster creation.
Before you begin
You need the Azure CLI version 2.0.61 or later installed and configured. Run az --version
to find the version. If you need to install or upgrade, see Install Azure CLI.
Go to https://shell.azure.com to open Cloud Shell in your browser.
For consistency and to help run the commands in this article, create a variable for your desired AKS cluster name. The following example uses the name myakscluster:
aksname="myakscluster"
Azure AD authentication overview
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.
From inside of the Kubernetes cluster, Webhook Token Authentication is used to verify authentication tokens. Webhook token authentication is configured and managed as part of the AKS cluster. For more information on Webhook token authentication, see the webhook authentication documentation.
Note
When configuring Azure AD for AKS authentication, two Azure AD applications are configured. This operation must be completed by an Azure tenant administrator.
Create Azure AD server component
To integrate with AKS, you create and use an Azure AD application that acts as an endpoint for the identity requests. The first Azure AD application you need gets Azure AD group membership for a user.
Create the server application component using the az ad app create command, then update the group membership claims using the az ad app update command. The following example uses the aksname variable defined in the Before you begin section, and creates a variable
# Create the Azure AD application
serverApplicationId=$(az ad app create \
--display-name "${aksname}Server" \
--identifier-uris "https://${aksname}Server" \
--query appId -o tsv)
# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All
Now create a service principal for the server app using the az ad sp create command. This service principal is used to authenticate itself within the Azure platform. Then, get the service principal secret using the az ad sp credential reset command and assign to the variable named serverApplicationSecret for use in one of the following steps:
# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId
# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
--name $serverApplicationId \
--credential-description "AKSPassword" \
--query password -o tsv)
The Azure AD service principal needs permissions to perform the following actions:
- Read directory data
- Sign in and read user profile
Assign these permissions using the az ad app permission add command:
az ad app permission add \
--id $serverApplicationId \
--api 00000003-0000-0000-c000-000000000000 \
--api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role
Finally, grant the permissions assigned in the previous step for the server application using the az ad app permission grant command. This step fails if the current account is not a tenant admin. You also need to add permissions for Azure AD application to request information that may otherwise require administrative consent using the az ad app permission admin-consent:
az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id $serverApplicationId
Create Azure AD client component
The second Azure AD application is used when a user logs to the AKS cluster with the Kubernetes CLI (kubectl
). This client application takes the authentication request from the user and verifies their credentials and permissions. Create the Azure AD app for the client component using the az ad app create command:
clientApplicationId=$(az ad app create \
--display-name "${aksname}Client" \
--native-app \
--reply-urls "https://${aksname}Client" \
--query appId -o tsv)
Create a service principal for the client application using the az ad sp create command:
az ad sp create --id $clientApplicationId
Get the oAuth2 ID for the server app to allow the authentication flow between the two app components using the az ad app show command. This oAuth2 ID is used in the next step.
oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)
Add the permissions for the client application and server application components to use the oAuth2 communication flow using the az ad app permission add command. Then, grant permissions for the client application to communication with the server application using the az ad app permission grant command:
az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId
Deploy the cluster
With the two Azure AD applications created, now create the AKS cluster itself. First, create a resource group using the az group create command. The following example creates the resource group in the EastUS region:
Create a resource group for the cluster:
az group create --name myResourceGroup --location EastUS
Get the tenant ID of your Azure subscription using the az account show command. Then, create the AKS cluster using the az aks create command. The command to create the AKS cluster provides the server and client application IDs, the server application service principal secret, and your tenant ID:
tenantId=$(az account show --query tenantId -o tsv)
az aks create \
--resource-group myResourceGroup \
--name $aksname \
--node-count 1 \
--generate-ssh-keys \
--aad-server-app-id $serverApplicationId \
--aad-server-app-secret $serverApplicationSecret \
--aad-client-app-id $clientApplicationId \
--aad-tenant-id $tenantId
Finally, get the cluster admin credentials using the az aks get-credentials command. In one of the following steps, you get the regular user cluster credentials to see the Azure AD authentication flow in action.
az aks get-credentials --resource-group myResourceGroup --name $aksname --admin
Create Kubernetes RBAC binding
Before an Azure Active Directory account can be used with the AKS cluster, a role binding or cluster role binding needs to be created. Roles define the permissions to grant, and bindings apply them to desired users. These assignments can be applied to a given namespace, or across the entire cluster. For more information, see Using Kubernetes RBAC authorization.
Get the user principal name (UPN) for the user currently logged in using the az ad signed-in-user show command. This user account is enabled for Azure AD integration in the next step.
az ad signed-in-user show --query userPrincipalName -o tsv
Important
If the user you grant the Kubernetes RBAC binding for is in the same Azure AD tenant, assign permissions based on the userPrincipalName. If the user is in a different Azure AD tenant, query for and use the objectId property instead.
Create a YAML manifest named basic-azure-ad-binding.yaml
and paste the following contents. On the last line, replace userPrincipalName_or_objectId with the UPN or object ID output from the previous command:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: contoso-cluster-admins
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
kind: User
name: userPrincipalName_or_objectId
Create the ClusterRoleBinding using the kubectl apply command and specify the filename of your YAML manifest:
kubectl apply -f basic-azure-ad-binding.yaml
Access cluster with Azure AD
Now let's test the integration of Azure AD authentication for the AKS cluster. Set the kubectl
config context to use regular user credentials. This context passes all authentication requests back through Azure AD.
az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing
Now use the kubectl get pods command to view pods across all namespaces:
kubectl get pods --all-namespaces
You receive a sign in prompt to authenticate using Azure AD credentials using a web browser. After you've successfully authenticated, the kubectl
command displays the pods in the AKS cluster, as shown in the following example output:
kubectl get pods --all-namespaces
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code BYMK7UXVD to authenticate.
NAMESPACE NAME READY STATUS RESTARTS AGE
kube-system coredns-754f947b4-2v75r 1/1 Running 0 23h
kube-system coredns-754f947b4-tghwh 1/1 Running 0 23h
kube-system coredns-autoscaler-6fcdb7d64-4wkvp 1/1 Running 0 23h
kube-system heapster-5fb7488d97-t5wzk 2/2 Running 0 23h
kube-system kube-proxy-2nd5m 1/1 Running 0 23h
kube-system kube-svc-redirect-swp9r 2/2 Running 0 23h
kube-system kubernetes-dashboard-847bb4ddc6-trt7m 1/1 Running 0 23h
kube-system metrics-server-7b97f9cd9-btxzz 1/1 Running 0 23h
kube-system tunnelfront-6ff887cffb-xkfmq 1/1 Running 0 23h
The authentication token received for kubectl
is cached. You are only reprompted to sign in when the token has expired or the Kubernetes config file is re-created.
If you see an authorization error message after you've successfully signed in using a web browser as in the following example output, check the following possible issues:
error: You must be logged in to the server (Unauthorized)
- You defined the appropriate object ID or UPN, depending on if the user account is in the same Azure AD tenant or not.
- The user is not a member of more than 200 groups.
- Secret defined in the application registration for server matches the value configured using
--aad-server-app-secret
- Be sure that only one version of kubectl is installed on your machine at a time. Conflicting versions can cause issues during authorization. To install the latest version, use az aks install-cli.
Next steps
For the complete script that contains the commands shown in this article, see the [Azure AD integration script in the AKS samples repo][complete-script].
To use Azure AD users and groups to control access to cluster resources, see Control access to cluster resources using Kubernetes role-based access control and Azure AD identities in AKS.
For more information about how to secure Kubernetes clusters, see Access and identity options for AKS).
For best practices on identity and resource control, see Best practices for authentication and authorization in AKS.
Feedback
Submit and view feedback for