open-vault/website/content/docs/auth/azure.mdx

---
layout: docs
page_title: Azure - Auth Methods
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 [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`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.

## Prerequisites:

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

If Vault is hosted on Azure, Vault can use MSI to access Azure instead of a shared secret.
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.

### Role assignments

~> **Note:** The role assignments are only required when the
[`vm_name`](/vault/api-docs/auth/azure#vm_name), [`vmss_name`](/vault/api-docs/auth/azure#vmss_name),
or [`resource_id`](/vault/api-docs/auth/azure#resource_id) parameters are used on login.

| Azure Environment | Login Parameter | Azure API Permission |
| ----------- | --------------- | -------------------- |
| Virtual Machine | [`vm_name`](/vault/api-docs/auth/azure#vm_name) | `Microsoft.Compute/virtualMachines/*/read` |
| Virtual Machine Scale Set ([Uniform Orchestration][vmss-uniform]) | [`vmss_name`](/vault/api-docs/auth/azure#vmss_name) | `Microsoft.Compute/virtualMachineScaleSets/*/read` |
| Virtual Machine Scale Set ([Flexible Orchestration][vmss-flex]) | [`vmss_name`](/vault/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`](/vault/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

### API permissions

The following [API permissions](https://learn.microsoft.com/en-us/azure/active-directory/develop/permissions-consent-overview#types-of-permissions)
must be assigned to the service principal provided to Vault for managing the root rotation in Azure:

| Permission Name               | Type        |
| ----------------------------- | ----------- |
| Application.ReadWrite.All     | Application |

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

```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%2Fmanagement.azure.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:

   ```shell-session
   $ vault auth enable azure
   ```

1. Configure the Azure auth method:

   ```shell-session
   $ vault write auth/azure/config \
       tenant_id=7cd1f227-ca67-4fc6-a1a4-9888ea7f388c \
       resource=https://management.azure.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:

   ```shell-session
   $ 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](/vault/api-docs/auth/azure).

### Via the API

1. Enable Azure authentication in Vault:

   ```shell-session
   $ 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:

   ```shell-session
   $ 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:

   ```shell-session
   $ curl \
       --header "X-Vault-Token: ..." \
       --request POST \
       --data '{"policies": ["dev", "prod"], ...}' \
       https://127.0.0.1:8200/v1/auth/azure/role/dev-role
   ```

## Azure managed identities

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 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
about requests and responses from the Azure API.

To enable the Azure debug logs, set the following environment variable on the Vault
server:

```shell
AZURE_GO_SDK_LOG_LEVEL=DEBUG
```

## API

The Azure Auth Plugin has a full HTTP API. Please see the [API documentation](/vault/api-docs/auth/azure) for more details.

## Code example

The following example demonstrates the Azure auth method to authenticate
with Vault.

<CodeTabs>

<CodeBlockConfig>

```go
package main

import (
	"context"
	"fmt"

	vault "github.com/hashicorp/vault/api"
	auth "github.com/hashicorp/vault/api/auth/azure"
)

// Fetches a key-value secret (kv-v2) after authenticating to Vault via Azure authentication.
// This example assumes you have a configured Azure AD Application.
func getSecretWithAzureAuth() (string, error) {
	config := vault.DefaultConfig() // modify for more granular configuration

	client, err := vault.NewClient(config)
	if err != nil {
		return "", fmt.Errorf("unable to initialize Vault client: %w", err)
	}

	azureAuth, err := auth.NewAzureAuth(
		"dev-role-azure",
	)
	if err != nil {
		return "", fmt.Errorf("unable to initialize Azure auth method: %w", err)
	}

	authInfo, err := client.Auth().Login(context.Background(), azureAuth)
	if err != nil {
		return "", fmt.Errorf("unable to login to Azure auth method: %w", err)
	}
	if authInfo == nil {
		return "", fmt.Errorf("no auth info was returned after login")
	}

	// get secret from the default mount path for KV v2 in dev mode, "secret"
	secret, err := client.KVv2("secret").Get(context.Background(), "creds")
	if err != nil {
		return "", fmt.Errorf("unable to read secret: %w", err)
	}

	// data map can contain more than one key-value pair,
	// in this case we're just grabbing one of them
	value, ok := secret.Data["password"].(string)
	if !ok {
		return "", fmt.Errorf("value type assertion failed: %T %#v", secret.Data["password"], secret.Data["password"])
	}

	return value, nil
}

```
</CodeBlockConfig>

<CodeBlockConfig>

```cs
using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
using VaultSharp;
using VaultSharp.V1.AuthMethods;
using VaultSharp.V1.AuthMethods.Azure;
using VaultSharp.V1.Commons;

namespace Examples
{
    public class AzureAuthExample
    {
        public class InstanceMetadata
        {
            public string name { get; set; }
            public string resourceGroupName { get; set; }
            public string subscriptionId { get; set; }
        }

        const string MetadataEndPoint = "http://169.254.169.254/metadata/instance?api-version=2017-08-01";
        const string AccessTokenEndPoint = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://management.azure.com/";

        /// <summary>
        /// Fetches a key-value secret (kv-v2) after authenticating to Vault via Azure authentication.
        /// This example assumes you have a configured Azure AD Application.
        /// </summary>
        public string GetSecretWithAzureAuth()
        {
            string vaultAddr = Environment.GetEnvironmentVariable("VAULT_ADDR");
            if(String.IsNullOrEmpty(vaultAddr))
            {
                throw new System.ArgumentNullException("Vault Address");
            }

            string roleName = Environment.GetEnvironmentVariable("VAULT_ROLE");
            if(String.IsNullOrEmpty(roleName))
            {
                throw new System.ArgumentNullException("Vault Role Name");
            }

            string jwt = GetJWT();
            InstanceMetadata metadata = GetMetadata();

            IAuthMethodInfo authMethod = new AzureAuthMethodInfo(roleName: roleName, jwt: jwt, subscriptionId: metadata.subscriptionId, resourceGroupName: metadata.resourceGroupName, virtualMachineName: metadata.name);
            var vaultClientSettings = new VaultClientSettings(vaultAddr, authMethod);

            IVaultClient vaultClient = new VaultClient(vaultClientSettings);

            // We can retrieve the secret from the VaultClient object
            Secret<SecretData> kv2Secret = null;
            kv2Secret = vaultClient.V1.Secrets.KeyValue.V2.ReadSecretAsync(path: "/creds").Result;

            var password = kv2Secret.Data.Data["password"];

            return password.ToString();
        }

        /// <summary>
        /// Query Azure Resource Manage for metadata about the Azure instance
        /// </summary>
        private InstanceMetadata GetMetadata()
        {
            HttpWebRequest metadataRequest = (HttpWebRequest)WebRequest.Create(MetadataEndPoint);
            metadataRequest.Headers["Metadata"] = "true";
            metadataRequest.Method = "GET";

            HttpWebResponse metadataResponse = (HttpWebResponse)metadataRequest.GetResponse();

            StreamReader streamResponse = new StreamReader(metadataResponse.GetResponseStream());
            string stringResponse = streamResponse.ReadToEnd();
            var resultsDict = JsonConvert.DeserializeObject<Dictionary<string, InstanceMetadata>>(stringResponse);

            return resultsDict["compute"];
        }

        /// <summary>
        /// Query Azure Resource Manager (ARM) for an access token
        /// </summary>
        private string GetJWT()
        {
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(AccessTokenEndPoint);
            request.Headers["Metadata"] = "true";
            request.Method = "GET";

            HttpWebResponse response = (HttpWebResponse)request.GetResponse();

            // Pipe response Stream to a StreamReader and extract access token
            StreamReader streamResponse = new StreamReader(response.GetResponseStream());
            string stringResponse = streamResponse.ReadToEnd();
            var resultsDict = JsonConvert.DeserializeObject<Dictionary<string, string>>(stringResponse);

            return resultsDict["access_token"];
        }
    }
}
```

</CodeBlockConfig>

</CodeTabs>