Use Azure role-based access control (RBAC) for Kubernetes authorization

Applies to: AKS on Azure Stack HCI 23H2

Infrastructure administrators can use Azure role-based access control (Azure RBAC) to control who can access the kubeconfig file and the permissions they have. Kubernetes operators can interact with Kubernetes clusters using the kubectl tool based on the given permissions. Azure CLI provides an easy way to get the access credentials and kubeconfig configuration file to connect to your AKS clusters using kubectl.

When you use integrated authentication between Microsoft Entra ID and AKS, you can use Microsoft Entra users, groups, or service principals as subjects in Kubernetes role-based access control (Kubernetes RBAC). This feature frees you from having to separately manage user identities and credentials for Kubernetes. However, you still must set up and manage Azure RBAC and Kubernetes RBAC separately.

This article describes how to use Azure RBAC for Kubernetes cluster authorization with Microsoft Entra ID and Azure role assignments.

For a conceptual overview, see Azure RBAC for Kubernetes Authorization for AKS enabled by Azure Arc.

Before you begin

Before you begin, make sure you have the following prerequisites:

• AKS currently supports enabling Azure RBAC only during initial deployment and Kubernetes cluster creation. You can't enable Azure RBAC after the Kubernetes cluster is created.

• Azure CLI. If you need to install or upgrade, see Install Azure CLI.

• Install the latest version of the aksarc and connectedk8s Azure CLI extension. Note that you need to run aksarc extension version 1.1.1 or later to enable Azure RBAC.

  az extension add --name aksarc
  az extension add --name connectedk8s
  

  If you already installed the aksarc extension, update the extension to the latest version:

  az extension update --name aksarc
  az extension update --name connectedk8s
  

• To interact with Kubernetes clusters, you must install kubectl and kubelogin.

• You need the following permissions to enable Azure RBAC while creating a Kubernetes cluster.

  • To create a Kubernetes cluster, you need the Azure Kubernetes Service Arc Contributor role.
  • To use the --enable-azure-rbac parameter, you need the Role-Based Access Control Administrator role for access to the Microsoft.Authorization/roleAssignments/write permission. For more information, see Azure built-in roles.
  • New role assignments can take up to five minutes to propagate and be updated by the authorization server.

Step 1: Create an Azure RBAC-enabled Kubernetes cluster

You can create an Azure RBAC-enabled Kubernetes cluster for authorization and a Microsoft Entra ID for authentication.

az aksarc create -n $aks_cluster_name -g $resource_group_name --custom-location $customlocation_ID --vnet-ids $logicnet_Id --generate-ssh-keys --control-plane-ip $controlplaneIP --enable-azure-rbac

After a few minutes, the command completes and returns JSON-formatted information about the cluster.

Step 2: Create role assignments for users to access the cluster

AKS enabled by Azure Arc provides the following built-in roles:

You can use the az role assignment create command to create role assignments.

First, get the $ARM-ID for the target cluster to which you want to assign a role.

$ARM_ID = (az connectedk8s show -g "$resource_group_name" -n $aks_cluster_name --query id -o tsv)

Then, use the az role assignment create command to assign roles to your Kubernetes cluster. You must provide the $ARM_ID from the first step and the assignee-object-id for this step. The assignee-object-id can be a Microsoft Entra ID or a service principal client ID.

The following example assigns the Azure Arc Kubernetes Viewer role to the Kubernetes cluster:

az role assignment create --role "Azure Arc Kubernetes Viewer" --assignee <assignee-object-id> --scope $ARM_ID

In this example, the scope is the Azure Resource Manager ID of the cluster. It can also be the resource group containing the Kubernetes cluster.

Create custom role definitions

You can choose to create your own role definition for use in role assignments.

The following example shows a role definition that allows a user to only read deployments. For more information, see the full list of data actions that you can use to construct a role definition. For more information about creating a custom role, see Steps to create a custom role

To create your own custom role definitions, copy the following JSON object into a file called custom-role.json. Replace the <subscription-id> placeholder with the actual subscription ID. The custom role uses one of the data actions and lets you view all deployments in the scope (cluster or namespace) where the role assignment is created.

{
    "Name": "AKS Arc Deployment Reader",
    "Description": "Lets you view all deployments in cluster/namespace.",
    "Actions": [],
    "NotActions": [],
    "DataActions": [
        "Microsoft.Kubernetes/connectedClusters/apps/deployments/read"
    ],
    "NotDataActions": [],
    "assignableScopes": [
        "/subscriptions/<YOUR SUBSCRIPTION ID>"
    ]
}

For information about custom roles and how to author them, see Azure custom roles.

Create the role definition using the az role definition create command, setting the --role-definition parameter to the deploy-view.json file you created in the previous step:

az role definition create --role-definition @deploy-view.json 

Assign the role definition to a user or other identity using the az role assignment create command:

az role assignment create --role "AKS Arc Deployment Reader" --assignee <assignee-object-id> --scope $ARM_ID

Step 3: Use Azure RBAC for Kubernetes authorization with kubectl

To access the Kubernetes cluster with the given permissions, the Kubernetes operator needs the Microsoft Entra kubeconfig, which you can get using the az aksarc get-credentials command. This command provides access to the admin-based kubeconfig, as well as a user-based kubeconfig. The admin-based kubeconfig file contains secrets and should be securely stored and rotated periodically. On the other hand, the user-based Microsoft Entra ID kubeconfig doesn't contain secrets and can be distributed to users who connect from their client machines.

To run this Azure CLI command, you must have Azure Kubernetes Service Arc Cluster User role permissions on the cluster.

az aksarc get-credentials -g "$resource_group_name" -n $aks_cluster_name --file <file-name>

Now, you can use kubectl manage your cluster. For example, you can list the nodes in your cluster using kubectl get nodes. The first time you run it, you must sign in, as shown in the following example:

kubectl get nodes

To sign in, use a web browser to open the page https://microsoft.com/devicelogin, and enter the code AAAAAAAAA to authenticate.

Use Azure RBAC for Kubernetes authorization with kubelogin

AKS provides the kubelogin plugin to help unblock additional scenarios, such as non-interactive logins, older kubectl versions, or using SSO across multiple clusters without the need to sign in to a new cluster.

You can use the kubelogin plugin by running the following command:

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

Similar to kubectl, you must log in the first time you run it, as shown in the following example:

kubectl get nodes

To sign in, use a web browser to open the page https://microsoft.com/devicelogin, and enter the code AAAAAAAAA to authenticate.

Clean up resources

Delete role assignment

# List role assignments
az role assignment list --scope $ARM_ID --query [].id -o tsv

# Delete role assignments
az role assignment delete --ids <LIST OF ASSIGNMENT IDS>

Delete role definition

az role definition delete -n "AKS Arc Deployment Reader"

Next steps

• Azure role-based access control (Azure RBAC)
• Access and identity options for AKS enabled by Azure Arc
• Create an Azure service principal with Azure CLI
• Available Azure permissions for Hybrid + Multicloud