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.
This method supports authentication for system-assigned and user-assigned managed identities. See Managed Identities for Azure resources 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.
Note: Credentials can be referenced as environment variables as defined here for privacy purposes.
Pre-requisites
- A running Azure VM Instance with a system-assigned managed identity. Such as:
- A running Vault server. This article is written after performing these steps in the lab with Vault v1.14.0+ent.
- Note: 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.
Setup
-
To enable the Azure auth method, run:
:~$ vault auth enable azure
-
To get the details of the tenant_id of your subscription, run the following on the Azure cloud powershell or anywhere on the terminal where Azure CLI is installed, or simply copy from the Azure Portal.
> az account show --subscription <subscription_id>
-
Create a Service Principal in Azure AD for Vault with a Reader role assigned to it with Azure Resource Group as its scope. This is the resource group where the VM with managed identity lies. Run the following on the Azure cloud powershell or anywhere on the terminal where Azure CLI is installed, or simply copy from the Azure Portal.
Here, the appID will act as a client_id and the password will act as a client_secret for Vault.
> az ad sp create-for-rbac \
--name sp-for-vault \
--role reader \
--scopes /subscriptions/<subscription_id>/resourceGroups/Vault-Auth-Test_group
Output:
{
"appId": "<app_id>",
"displayName": "sp-for-vault",
"password": "<secret>",
"tenant": "<tenant_ID>"
} -
To configure the auth method, run:
:~$ vault write auth/azure/config \
tenant_id=<tenant_ID> \
resource=https://management.azure.com/ \
client_id=<client_ID> \
client_secret=<secret> \
environment=AzurePublicCloudNote:
-
resource(string: <required>)- The resource URL for the application registered in Azure Active Directory. The value is expected to match the audience (audclaim) of the JWT provided to the login API. See the resource parameter for how the audience is set when requesting a JWT access token from the Azure Instance Metadata Service (IMDS) endpoint. This value can also be provided with theAZURE_AD_RESOURCEenvironment variable. -
environment(string: 'AzurePublicCloud')- The Azure cloud environment. Valid values: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud. This value can also be provided with theAZURE_ENVIRONMENTenvironment variable.
-
-
To create the Azure auth role, run:
:~$ vault write auth/azure/role/my-role \
> policies="default" \
> bound_subscription_ids=<subscription_id> \
> bound_resource_groups=Vault-Auth-Test_group -
To generate the JWT from the VM, login to the shell of the VM and run:
response=$(curl '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 -s)
access_token=$(echo $response | python -c 'import sys, json; print (json.load(sys.stdin)["access_token"])')
echo $access_token -
An access token contains claims that you can use in Azure Active Directory to identify the granted permissions to your APIs. To call a resource server, the HTTP request must include an access token. An access token is denoted as access_token in the responses from Azure AD.
- To login against the configured Azure auth, run:
:~$ vault write auth/azure/login \
role="my-role" \
jwt="$access_token" \
resource_group_name=Vault-Auth-Test_group \
vm_name=Vault-Auth-Test
Output:
Key Value
--- -----
token hvs.CAESIL6-wPEfLfI_J-cvNQhyGsLlURlwRFvhIoWhh8HLIJgRGiEKHGh2cy5oaGF6alVUM2lHQWNvbDlObUExU08zaDEQigI
token_accessor qSK361VGNNBcdXuohxfgMpJq
token_duration 768h
token_renewable true
token_policies ["default"]
identity_policies []
policies ["default"]
token_meta_role my-role
token_meta_subscription_id <Subscription ID>
token_meta_vm_name Vault-Auth-Test
token_meta_resource_group_name Vault-Auth-Test_group -
To read the generated token, run:
:~$ vault token lookup hvs.CAESIL6-wPEfLfI_J-cvNQhyGsLlURlwRFvhIoWhh8HLIJgRGiEKHGh2cy5oaGF6alVUM2lHQWNvbDlObUExU08zaDEQigI
Key Value
--- -----
accessor qSK361VGNNBcdXuohxfgMpJq
creation_time 1690119390
creation_ttl 768h
display_name azure-cd029f41-21b0-4928-a0bb-e91456ba7aa3
entity_id 8dd71fb5-7778-0f89-8410-344f367ec25b
expire_time 2023-08-24T19:06:30.307757372+05:30
explicit_max_ttl 0s
id hvs.CAESIL6-wPEfLfI_J-cvNQhyGsLlURlwRFvhIoWhh8HLIJgRGiEKHGh2cy5oaGF6alVUM2lHQWNvbDlObUExU08zaDEQigI
issue_time 2023-07-23T19:06:30.307761831+05:30
meta map[resource_group_name:Vault-Auth-Test_group role:my-role subscription_id:a51e73e8-caf2-4c26-b139-c835214a1f47 vm_name:Vault-Auth-Test]
num_uses 0
orphan true
path auth/azure/login
policies [default]
renewable true
ttl 767h55m8s
type service
Azure Rotate-Root Credentials
- The service Principal used to config Azure auth must have the following permissions for Vault to perform the client_secret rotation.
- To rotate the client_secret, run:
:~$ vault write -f auth/azure/rotate-root