Skip to content

Commit 1db689e

Browse files
cbiguetcbiguet
authored
Update azure auth docs to account for xms fields limitations and non-required fields on login command (#1258)
2 parents 8199611 + 6adc60e commit 1db689e

File tree

12 files changed

+138
-72
lines changed

12 files changed

+138
-72
lines changed

‎content/vault/v1.16.x/content/api-docs/auth/azure.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,13 @@ Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
287287
a role name for some entity. It verifies the JWT signature to authenticate that
288288
entity and then authorizes the entity for the given role.
289289

290+
The `role` and `jwt` parameters are required. When using
291+
`bound_service_principal_ids` and `bound_group_ids` in the token roles, all the
292+
information is required in the JWT (except for `vm_name`, `vmss_name`, `resource_id`). When
293+
using other `bound_*` parameters, calls to Azure APIs will be made and
294+
`subscription_id`, `resource_group_name`, and `vm_name`/`vmss_name` are all required
295+
and can be obtained through instance metadata.
296+
290297
| Method | Path |
291298
| :----- | :------------------ |
292299
| `POST` | `/auth/azure/login` |
@@ -298,10 +305,10 @@ entity and then authorizes the entity for the given role.
298305
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT)
299306
from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token)
300307
for details on how to acquire a JWT access token through instance metadata.
301-
- `subscription_id` `(string: <required>)` - The subscription ID for the machine that
308+
- `subscription_id` `(string: "")` - The subscription ID for the machine that
302309
generated the MSI token. This information can be obtained through instance
303310
metadata.
304-
- `resource_group_name` `(string: <required>)` - The resource group for the machine that
311+
- `resource_group_name` `(string: "")` - The resource group for the machine that
305312
generated the MSI token. This information can be obtained through instance
306313
metadata.
307314
- `vm_name` `(string: "")` - The virtual machine name for the machine that

‎content/vault/v1.16.x/content/docs/auth/azure.mdx‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,20 @@ please update your API calls accordingly.
2323

2424
## Token validation ((#token-validation))
2525

26-
Vault validates the resource group (`resource_group_name`), VM name (`vm_name`)
27-
and VM scale set name (`vmss_name`) parameters against token claims. Depending
28-
on the identities attached to the machine generating the MSI token, the
29-
associated claims must include at least one of the following claims
30-
to pass validation: "xms_mirid" or "xms_az_rid".
31-
32-
System-assigned management identity | "xms_mirid" | "xms_az_rid"
33-
----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------| ---------------
34-
Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
35-
Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
26+
When using a first-party Azure resource, Vault validates the resource group
27+
(`resource_group_name`), VM name (`vm_name`) and VM scale set name (`vmss_name`)
28+
parameters against token claims. Depending on the identities attached to the
29+
machine generating the MSI token, the associated claims must include at least one
30+
of the following claims to pass validation: "xms_mirid" or "xms_az_rid". These
31+
claims are not present on the token when using a custom resource or a resource
32+
URI that begins with `api://` and so cannot be used.
33+
34+
Resource type | System-assigned management identity | "xms_mirid" | "xms_az_rid"
35+
------------------------------------- | ------------------------------------| --------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------
36+
First-party Azure resource | Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
37+
First-party Azure resource | Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
38+
Custom resource or API (`api://{id}`) | Enabled | Does not exist | Does not exist
39+
Custom resource or API (`api://{id}`) | Not enabled | Does not exist | Does not exist
3640

3741
See [Azure managed identity REST endpoint reference](https://learn.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=portal%2Chttp#rest-endpoint-reference) and
3842
[Managed identities for Azure resources frequently asked questions](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identities-faq#what-identity-will-imds-default-to-if-i-dont-specify-the-identity-in-the-request) for more details on how to request MSI tokens.

‎content/vault/v1.17.x/content/api-docs/auth/azure.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,13 @@ Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
297297
a role name for some entity. It verifies the JWT signature to authenticate that
298298
entity and then authorizes the entity for the given role.
299299

300+
The `role` and `jwt` parameters are required. When using
301+
`bound_service_principal_ids` and `bound_group_ids` in the token roles, all the
302+
information is required in the JWT (except for `vm_name`, `vmss_name`, `resource_id`). When
303+
using other `bound_*` parameters, calls to Azure APIs will be made and
304+
`subscription_id`, `resource_group_name`, and `vm_name`/`vmss_name` are all required
305+
and can be obtained through instance metadata.
306+
300307
| Method | Path |
301308
| :----- | :------------------ |
302309
| `POST` | `/auth/azure/login` |
@@ -308,10 +315,10 @@ entity and then authorizes the entity for the given role.
308315
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT)
309316
from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token)
310317
for details on how to acquire a JWT access token through instance metadata.
311-
- `subscription_id` `(string: <required>)` - The subscription ID for the machine that
318+
- `subscription_id` `(string: "")` - The subscription ID for the machine that
312319
generated the MSI token. This information can be obtained through instance
313320
metadata.
314-
- `resource_group_name` `(string: <required>)` - The resource group for the machine that
321+
- `resource_group_name` `(string: "")` - The resource group for the machine that
315322
generated the MSI token. This information can be obtained through instance
316323
metadata.
317324
- `vm_name` `(string: "")` - The virtual machine name for the machine that

‎content/vault/v1.17.x/content/docs/auth/azure.mdx‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,20 @@ please update your API calls accordingly.
2323

2424
## Token validation ((#token-validation))
2525

26-
Vault validates the resource group (`resource_group_name`), VM name (`vm_name`)
27-
and VM scale set name (`vmss_name`) parameters against token claims. Depending
28-
on the identities attached to the machine generating the MSI token, the
29-
associated claims must include at least one of the following claims
30-
to pass validation: "xms_mirid" or "xms_az_rid".
31-
32-
System-assigned management identity | "xms_mirid" | "xms_az_rid"
33-
----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------| ---------------
34-
Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
35-
Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
26+
When using a first-party Azure resource, Vault validates the resource group
27+
(`resource_group_name`), VM name (`vm_name`) and VM scale set name (`vmss_name`)
28+
parameters against token claims. Depending on the identities attached to the
29+
machine generating the MSI token, the associated claims must include at least one
30+
of the following claims to pass validation: "xms_mirid" or "xms_az_rid". These
31+
claims are not present on the token when using a custom resource or a resource
32+
URI that begins with `api://` and so cannot be used.
33+
34+
Resource type | System-assigned management identity | "xms_mirid" | "xms_az_rid"
35+
------------------------------------- | ------------------------------------| --------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------
36+
First-party Azure resource | Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
37+
First-party Azure resource | Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
38+
Custom resource or API (`api://{id}`) | Enabled | Does not exist | Does not exist
39+
Custom resource or API (`api://{id}`) | Not enabled | Does not exist | Does not exist
3640

3741
See [Azure managed identity REST endpoint reference](https://learn.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=portal%2Chttp#rest-endpoint-reference) and
3842
[Managed identities for Azure resources frequently asked questions](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identities-faq#what-identity-will-imds-default-to-if-i-dont-specify-the-identity-in-the-request) for more details on how to request MSI tokens.

‎content/vault/v1.18.x/content/api-docs/auth/azure.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,13 @@ Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
297297
a role name for some entity. It verifies the JWT signature to authenticate that
298298
entity and then authorizes the entity for the given role.
299299

300+
The `role` and `jwt` parameters are required. When using
301+
`bound_service_principal_ids` and `bound_group_ids` in the token roles, all the
302+
information is required in the JWT (except for `vm_name`, `vmss_name`, `resource_id`). When
303+
using other `bound_*` parameters, calls to Azure APIs will be made and
304+
`subscription_id`, `resource_group_name`, and `vm_name`/`vmss_name` are all required
305+
and can be obtained through instance metadata.
306+
300307
| Method | Path |
301308
| :----- | :------------------ |
302309
| `POST` | `/auth/azure/login` |
@@ -308,10 +315,10 @@ entity and then authorizes the entity for the given role.
308315
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT)
309316
from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token)
310317
for details on how to acquire a JWT access token through instance metadata.
311-
- `subscription_id` `(string: <required>)` - The subscription ID for the machine that
318+
- `subscription_id` `(string: "")` - The subscription ID for the machine that
312319
generated the MSI token. This information can be obtained through instance
313320
metadata.
314-
- `resource_group_name` `(string: <required>)` - The resource group for the machine that
321+
- `resource_group_name` `(string: "")` - The resource group for the machine that
315322
generated the MSI token. This information can be obtained through instance
316323
metadata.
317324
- `vm_name` `(string: "")` - The virtual machine name for the machine that

‎content/vault/v1.18.x/content/docs/auth/azure.mdx‎

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,20 @@ please update your API calls accordingly.
2323

2424
## Token validation ((#token-validation))
2525

26-
Vault validates the resource group (`resource_group_name`), VM name (`vm_name`)
27-
and VM scale set name (`vmss_name`) parameters against token claims. Depending
28-
on the identities attached to the machine generating the MSI token, the
29-
associated claims must include at least one of the following claims
30-
to pass validation: "xms_mirid" or "xms_az_rid".
31-
32-
System-assigned management identity | "xms_mirid" | "xms_az_rid"
33-
----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------| ---------------
34-
Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
35-
Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
26+
When using a first-party Azure resource, Vault validates the resource group
27+
(`resource_group_name`), VM name (`vm_name`) and VM scale set name (`vmss_name`)
28+
parameters against token claims. Depending on the identities attached to the
29+
machine generating the MSI token, the associated claims must include at least one
30+
of the following claims to pass validation: "xms_mirid" or "xms_az_rid". These
31+
claims are not present on the token when using a custom resource or a resource
32+
URI that begins with `api://` and so cannot be used.
33+
34+
Resource type | System-assigned management identity | "xms_mirid" | "xms_az_rid"
35+
------------------------------------- | ------------------------------------| --------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------
36+
First-party Azure resource | Enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}` | Does not exist
37+
First-party Azure resource | Not enabled | `/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity}` |`/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{virtual-machine-name}`
38+
Custom resource or API (`api://{id}`) | Enabled | Does not exist | Does not exist
39+
Custom resource or API (`api://{id}`) | Not enabled | Does not exist | Does not exist
3640

3741
See [Azure managed identity REST endpoint reference](https://learn.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=portal%2Chttp#rest-endpoint-reference) and
3842
[Managed identities for Azure resources frequently asked questions](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/managed-identities-faq#what-identity-will-imds-default-to-if-i-dont-specify-the-identity-in-the-request) for more details on how to request MSI tokens.

‎content/vault/v1.19.x/content/api-docs/auth/azure.mdx‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,13 @@ Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and
299299
a role name for some entity. It verifies the JWT signature to authenticate that
300300
entity and then authorizes the entity for the given role.
301301

302+
The `role` and `jwt` parameters are required. When using
303+
`bound_service_principal_ids` and `bound_group_ids` in the token roles, all the
304+
information is required in the JWT (except for `vm_name`, `vmss_name`, `resource_id`). When
305+
using other `bound_*` parameters, calls to Azure APIs will be made and
306+
`subscription_id`, `resource_group_name`, and `vm_name`/`vmss_name` are all required
307+
and can be obtained through instance metadata.
308+
302309
| Method | Path |
303310
| :----- | :------------------ |
304311
| `POST` | `/auth/azure/login` |
@@ -310,10 +317,10 @@ entity and then authorizes the entity for the given role.
310317
- `jwt` `(string: <required>)` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT)
311318
from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token)
312319
for details on how to acquire a JWT access token through instance metadata.
313-
- `subscription_id` `(string: <required>)` - The subscription ID for the machine that
320+
- `subscription_id` `(string: "")` - The subscription ID for the machine that
314321
generated the MSI token. This information can be obtained through instance
315322
metadata.
316-
- `resource_group_name` `(string: <required>)` - The resource group for the machine that
323+
- `resource_group_name` `(string: "")` - The resource group for the machine that
317324
generated the MSI token. This information can be obtained through instance
318325
metadata.
319326
- `vm_name` `(string: "")` - The virtual machine name for the machine that

0 commit comments

Comments
 (0)