» 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) signed by Azure Active Directory for the configured tenant.

Currently supports authentication for:

» Prerequisites:

The following documentation assumes that the method has been mounted at auth/azure.

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 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:

» 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.

$ 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_pricipal_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.

» 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.

$ 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:

{
  "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:

    $ vault auth enable azure
    
  2. Configure the Azure auth method:

    $ 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.

  3. Create a role:

    $ 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.

» Via the API

  1. Enable Azure authentication in Vault:

    $ curl \
        --header "X-Vault-Token: ..." \
        --request POST \
        --data '{"type": "azure"}' \
        https://127.0.0.1:8200/v1/sys/auth/azure
    
  2. Configure the Azure auth method:

    $ curl \
        --header "X-Vault-Token: ..." \
        --request POST \
        --data '{"tenant_id": "...", "resource": "..."}' \
        https://127.0.0.1:8200/v1/auth/azure/config
    
  3. Create a role:

    $ 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

Assuming you have saved the binary vault-plugin-auth-azure to some folder and configured the plugin directory for your server at path/to/plugins:

  1. Enable the plugin in the catalog:

    $ vault write sys/plugins/catalog/azure-auth \
        command="vault-plugin-auth-azure" \
        sha_256="..."
    
  2. Enable the azure auth method as a plugin:

    $ vault auth enable -path=azure -plugin-name=azure-auth plugin
    

» API

The Azure Auth Plugin has a full HTTP API. Please see the API documentation for more details.