Skip to content

Commit a4b7e33

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #253521 from MGoedtel/task145613
First draft Kubelogin reference
2 parents 093d37d + fa12861 commit a4b7e33

File tree

2 files changed

+339
-4
lines changed

2 files changed

+339
-4
lines changed

‎articles/aks/TOC.yml

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -363,10 +363,12 @@
363363
href: use-labels.md
364364
- name: Security and authentication
365365
items:
366-
- name: Defender for Containers overview
367-
href: ../defender-for-cloud/defender-for-containers-introduction.md?toc=/azure/aks/toc.json&bc=/azure/aks/breadcrumb/toc.json
368-
- name: Enable Defender for Containers
369-
href: ../defender-for-cloud/defender-for-containers-enable.md?tabs=aks-deploy-portal%2Ck8s-deploy-asc%2Ck8s-verify-asc%2Ck8s-remove-arc%2Caks-removeprofile-api&pivots=defender-for-container-aks?toc=/azure/aks/toc.json&bc=/azure/aks/breadcrumb/toc.json
366+
- name: Container security
367+
items:
368+
- name: Defender for Containers overview
369+
href: ../defender-for-cloud/defender-for-containers-introduction.md?toc=/azure/aks/toc.json&bc=/azure/aks/breadcrumb/toc.json
370+
- name: Enable Defender for Containers
371+
href: ../defender-for-cloud/defender-for-containers-enable.md?tabs=aks-deploy-portal%2Ck8s-deploy-asc%2Ck8s-verify-asc%2Ck8s-remove-arc%2Caks-removeprofile-api&pivots=defender-for-container-aks?toc=/azure/aks/toc.json&bc=/azure/aks/breadcrumb/toc.json
370372
- name: Image security
371373
items:
372374
- name: Validate signed images with Image Integrity
@@ -379,6 +381,8 @@
379381
href: ../defender-for-cloud/defender-for-containers-introduction.mdtoc=/azure/aks/toc.json&bc=/azure/aks/breadcrumb/toc.json
380382
- name: Cluster security
381383
items:
384+
- name: Azure kubelogin
385+
href: kubelogin-authentication.md
382386
- name: Create service principal
383387
href: kubernetes-service-principal.md
384388
- name: Use managed identities

‎articles/aks/kubelogin-authentication.md

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
---
2+
title: Using Kubelogin with Azure Kubernetes Service (AKS)
3+
description: Learn about using Kubelogin to enable all of the supported Azure Active Directory authentication methods with Azure Kubernetes Service (AKS).
4+
ms.topic: article
5+
ms.date: 11/28/2023
6+
7+
---
8+
9+
# Use Kubelogin with Azure Kubernetes Service (AKS)
10+
11+
Kubelogin is a client-go credential [plugin][client-go-cred-plugin] that implements Microsoft Entra ID authentication. This plugin provides features that are not available in kubectl.
12+
13+
Azure Kubernetes Service (AKS) clusters integrated with Microsoft Entra ID, running Kubernetes versions 1.24 and higher, automatically use the `kubelogin` format.
14+
15+
This article provides an overview of the following authentication methods and examples on how to use them:
16+
17+
* Device code
18+
* The Azure CLI
19+
* Interactive web browser
20+
* Service principal
21+
* Managed identity
22+
* Workflow identity
23+
24+
## Limitations
25+
26+
* A maximum of 200 groups are included in the Microsoft Entra ID JSON Web Token (JWT). For more than 200 groups, consider using [Application Roles][entra-id-application-roles].
27+
* Groups created in Microsoft Entra ID are only included by their ObjectID and not by their display name. `sAMAccountName` is only available for groups synchronized from on-premises Active Directory.
28+
* On AKS, service principal authentication method only works with managed Microsoft Entra ID, not legacy Azure Active Directory.
29+
* Device code authentication method doesn't work when Conditional Access policy is configured on a Microsoft Entra tenant. Use web browser interactive authentication instead.
30+
31+
## Authentication modes
32+
33+
Most of the interaction with `kubelogin` is specific to the `convert-kubeconfig` subcommand, which uses the input kubeconfig specified in `--kubeconfig` or `KUBECONFIG` environment variable to convert to the final kubeconfig in exec format based on the specified authentication mode.
34+
35+
### How authentication works
36+
37+
The authentication modes that `kubelogin` implements are Microsoft Entra ID OAuth 2.0 token grant flows. Throughout `kubelogin` subcommands, you see below common flags. In general, these flags are already set up when you get the kubeconfig from AKS.
38+
39+
* **--tenant-id**: Microsoft Entra ID tenant ID
40+
* **--client-id**: The application ID of the public client application. This client app is only used in device code, web browser interactive, and ropc log in modes.
41+
* **--server-id**: The application ID of the web app, or resource server. The token should be issued to this resource.
42+
43+
> [!NOTE]
44+
> With each authentication method, the token isn't cached on the file system.
45+
46+
## Using device code
47+
48+
Device code is the default authentication mode in `convert-kubeconfig` subcommand. The `-l devicecode` is optional. This authentication method prompts the device code for user to sign in from a browser session.
49+
50+
Before `kubelogin` and Exec plugin were introduced, the Azure authentication mode in `kubectl` only supported device code flow. It used an old library that produces the token with `audience` claim that has the `spn:` prefix, which isn't compatible with [AKS-managed Microsoft Entra ID][aks-managed-microsoft-entra-id] using [on-behalf-of][oauth-on-behalf-of] (OBO) flow. When you run the `convert-kubeconfig` subcommand, `kubelogin` removes the `spn:` (prefix in audience claim). If you require using the original functionality, add the `--legacy` argument.
51+
52+
If you're using `kubeconfig` from legacy Azure AD cluster, `kubelogin` automatically adds the `--legacy` flag.
53+
54+
In this sign in mode, the access token and refresh token are cached in the `${HOME}/.kube/cache/kubelogin` directory. This path can be overridden specifying the `--token-cache-dir` parameter.
55+
56+
If your Azure AD integrated cluster uses Kubernetes version 1.24 or earlier, you need to manually convert the kubeconfig format by running the following commands.
57+
58+
```bash
59+
export KUBECONFIG=/path/to/kubeconfig
60+
kubelogin convert-kubeconfig
61+
```
62+
63+
Run `kubectl` command to get node information.
64+
65+
```bash
66+
kubectl get nodes
67+
```
68+
69+
To clean up cached tokens, run the following command.
70+
71+
```bash
72+
kubelogin remove-tokens
73+
```
74+
75+
> [!NOTE]
76+
> Device code sign in method doesn't work when Conditional Access policy is configured on Microsoft Entra tenant. Use the [web browser interactive mode][web-browser-interactive-mode] instead.
77+
78+
## Using the Azure CLI
79+
80+
Authenticating using the Azure CLI method uses the already signed in context performed by the Azure CLI to get the access token. The token is issued in the same Microsoft Entra tenant as with `az login`.
81+
82+
`kubelogin` doesn't write the tokens to the token cache file. It's already managed by the Azure CLI.
83+
84+
> [!NOTE]
85+
> This authentication method only works with AKS-managed Microsoft Entra ID.
86+
87+
```bash
88+
az login
89+
90+
export KUBECONFIG=/path/to/kubeconfig
91+
92+
kubelogin convert-kubeconfig -l azurecli
93+
```
94+
95+
Run `kubectl` command to get node information.
96+
97+
```bash
98+
kubectl get nodes
99+
```
100+
101+
When the Azure CLI's config directory is outside the $`{HOME}` directory, specify the parameter `--azure-config-dir` in `convert-kubeconfig` subcommand. It generates the `kubeconfig` with the environment variable configured. You can achieve the same configuration by setting the environment variable `AZURE_CONFIG_DIR` to this directory while running `kubectl` command.
102+
103+
## Using an interactive web browser
104+
105+
Interactive web browser authentication automatically opens a web browser to log in the user. Once authenticated, the browser redirects back to a local web server with the credentials. This authentication method complies with Conditional Access policy.
106+
107+
When you authenticate using this method, the access token is cached in the `${HOME}/.kube/cache/kubelogin` directory. This path can be overridden by specifying the `--token-cache-dir` parameter.
108+
109+
The following example shows how to use a bearer token with interactive flow.
110+
111+
```bash
112+
export KUBECONFIG=/path/to/kubeconfig
113+
114+
kubelogin convert-kubeconfig -l interactive
115+
```
116+
117+
Run `kubectl` command to get node information.
118+
119+
```bash
120+
kubectl get nodes
121+
```
122+
123+
The following example shows how to use Proof-of-Possession (PoP) tokens with interactive flow.
124+
125+
```bash
126+
export KUBECONFIG=/path/to/kubeconfig
127+
128+
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
129+
```
130+
131+
Run `kubectl` command to get node information.
132+
133+
```bash
134+
kubectl get nodes
135+
```
136+
137+
## Using a service principal
138+
139+
This authentication method uses a service principal to sign in. The credential may be provided using an environment variable or command-line argument. The supported credentials are password and pfx client certificate.
140+
141+
The following are limitations to consider before using this method:
142+
143+
* This only works with managed Microsoft Entra ID
144+
* The service principal can be member of a maximum of [200 Microsoft Entra ID groups][microsoft-entra-group-membership].
145+
146+
The following examples show how to set up a client secret using an environment variable.
147+
148+
```bash
149+
export KUBECONFIG=/path/to/kubeconfig
150+
151+
kubelogin convert-kubeconfig -l spn
152+
153+
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<spn client id>
154+
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<spn secret>
155+
```
156+
157+
Run `kubectl` command to get node information.
158+
159+
```bash
160+
kubectl get nodes
161+
```
162+
163+
```bash
164+
export KUBECONFIG=/path/to/kubeconfig
165+
166+
kubelogin convert-kubeconfig -l spn
167+
168+
export AZURE_CLIENT_ID=<spn client id>
169+
export AZURE_CLIENT_SECRET=<spn secret>
170+
```
171+
172+
Run `kubectl` command to get node information.
173+
174+
```bash
175+
kubectl get nodes
176+
```
177+
178+
The following example shows how to set up a client secret in a command-line argument.
179+
180+
```bash
181+
export KUBECONFIG=/path/to/kubeconfig
182+
183+
kubelogin convert-kubeconfig -l spn --client-id <spn client id> --client-secret <spn client secret>
184+
```
185+
186+
Run `kubectl` command to get node information.
187+
188+
```bash
189+
kubectl get nodes
190+
```
191+
192+
> [!WARNING]
193+
> This method leaves the secret in the kubeconfig file.
194+
195+
The following examples show how to set up a client secret using a client certificate.
196+
197+
```bash
198+
export KUBECONFIG=/path/to/kubeconfig
199+
200+
kubelogin convert-kubeconfig -l spn
201+
202+
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<spn client id>
203+
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
204+
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<pfx password>
205+
```
206+
207+
Run `kubectl get nodes` command to get node information in ps output format.
208+
209+
```bash
210+
kubectl get nodes
211+
```
212+
213+
```bash
214+
export KUBECONFIG=/path/to/kubeconfig
215+
216+
kubelogin convert-kubeconfig -l spn
217+
218+
export AZURE_CLIENT_ID=<spn client id>
219+
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
220+
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<pfx password>
221+
```
222+
223+
Run `kubectl` command to get node information.
224+
225+
```bash
226+
kubectl get nodes
227+
```
228+
229+
The following example shows how to set up a Proof-of-Possession (PoP) token using a client secret from environment variables.
230+
231+
```bash
232+
export KUBECONFIG=/path/to/kubeconfig
233+
234+
kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
235+
236+
export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<spn client id>
237+
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<spn secret>
238+
```
239+
240+
Run `kubectl` command to get node information.
241+
242+
```bash
243+
kubectl get nodes
244+
```
245+
246+
## Using a managed identity
247+
248+
The [managed identity][managed-identity-overview] authentication method should be used for applications to use when connecting to resources that support Microsoft Entra authentication. For example, accessing Azure services such as Azure Virtual Machine, Azure Virtual Machine Scale Sets, Azure Cloud Shell, etc.
249+
250+
The following example shows how to use the default managed identity.
251+
252+
```bash
253+
export KUBECONFIG=/path/to/kubeconfig
254+
255+
kubelogin convert-kubeconfig -l msi
256+
```
257+
258+
Run `kubectl` command to get node information.
259+
260+
```bash
261+
kubectl get nodes
262+
```
263+
264+
The following example shows how to use a managed identity with a specific identity.
265+
266+
```bash
267+
export KUBECONFIG=/path/to/kubeconfig
268+
269+
kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>
270+
```
271+
272+
Run `kubectl` command to get node information.
273+
274+
```bash
275+
kubectl get nodes
276+
```
277+
278+
## Using a workload identity
279+
280+
This authentication method uses Microsoft Entra ID federated identity credentials to authenticate to Kubernetes clusters with Microsoft Entra ID integration. It works by setting the environment variables:
281+
282+
* **AZURE_CLIENT_ID**: the Microsoft Entra ID application ID that is federated with workload identity
283+
* **AZURE_TENANT_ID**: the Microsoft Entra ID tenant ID
284+
* **AZURE_FEDERATED_TOKEN_FILE**: the file containing signed assertion of workload identity. For example, Kubernetes projected service account (jwt) token
285+
* **AZURE_AUTHORITY_HOST**: the base URL of a Microsoft Entra ID authority. For example, `https://login.microsoftonline.com/`.
286+
287+
With [workload identity][workload-identity], it's possible to access Kubernetes clusters from CI/CD system such as GitHub, ArgoCD, etc. without storing Service Principal credentials in those external systems. To configure OIDC federation from GitHub, see the following [example][oidc-federation-github].
288+
289+
The following example shows how to use a workload identity.
290+
291+
```bash
292+
export KUBECONFIG=/path/to/kubeconfig
293+
294+
kubelogin convert-kubeconfig -l workloadidentity
295+
```
296+
297+
Run `kubectl` command to get node information.
298+
299+
```bash
300+
kubectl get nodes
301+
```
302+
303+
## Using Kubelogin with AKS
304+
305+
AKS uses a pair of first party Azure AD applications. These application IDs are the same in all environments.
306+
307+
The AKS Microsoft Entra ID Server application ID used by the server side is: `6dae42f8-4368-4678-94ff-3960e28e3630`. The access token accessing AKS clusters need to be issued for this application. In most of kubelogin authentication modes, `--server-id` is a required parameter with `kubelogin get-token`.
308+
309+
The AKS Microsoft Entra ID client application ID used by kubelogin to perform public client authentication on behalf of the user is: `80faf920-1908-4b52-b5ef-a8e7bedfc67a`. The client application ID is used as part of device code and web browser interactive authentication methods.
310+
311+
## Next steps
312+
313+
* Learn how to integrate AKS with Microsoft Entra ID with our [AKS-managed Microsoft Entra integration][aks-managed-microsoft-entra-integration-guide] how-to guide.
314+
* To get started with managed identities in AKS, see [Use a managed identity in AKS][use-managed-identity-aks].
315+
* To get started with workload identities in AKS, see [Use a workload identity in AKS][use-workload-identity-aks].
316+
317+
<!-- LINKS - internal -->
318+
[aks-managed-microsoft-entra-id]: managed-azure-ad.md
319+
[oauth-on-behalf-of]: ../active-directory/develop/v2-oauth2-on-behalf-of-flow.md
320+
[web-browser-interactive-mode]: #using-an-interactive-web-browser
321+
[microsoft-entra-group-membership]: /entra/identity/hybrid/connect/how-to-connect-fed-group-claims
322+
[managed-identity-overview]: /entra/identity/managed-identities-azure-resources/overview
323+
[workload-identity]: /entra/workload-id/workload-identities-overview
324+
[entra-id-application-roles]: /entra/external-id/customers/how-to-use-app-roles-customers
325+
[aks-managed-microsoft-entra-integration-guide]: managed-azure-ad.md
326+
[use-managed-identity-aks]: use-managed-identity.md
327+
[use-workload-identity-aks]: workload-identity-overview.md
328+
329+
<!-- LINKS - external -->
330+
[client-go-cred-plugin]: https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
331+
[oidc-federation-github]: https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-azure

0 commit comments

Comments
 (0)