Edit

Share via

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

  • Article

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 on Azure Stack HCI 23H2 currently supports enabling Azure RBAC only during Kubernetes cluster creation. You can't enable Azure RBAC after the Kubernetes cluster is created.

  • Install the latest version of the aksarc and connectedk8s Azure CLI extensions. Note that you need to run the aksarc extension version 1.1.1 or later to enable Azure RBAC. Run az --version to find the current version. If you need to install or upgrade Azure CLI, see Install Azure CLI.

    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.

  • Once Azure RBAC is enabled, you can access your Kubernetes cluster with the given permissions using either direct mode or proxy mode.

    • To access the Kubernetes cluster directly using the az aksarc get-credentials command, you need the Microsoft.HybridContainerService/provisionedClusterInstances/listUserKubeconfig/action, which is included in the Azure Kubernetes Service Arc Cluster User role permission.
    • To access the Kubernetes cluster from anywhere with a proxy mode using the az connectedk8s proxy command, or from the Azure portal, you need the Microsoft.Kubernetes/connectedClusters/listClusterUserCredential/action action, which is included in the Azure Arc-enabled Kubernetes Cluster User role permission. Meanwhile, you must verify that the agents and the machine performing the onboarding process meet the network requirements specified in Azure Arc-enabled Kubernetes network requirements.

  • To use kubectl, you can access it using either Azure RBAC or the AAD Admin Group.

    • To use kubectl with Azure RBAC, you need the Azure Arc Kubernetes Viewer role scoped to the connected cluster resource.
    • To use kubectl with the AAD Admin Group, you don't need any specific role, but you must ensure you are in one of the groups in the add-admin-group list of the connected cluster resource.

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 Arc provides the following five built-in roles. They are similar to the Kubernetes built-in roles with a few differences, such as supporting CRDs. See the full list of actions allowed by each Azure built-in role.

Role Description
Azure Arc-enabled Kubernetes Cluster User Allows you to retrieve the Cluster Connect-based kubeconfig file to manage clusters from anywhere.
Azure Arc Kubernetes Viewer Allows read-only access to see most objects in a namespace.
Doesn't allow viewing secrets, because read permission on secrets enables access to ServiceAccount credentials in the namespace. These credentials in turn allow API access through that ServiceAccount value (a form of privilege escalation).
Azure Arc Kubernetes Writer Allows read/write access to most objects in a namespace.
Doesn't allow viewing or modifying roles or role bindings. However, this role allows accessing secrets and running pods as any ServiceAccount value in the namespace, so it can be used to gain the API access levels of any such ServiceAccount value in the namespace.
Azure Arc Kubernetes Admin Allows admin access. It's intended to be granted within a namespace through RoleBinding. If you use it in RoleBinding, it allows read/write access to most resources in a namespace, including the ability to create roles and role bindings within the namespace. This role doesn't allow write access to resource quota or to the namespace itself.
Azure Arc Kubernetes Cluster Admin Allows "superuser" access to execute any action on any resource. When you use it in ClusterRoleBinding, it gives full control over every resource in the cluster and in all namespaces. When you use it in RoleBinding, it gives full control over every resource in the role binding namespace, including the namespace itself.

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: Access Kubernetes cluster

You can now access your Kubernetes cluster with the given permissions, using either direct mode or proxy mode.

Access your cluster with kubectl (direct mode)

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 need the Microsoft.HybridContainerService/provisionedClusterInstances/listUserKubeconfig/action, which is included in the Azure Kubernetes Service Arc Cluster User role permission:

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

Access your cluster from a client device (proxy mode)

To access the Kubernetes cluster from anywhere with a proxy mode using az connectedk8s proxy command, you need the Microsoft.Kubernetes/connectedClusters/listClusterUserCredential/action, which is included in Azure Arc-enabled Kubernetes Cluster User role permission.

Run the following steps on another client device:

  1. Sign in using Microsoft Entra authentication

  2. Get the cluster connect kubeconfig needed to communicate with the cluster from anywhere (even from outside the firewall surrounding the cluster):

    az connectedk8s proxy -n $CLUSTER_NAME -g $RESOURCE_GROUP

    Note

    This command opens the proxy and blocks the current shell.

  3. In a different shell session, use kubectl to send requests to the cluster:

    kubectl get pods -A

You should now see a response from the cluster containing the list of all pods under the default namespace.

For more information, see Access your cluster from a client device.

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