From 5d0aab1099584898414e58f9a029526adb518428 Mon Sep 17 00:00:00 2001 From: Austin Gebauer <34121980+austingebauer@users.noreply.github.com> Date: Thu, 20 Oct 2022 12:36:29 -0700 Subject: [PATCH] auth/azure: documents auth support for VMSS flexible orchestration (#17540) * auth/azure: documents auth support for VMSS flexible orchestration * adds changelog --- changelog/17540.txt | 4 ++ website/content/docs/auth/azure.mdx | 75 +++++++++++++---------------- 2 files changed, 38 insertions(+), 41 deletions(-) create mode 100644 changelog/17540.txt diff --git a/changelog/17540.txt b/changelog/17540.txt new file mode 100644 index 000000000..3915eae2a --- /dev/null +++ b/changelog/17540.txt @@ -0,0 +1,4 @@ +```release-note:improvement +auth/azure: Adds support for authentication with Managed Service Identity (MSI) from a +Virtual Machine Scale Set (VMSS) in flexible orchestration mode. +``` \ No newline at end of file diff --git a/website/content/docs/auth/azure.mdx b/website/content/docs/auth/azure.mdx index 5646d0f81..3006527f8 100644 --- a/website/content/docs/auth/azure.mdx +++ b/website/content/docs/auth/azure.mdx @@ -14,35 +14,43 @@ 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) for more information about these resources. +managed identities. See [Azure Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview) +for more information about these resources. -~> System-assigned identities are unique to every virtual machine in Azure. If the -virtual machines using Azure auth are recreated frequently, using system-assigned -identities could result in a lot of Vault entities. For environments with high ephemeral -workloads, user-assigned identities are recommended. +This documentation assumes the Azure method is mounted at the `/auth/azure` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. ## Prerequisites: -The following documentation assumes that the method has been -[mounted](/docs/plugins) at `auth/azure`. +The Azure auth method requires client credentials to access Azure APIs. The following +are required to configure the auth method: -- A configured [Azure AD application](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications) which is used as the resource for generating MSI access tokens. -- Client credentials (shared secret) for accessing the Azure Resource Manager with read access to compute endpoints. 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) +- A configured [Azure AD application](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-integrating-applications) + which is used as the resource for generating MSI access tokens. +- Client credentials (shared secret) with read access to particular Azure Resource Manager + 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). -Required Azure API permissions to be granted to Vault user: +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. -- `Microsoft.Compute/virtualMachines/*/read` -- `Microsoft.Compute/virtualMachineScaleSets/*/read` +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 above permissions are only required when the associated vm\* parameters are used on login. Please see the [API doc](https://www.vaultproject.io/api-docs/auth/azure#login) for more details. +~> **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. -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. +| 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` | -The next sections review how the authN/Z workflows work. If you -have already reviewed these sections, here are some quick links to: - -- [Usage](/docs/secrets/azure#usage) -- [API documentation](/api-docs/auth/azure) docs. +[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 ## Authentication @@ -173,29 +181,14 @@ tool. https://127.0.0.1:8200/v1/auth/azure/role/dev-role ``` -### Plugin Setup +## Azure Managed Identities -~> The following section is only relevant if you decide to enable the azure auth -method as an external plugin. The azure plugin method is integrated into Vault as -a builtin method by default. - -Assuming you have saved the binary `vault-plugin-auth-azure` to some folder and -configured the [plugin directory](/docs/plugins/plugin-architecture#plugin-directory) -for your server at `path/to/plugins`: - -1. Enable the plugin in the catalog: - - ```text - $ vault write sys/plugins/catalog/auth/azure-auth \ - command="vault-plugin-auth-azure" \ - sha256="..." - ``` - -1. Enable the azure auth method as a plugin: - - ```text - $ vault auth enable -path=azure azure-auth - ``` +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 +frequently, using system-assigned identities could result in many Vault entities being +created. For environments with high ephemeral workloads, user-assigned identities are +recommended. ## Azure Debug Logs