From 6d257c1b8efb7b417d4f4e2b6586b9a781400829 Mon Sep 17 00:00:00 2001 From: John-Michael Faircloth Date: Fri, 16 Dec 2022 09:40:59 -0600 Subject: [PATCH] docs: update azure docs to reflect new managed identity support (#18357) * docs: update azure docs to reflect new managed identity support * update links and formatting * update wording * update resource_id description * fix formatting; add section on token limitations * fix link and formatting --- website/content/api-docs/auth/azure.mdx | 6 +++- website/content/docs/auth/azure.mdx | 42 +++++++++++++++++-------- 2 files changed, 34 insertions(+), 14 deletions(-) diff --git a/website/content/api-docs/auth/azure.mdx b/website/content/api-docs/auth/azure.mdx index e803193687..9dbe63f649 100644 --- a/website/content/api-docs/auth/azure.mdx +++ b/website/content/api-docs/auth/azure.mdx @@ -280,10 +280,14 @@ entity and then authorizes the entity for the given role. metadata. - `vm_name` `(string: "")` - The virtual machine name for the machine that generated the MSI token. This information can be obtained through instance - metadata. If vmss_name is provided, this value is ignored. + metadata. If `vmss_name` is provided, this value is ignored. - `vmss_name` `(string: "")` - The virtual machine scale set name for the machine that generated the MSI token. This information can be obtained through instance metadata. +- `resource_id` `(string: "")` - The fully qualified ID of the Azure resource that + generated the MSI token, including the resource name and resource type. Use + the format /subscriptions/{guid}/resourceGroups/{resource-group-name}/{resource-provider-namespace}/{resource-type}/{resource-name}. + If `vm_name` or `vmss_name` is provided, this value is ignored. ### Sample Payload diff --git a/website/content/docs/auth/azure.mdx b/website/content/docs/auth/azure.mdx index 3006527f8b..485ff81eee 100644 --- a/website/content/docs/auth/azure.mdx +++ b/website/content/docs/auth/azure.mdx @@ -14,7 +14,7 @@ and expects a [JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) signed by Azure Active Directory for the configured tenant. This method supports authentication for system-assigned and user-assigned -managed identities. See [Azure Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview) +managed identities. See [Managed identities for Azure resources](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) for more information about these resources. This documentation assumes the Azure method is mounted at the `/auth/azure` @@ -32,25 +32,27 @@ are required to configure the auth method: resources. See [Azure AD Service to Service Client Credentials](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service). If Vault is hosted on Azure, Vault can use MSI to access Azure instead of a shared secret. -MSI must be [enabled](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm) -on the VMs hosting Vault. +A managed identity must be [enabled](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/) +on the resource that acquires the access token. The following Azure [role assignments](https://learn.microsoft.com/en-us/azure/role-based-access-control/overview#role-assignments) must be granted to the Azure AD application in order for the auth method to access Azure APIs during authentication. ~> **Note:** The role assignments are only required when the -[`vm_name`](/api-docs/auth/azure#vm_name) and [`vmss_name`](/api-docs/auth/azure#vmss_name) -parameters are used on login. +[`vm_name`](/api-docs/auth/azure#vm_name), [`vmss_name`](/api-docs/auth/azure#vmss_name), +or [`resource_id`](/api-docs/auth/azure#resource_id) parameters are used on login. | Azure Environment | Login Parameter | Azure API Permission | | ----------- | --------------- | -------------------- | | Virtual Machine | [`vm_name`](/api-docs/auth/azure#vm_name) | `Microsoft.Compute/virtualMachines/*/read` | | Virtual Machine Scale Set ([Uniform Orchestration][vmss-uniform]) | [`vmss_name`](/api-docs/auth/azure#vmss_name) | `Microsoft.Compute/virtualMachineScaleSets/*/read` | | Virtual Machine Scale Set ([Flexible Orchestration][vmss-flex]) | [`vmss_name`](/api-docs/auth/azure#vmss_name) | `Microsoft.Compute/virtualMachineScaleSets/*/read` `Microsoft.ManagedIdentity/userAssignedIdentities/*/read` | +| Services that ([support managed identities][managed-identities]) for Azure resources | [`resource_id`](/api-docs/auth/azure#resource_id) | `read` on the resource used to obtain the JWT | [vmss-uniform]: https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes#scale-sets-with-uniform-orchestration [vmss-flex]: https://learn.microsoft.com/en-us/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes#scale-sets-with-flexible-orchestration +[managed-identities]: https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/managed-identities-status ## Authentication @@ -68,7 +70,12 @@ $ vault write auth/azure/login \ vm_name="test-vm" ``` -The `role` and `jwt` parameters are required. When using `bound_service_principal_ids` and `bound_group_ids` in the token roles, all the information is required in the JWT (except for _vm_name_ and _vmss_name_). When using other `bound_*` parameters, calls to Azure APIs will be made and subscription id, resource group name, and vm name/vmss_name are all required and can be obtained through instance metadata. +The `role` and `jwt` parameters are required. When using +`bound_service_principal_ids` and `bound_group_ids` in the token roles, all the +information is required in the JWT (except for `vm_name`, `vmss_name`, `resource_id`). When +using other `bound_*` parameters, calls to Azure APIs will be made and +`subscription_id`, `resource_group_name`, and `vm_name`/`vmss_name` are all required +and can be obtained through instance metadata. For example: @@ -116,13 +123,13 @@ tool. 1. Enable Azure authentication in Vault: - ```text + ```shell-session $ vault auth enable azure ``` 1. Configure the Azure auth method: - ```text + ```shell-session $ vault write auth/azure/config \ tenant_id=7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \ resource=https://management.azure.com/ \ @@ -135,7 +142,7 @@ tool. 1. Create a role: - ```text + ```shell-session $ vault write auth/azure/role/dev-role \ policies="prod,dev" \ bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \ @@ -153,7 +160,7 @@ tool. 1. Enable Azure authentication in Vault: - ```sh + ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ @@ -163,7 +170,7 @@ tool. 1. Configure the Azure auth method: - ```sh + ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ @@ -173,7 +180,7 @@ tool. 1. Create a role: - ```sh + ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ @@ -185,11 +192,20 @@ tool. There are two types of [managed identities](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview#managed-identity-types) in Azure: System-assigned and User-assigned. System-assigned identities are unique to -every virtual machine in Azure. If the virtual machines using Azure auth are recreated +every virtual machine in Azure. If the resources using Azure auth are recreated frequently, using system-assigned identities could result in many Vault entities being created. For environments with high ephemeral workloads, user-assigned identities are recommended. + +### Limitations + +The TTL of the access token returned by Azure AD for a managed identity is +24hrs and is not configurable. See ([limitations of using managed identities][id-limitations]) +for more info. + +[id-limitations]: https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations#limitation-of-using-managed-identities-for-authorization + ## Azure Debug Logs The Azure auth plugin supports debug logging which includes additional information