8eed94b072
* website maintenance round * improve docs, revert bug workaround as it was fixed * boost memory * remove unnecessary code
197 lines
6.7 KiB
Plaintext
197 lines
6.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Azure - Auth Methods
|
|
sidebar_title: Azure
|
|
description: |-
|
|
The azure auth method plugin allows automated authentication of Azure Active
|
|
Directory.
|
|
---
|
|
|
|
# Azure Auth Method
|
|
|
|
The `azure` auth method allows authentication against Vault using
|
|
Azure Active Directory credentials. It treats Azure as a Trusted Third Party
|
|
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.
|
|
|
|
## Prerequisites:
|
|
|
|
The following documentation assumes that the method has been
|
|
[mounted](/docs/plugin) at `auth/azure`.
|
|
|
|
- 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)
|
|
|
|
Required Azure API permissions to be granted to Vault user:
|
|
|
|
- `Microsoft.Compute/virtualMachines/*/read`
|
|
- `Microsoft.Compute/virtualMachineScaleSets/*/read`
|
|
|
|
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.
|
|
|
|
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/auth/azure) docs.
|
|
|
|
## Authentication
|
|
|
|
### Via the CLI
|
|
|
|
The default path is `/auth/azure`. If this auth method was enabled at a different
|
|
path, specify `auth/my-path/login` instead.
|
|
|
|
```shell-session
|
|
$ vault write auth/azure/login \
|
|
role="dev-role" \
|
|
jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
|
|
subscription_id="12345-..." \
|
|
resource_group_name="test-group" \
|
|
vm_name="test-vm"
|
|
```
|
|
|
|
The `role` and `jwt` parameters are required. When using bound*service_principal_ids and bound_groups in the token roles, all the information is required in the JWT. When using other bound*\* parameters, calls to Azure APIs will be made and subscription id, resource group name, and vm name are all required and can be obtained through instance metadata.
|
|
|
|
For example:
|
|
|
|
```shell-session
|
|
$ vault write auth/azure/login role="dev-role" \
|
|
jwt="$(curl -s 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https%3A%2F%2Fvault.hashicorp.com%2F' -H Metadata:true | jq -r '.access_token')" \
|
|
subscription_id=$(curl -s -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-08-01" | jq -r '.compute | .subscriptionId') \
|
|
resource_group_name=$(curl -s -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-08-01" | jq -r '.compute | .resourceGroupName') \
|
|
vm_name=$(curl -s -H Metadata:true "http://169.254.169.254/metadata/instance?api-version=2017-08-01" | jq -r '.compute | .name')
|
|
```
|
|
|
|
### Via the API
|
|
|
|
The default endpoint is `auth/azure/login`. If this auth method was enabled
|
|
at a different path, use that value instead of `azure`.
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data '{"role": "dev-role", "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
|
|
https://127.0.0.1:8200/v1/auth/azure/login
|
|
```
|
|
|
|
The response will contain the token at `auth.client_token`:
|
|
|
|
```json
|
|
{
|
|
"auth": {
|
|
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
|
|
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
|
|
"policies": ["default", "dev", "prod"],
|
|
"lease_duration": 2764800,
|
|
"renewable": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Auth methods must be configured in advance before machines can authenticate.
|
|
These steps are usually completed by an operator or configuration management
|
|
tool.
|
|
|
|
### Via the CLI
|
|
|
|
1. Enable Azure authentication in Vault:
|
|
|
|
```text
|
|
$ vault auth enable azure
|
|
```
|
|
|
|
1. Configure the Azure auth method:
|
|
|
|
```text
|
|
$ vault write auth/azure/config \
|
|
tenant_id=7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \
|
|
resource=https://vault.hashicorp.com \
|
|
client_id=dd794de4-4c6c-40b3-a930-d84cd32e9699 \
|
|
client_secret=IT3B2XfZvWnfB98s1cie8EMe7zWg483Xy8zY004=
|
|
```
|
|
|
|
For the complete list of configuration options, please see the API
|
|
documentation.
|
|
|
|
1. Create a role:
|
|
|
|
```text
|
|
$ vault write auth/azure/role/dev-role \
|
|
policies="prod,dev" \
|
|
bound_subscription_ids=6a1d5988-5917-4221-b224-904cd7e24a25 \
|
|
bound_resource_groups=vault
|
|
```
|
|
|
|
Roles are associated with an authentication type/entity and a set of Vault
|
|
policies. Roles are configured with constraints specific to the
|
|
authentication type, as well as overall constraints and configuration for
|
|
the generated auth tokens.
|
|
|
|
For the complete list of role options, please see the [API documentation](/api/auth/azure).
|
|
|
|
### Via the API
|
|
|
|
1. Enable Azure authentication in Vault:
|
|
|
|
```sh
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request POST \
|
|
--data '{"type": "azure"}' \
|
|
https://127.0.0.1:8200/v1/sys/auth/azure
|
|
```
|
|
|
|
1. Configure the Azure auth method:
|
|
|
|
```sh
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request POST \
|
|
--data '{"tenant_id": "...", "resource": "..."}' \
|
|
https://127.0.0.1:8200/v1/auth/azure/config
|
|
```
|
|
|
|
1. Create a role:
|
|
|
|
```sh
|
|
$ curl \
|
|
--header "X-Vault-Token: ..." \
|
|
--request POST \
|
|
--data '{"policies": ["dev", "prod"], ...}' \
|
|
https://127.0.0.1:8200/v1/auth/azure/role/dev-role
|
|
```
|
|
|
|
### Plugin Setup
|
|
|
|
~> 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/internals/plugins#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
|
|
```
|
|
|
|
## API
|
|
|
|
The Azure Auth Plugin has a full HTTP API. Please see the [API documentation](/api/auth/azure) for more details.
|