Skip to content

Commit 64fa04e

Browse files
schaffererinschaffererin
committed
Rearchitect AKS-enabled Azure AD integration doc
1 parent dc2f9f9 commit 64fa04e

File tree

6 files changed

+543
-287
lines changed

6 files changed

+543
-287
lines changed

‎articles/aks/TOC.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -325,7 +325,13 @@
325325
- name: Enable Azure Active Directory integration
326326
items:
327327
- name: AKS-managed Azure AD
328-
href: managed-aad.md
328+
items:
329+
- name: Configure AKS-managed Azure for a new or existing cluster
330+
href: managed-aad.md
331+
- name: Manage local accounts
332+
href: manage-local-accounts-managed-aad.md
333+
- name: Cluster access control
334+
href: access-control-managed-aad.md
329335
- name: Azure AD integration (legacy)
330336
href: azure-ad-integration-cli.md
331337
- name: Enable GMSA integration

‎articles/aks/access-control-managed-aad.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Cluster access control with AKS-managed Azure Active Directory integration
3+
description: Learn how to access clusters when integrating Azure AD in your Azure Kubernetes Service (AKS) clusters.
4+
ms.topic: article
5+
ms.date: 04/20/2023
6+
ms.custom: devx-track-azurecli
7+
---
8+
9+
# Cluster access control with AKS-managed Azure Active Directory integration
10+
11+
## Use Conditional Access with Azure AD and AKS
12+
13+
When integrating Azure AD with your AKS cluster, you can also use [Conditional Access][aad-conditional-access] to control access to your cluster.
14+
15+
> [!NOTE]
16+
> Azure AD Conditional Access is an Azure AD Premium capability.
17+
18+
### Create an example Conditional Access policy to use with AKS
19+
20+
1. In the Azure portal, go to the **Azure Active Directory** page and select **Enterprise applications**.
21+
2. Select **Conditional Access** > **Policies** > **New policy**.
22+
:::image type="content" source="./media/managed-aad/conditional-access-new-policy.png" alt-text="Adding a Conditional Access policy":::
23+
3. Enter a name for the policy, for example **aks-policy**.
24+
4. Under **Assignments** select **Users and groups**. Choose the 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.
25+
:::image type="content" source="./media/managed-aad/conditional-access-users-groups.png" alt-text="Selecting users or groups to apply the Conditional Access policy":::
26+
5. Under **Cloud apps or actions > Include**, select **Select apps**. Search for **Azure Kubernetes Service** and select **Azure Kubernetes Service AAD Server**.
27+
:::image type="content" source="./media/managed-aad/conditional-access-apps.png" alt-text="Selecting Azure Kubernetes Service AD Server for applying the Conditional Access policy":::
28+
6. Under **Access controls > Grant**, select **Grant access**, **Require device to be marked as compliant**, and **Require all the selected controls**.
29+
:::image type="content" source="./media/managed-aad/conditional-access-grant-compliant.png" alt-text="Selecting to only allow compliant devices for the Conditional Access policy":::
30+
7. Confirm your settings, set **Enable policy** to **On**, and then select **Create**.
31+
:::image type="content" source="./media/managed-aad/conditional-access-enable-policy.png" alt-text="Enabling the Conditional Access policy":::
32+
33+
### Verify your Conditional Access policy has been successfully listed
34+
35+
1. Get the user credentials to access the cluster using the [`az aks get-credentials`][az-aks-get-credentials] command.
36+
37+
```azurecli-interactive
38+
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
39+
```
40+
41+
2. Follow the instructions to sign in.
42+
43+
3. View the nodes in the cluster using the `kubectl get nodes` command.
44+
45+
```azurecli-interactive
46+
kubectl get nodes
47+
```
48+
49+
4. In the Azure portal, navigate to **Azure Active Directory** and select **Enterprise applications** > **Activity** > **Sign-ins**.
50+
51+
5. Under the **Conditional Access** column you should see a status of **Success**. Select the event and then select **Conditional Access** tab. Your Conditional Access policy will be listed.
52+
:::image type="content" source="./media/managed-aad/conditional-access-sign-in-activity.png" alt-text="Screenshot that shows failed sign-in entry due to Conditional Access policy.":::
53+
54+
## Configure just-in-time cluster access with Azure AD and AKS
55+
56+
Another option for cluster access control is to use Privileged Identity Management (PIM) for just-in-time requests.
57+
58+
>[!NOTE]
59+
> PIM is an Azure AD Premium capability requiring a Premium P2 SKU. For more on Azure AD SKUs, see the [pricing guide][aad-pricing].
60+
61+
### Integrate just-in-time access requests with an AKS cluster using AKS-managed Azure AD integration
62+
63+
1. In the Azure portal, go to **Azure Active Directory** and select **Properties**.
64+
2. Note the value listed under **Tenant ID**. It will be referenced in a later step as `<tenant-id>`.
65+
:::image type="content" source="./media/managed-aad/jit-get-tenant-id.png" alt-text="In a web browser, the Azure portal screen for Azure Active Directory is shown with the tenant's ID highlighted.":::
66+
3. Select **Groups** > **New group**.
67+
:::image type="content" source="./media/managed-aad/jit-create-new-group.png" alt-text="Shows the Azure portal Active Directory groups screen with the 'New Group' option highlighted.":::
68+
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**.
69+
:::image type="content" source="./media/managed-aad/jit-new-group-created.png" alt-text="Shows the Azure portal's new group creation screen.":::
70+
5. On the **Groups** page, select the group you just created and note the Object ID. It will be referenced in a later step as `<object-id>`.
71+
:::image type="content" source="./media/managed-aad/jit-get-object-id.png" alt-text="Shows the Azure portal screen for the just-created group, highlighting the Object Id":::
72+
6. Create the AKS cluster with AKS-managed Azure AD integration using the [`az aks create`][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.
73+
74+
```azurecli-interactive
75+
az aks create -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <object-id> --aad-tenant-id <tenant-id>
76+
```
77+
78+
7. In the Azure portal, select **Activity** > **Privileged Access (Preview)** > **Enable Privileged Access**.
79+
:::image type="content" source="./media/managed-aad/jit-enabling-priv-access.png" alt-text="The Azure portal's Privileged access (Preview) page is shown, with 'Enable privileged access' highlighted":::
80+
8. To grant access, select **Add assignments**.
81+
:::image type="content" source="./media/managed-aad/jit-add-active-assignment.png" alt-text="The Azure portal's Privileged access (Preview) screen after enabling is shown. The option to 'Add assignments' is highlighted.":::
82+
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**.
83+
:::image type="content" source="./media/managed-aad/jit-adding-assignment.png" alt-text="The Azure portal's Add assignments Membership screen is shown, with a sample user selected to be added as a member. The option 'Next' is highlighted.":::
84+
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][aad-assignments].
85+
:::image type="content" source="./media/managed-aad/jit-set-active-assignment-details.png" alt-text="The Azure portal's Add assignments Setting screen is shown. An assignment type of 'Active' is selected and a sample justification has been given. The option 'Assign' is highlighted.":::
86+
87+
### Verify just-in-time access is working by accessing the cluster
88+
89+
1. Get the user credentials to access the cluster using the [`az aks get-credentials`][az-aks-get-credentials] command.
90+
91+
```azurecli-interactive
92+
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
93+
```
94+
95+
2. Follow the steps to sign in.
96+
97+
3. Use the `kubectl get nodes` command to view the nodes in the cluster.
98+
99+
```azurecli-interactive
100+
kubectl get nodes
101+
```
102+
103+
4. Note the authentication requirement and follow the steps to authenticate. If successful, you should see an output similar to the following example output:
104+
105+
```output
106+
To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code AAAAAAAAA to authenticate.
107+
NAME STATUS ROLES AGE VERSION
108+
aks-nodepool1-61156405-vmss000000 Ready agent 6m36s v1.18.14
109+
aks-nodepool1-61156405-vmss000001 Ready agent 6m42s v1.18.14
110+
aks-nodepool1-61156405-vmss000002 Ready agent 6m33s v1.18.14
111+
```
112+
113+
### Apply just-in-time access at the namespace level
114+
115+
1. Integrate your AKS cluster with [Azure RBAC](manage-azure-rbac.md).
116+
2. Associate the group you want to integrate with just-in-time access with a namespace in the cluster using the [`az role assignment create`][az-role-assignment-create] command.
117+
118+
```azurecli-interactive
119+
az role assignment create --role "Azure Kubernetes Service RBAC Reader" --assignee <AAD-ENTITY-ID> --scope $AKS_ID/namespaces/<namespace-name>
120+
```
121+
122+
3. Associate the group you configured at the namespace level with PIM to complete the configuration.
123+
124+
## Troubleshooting
125+
126+
If `kubectl get nodes` returns an error similar to the following:
127+
128+
```output
129+
Error from server (Forbidden): nodes is forbidden: User "aaaa11111-11aa-aa11-a1a1-111111aaaaa" cannot list resource "nodes" in API group "" at the cluster scope
130+
```
131+
132+
Make sure the admin of the security group has given your account an *Active* assignment.
133+
134+
<!-- LINKS - External -->
135+
[aad-pricing]: https://azure.microsoft.com/pricing/details/active-directory/
136+
137+
<!-- LINKS - Internal -->
138+
[aad-conditional-access]: ../active-directory/conditional-access/overview.md
139+
[az-aks-get-credentials]: /cli/azure/aks#az_aks_get_credentials
140+
[az-role-assignment-create]: /cli/azure/role/assignment#az_role_assignment_create
141+
[aad-assignments]: ../active-directory/privileged-identity-management/groups-assign-member-owner.md#assign-an-owner-or-member-of-a-group
142+
[az-aks-create]: /cli/azure/aks#az_aks_create

‎articles/aks/configure-managed-aad.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Configure AKS-managed Azure Active Directory integration for your clusters
3+
description: Learn how to configure Azure AD in your Azure Kubernetes Service (AKS) clusters.
4+
ms.topic: article
5+
ms.date: 04/20/2023
6+
ms.custom: devx-track-azurecli
7+
---
8+
9+
# Configure AKS-managed Azure Active Directory integration for your clusters
10+
11+
## Before you begin
12+
13+
* Make sure Azure CLI version 2.29.0 or later is installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI](/cli/azure/install-azure-cli).
14+
* You need `kubectl`, with a minimum version of [1.18.1](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.18.md#v1181) or [`kubelogin`](https://github.com/Azure/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.
15+
* If you're using [helm](https://github.com/helm/helm), you need a minimum version of helm 3.3.
16+
* This article requires that you have an Azure AD group for your cluster. This group will be registered as an admin group on the cluster to grant cluster admin permissions. If you don't have an existing Azure AD group, you can create one using the [`az ad group create`](/cli/azure/ad/group#az_ad_group_create) command.
17+
18+
## Create an AKS cluster with Azure AD enabled
19+
20+
1. Create an Azure resource group using the [`az group create`][az-group-create] command.
21+
22+
```azurecli-interactive
23+
az group create --name myResourceGroup --location centralus
24+
```
25+
26+
2. Create an AKS cluster and enable administration access for your Azure AD group using the [`az aks create`][az-aks-create] command.
27+
28+
```azurecli-interactive
29+
az aks create -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]
30+
```
31+
32+
A successful creation of an AKS-managed Azure AD cluster has the following section in the response body:
33+
34+
```output
35+
"AADProfile": {
36+
"adminGroupObjectIds": [
37+
"5d24****-****-****-****-****afa27aed"
38+
],
39+
"clientAppId": null,
40+
"managed": true,
41+
"serverAppId": null,
42+
"serverAppSecret": null,
43+
"tenantId": "72f9****-****-****-****-****d011db47"
44+
}
45+
```
46+
47+
## Enable AKS-managed Azure AD integration on your existing cluster
48+
49+
Enable AKS-managed Azure AD integration on your existing Kubernetes RBAC enabled cluster using the [`az aks update`][az-aks-update] command. Make sure to set your admin group to keep access on your cluster.
50+
51+
```azurecli-interactive
52+
az aks update -g MyResourceGroup -n MyManagedCluster --enable-aad --aad-admin-group-object-ids <id-1> [--aad-tenant-id <id>]
53+
```
54+
55+
A successful activation of an AKS-managed Azure AD cluster has the following section in the response body:
56+
57+
```output
58+
"AADProfile": {
59+
"adminGroupObjectIds": [
60+
"5d24****-****-****-****-****afa27aed"
61+
],
62+
"clientAppId": null,
63+
"managed": true,
64+
"serverAppId": null,
65+
"serverAppSecret": null,
66+
"tenantId": "72f9****-****-****-****-****d011db47"
67+
}
68+
```
69+
70+
Download user credentials again to access your cluster by following the steps in [access an Azure AD enabled cluster][access-cluster].
71+
72+
## Upgrade to AKS-managed Azure AD integration
73+
74+
If your cluster uses legacy Azure AD integration, you can upgrade to AKS-managed Azure AD integration with no downtime using the [`az aks update`][az-aks-update] command.
75+
76+
```azurecli-interactive
77+
az aks update -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]
78+
```
79+
80+
A successful migration of an AKS-managed Azure AD cluster has the following section in the response body:
81+
82+
```output
83+
"AADProfile": {
84+
"adminGroupObjectIds": [
85+
"5d24****-****-****-****-****afa27aed"
86+
],
87+
"clientAppId": null,
88+
"managed": true,
89+
"serverAppId": null,
90+
"serverAppSecret": null,
91+
"tenantId": "72f9****-****-****-****-****d011db47"
92+
}
93+
```
94+
95+
In order to access the cluster, follow the steps in [access an Azure AD enabled cluster][access-cluster] to update kubeconfig.
96+
97+
## Access an Azure AD enabled cluster
98+
99+
Before you access the cluster using an Azure AD defined group, you need the [Azure Kubernetes Service Cluster User](../role-based-access-control/built-in-roles.md#azure-kubernetes-service-cluster-user-role) built-in role.
100+
101+
1. Get the user credentials to access the cluster using the [`az aks get-credentials`][az-aks-get-credentials] command.
102+
103+
```azurecli-interactive
104+
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
105+
```
106+
107+
2. Follow the instructions to sign in.
108+
109+
3. Use the `kubectl get nodes` command to view nodes in the cluster.
110+
111+
```azurecli-interactive
112+
kubectl get nodes
113+
```
114+
115+
4. Set up [Azure role-based access control (Azure RBAC)](./azure-ad-rbac.md) to configure other security groups for your clusters.
116+
117+
## Troubleshooting access issues with Azure AD
118+
119+
> [!IMPORTANT]
120+
> The steps described in this section bypass the normal Azure AD group authentication. Use them only in an emergency.
121+
122+
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. You need to have access to the [Azure Kubernetes Service Cluster Admin](../role-based-access-control/built-in-roles.md#azure-kubernetes-service-cluster-admin-role) built-in role.
123+
124+
```azurecli-interactive
125+
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster --admin
126+
```
127+

0 commit comments

Comments
 (0)