Azure credential management with Vault

21min
|
Vault

Deployment

Dynamic secrets are a core feature in Vault. A class of dynamic secrets is on-demand, revocable, time-limited access credentials for cloud providers. For example, the Dynamic Secrets getting started tutorial demonstrated the AWS secrets engine to dynamically generate AWS credentials (access key ID and secret access key).

Challenge

To consume Azure services (e.g. Azure Kubernetes service), the client must have valid Azure credentials. Azure uses service principal to authenticate its users. An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. So each new application adds operational overhead as more service principals are required.

Solution

Automate the process by integrating your applications with Vault's Azure secrets engine. The applications ask Vault for Azure credential with a time-to-live (TTL) enforcing its validity so that the credentials are automatically revoked when they are no longer used.

Benefits

Each app instance can request unique, short-lived credentials. Unique credentials ensures isolated, auditable access and enable revocation of a single client. While short-lived reduces the time frame in which they are valid.

Note

This tutorial demonstrates the use of azure secrets engine to dynamically generate azure credentials.

Personas

The end-to-end scenario described in this tutorial involves two personas:

admin with privileged permissions to configure secrets engines
apps read the secrets from Vault

Prerequisites

This tutorial assumes the following:

You have a Microsoft Azure account
Vault installed

Policy requirements

Each persona requires a different set of capabilities. These are expressed in policies. If you are not familiar with policies, complete the policies tutorial.

Required Vault policies

The admin tasks require these capabilities.

# Mount secrets engines
path "sys/mounts/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Configure the azure secrets engine and create roles
path "azure/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Write ACL policies
path "sys/policies/acl/*" {
  capabilities = [ "create", "read", "update", "delete", "list" ]
}

# Manage tokens for verification
path "auth/token/create" {
  capabilities = [ "create", "read", "update", "delete", "list", "sudo" ]
}

The apps tasks require these capabilities.

path "azure/creds/edu-app" {
  capabilities = [ "read" ]
}

Lab setup

Note

If you do not have access to an HCP Vault Dedicated cluster, visit the Create a Vault Cluster on HCP tutorial.

Launch the HCP Portal and login.
Click Vault in the left navigation pane.
In the Vault clusters pane, click vault-cluster.
Under Cluster URLs, click Public Cluster URL.
In a terminal, set the VAULT_ADDR environment variable to the copied address.
```
$ export VAULT_ADDR=<Public_Cluster_URL>
```
Return to the Overview page and click Generate token.
Within a few moments, a new token will be generated.
Copy the Admin Token.
Return to the terminal and set the VAULT_TOKEN environment variable.
```
$ export VAULT_TOKEN=<token>
```
Set the VAULT_NAMESPACE environment variable to admin.
```
$ export VAULT_NAMESPACE=admin
```
The admin namespace is the top-level namespace automatically created by HCP Vault. All CLI operations default to use the namespace defined in this environment variable.

Type vault status to verify your connectivity to the Vault cluster.

$ vault status

Key                      Value
---                      -----
Recovery Seal Type       shamir
Initialized              true
Sealed                   false
Total Recovery Shares    1
Threshold                1
Version                  1.9.2+ent
Storage Type             raft
...snipped...

The HCP Vault Dedicated server is ready.

Create an Azure service principal and resource group

(Persona: admin)

To delegate the credential generation task to Vault, you need to give Vault privileged Azure credentials to perform the task. The following demonstrates the creation of a service principal.

Production

The service principal should be dedicated to the Vault secrets engine.

Invoking the rotate-root command will delete the existing client secret and generate a new secret known only to Vault.

Note

Refer to the online Azure documentation for more details.

Launch the Microsoft Azure Portal and sign in.
Select Azure Active Directory and select Properties.
Copy the Tenant ID.
In a terminal, set the variable TENANT_ID to the Tenant ID.
```
$ export TENANT_ID=<Tenant ID>
```
From the side navigation, select App registrations.
Select New registrations.
Enter a desired name in the Name field (e.g. vault-education).
Click Register.
Copy the Application (client) ID.
In a terminal, set the variable CLIENT_ID to the Application (client) ID.
```
$ export CLIENT_ID=<Client ID>
```
From the side navigation, select Certificate & secrets.
Under the Client secrets, click New client secret.
Enter a description in the Description field.
Click Add.
Copy the client secret value.
In a terminal, set the variable CLIENT_SECRET to the client secret value.
```
$ export CLIENT_SECRET=<Client secret>
```
From the side navigation, click API permissions.
Under Configured permissions, click Add a permission.
The Azure Secrets Engine documentation lists the Azure permissions need to be assigned.
Click Microsoft Graph.
Select Application permissions.
Add the following permissions.
Permission Name Type
Application.ReadWrite.OwnedBy Application
GroupMember.ReadWrite.All Application
Note
If you plan to use the rotate root credentials API, you'll need to change Application.ReadWrite.OwnedBy to Application.ReadWrite.All.
Click Add permissions.
Click Grant admin consent for azure to grant the permissions.
Click Yes to confirm consent.
Navigate to the Subscriptions blade.
Click the name of your subscription.
Copy the Subscription ID.
In a terminal, set the variable SUBSCRIPTION_ID to the Subscription ID.
```
$ export SUBSCRIPTION_ID=<Subscription ID>
```
From the side navigation, click Access control (IAM).
Click Add > Add a role assignment.
Select User Access Administrator and click Next.
Click Select members.
Enter your application name or application id in the Select field.
Click the application when it is displayed which will add the application to the Selected members list.
Click Select.
Click Review + assign, and then Review + assign gain.

Permission Name	Type
Application.ReadWrite.OwnedBy	Application
GroupMember.ReadWrite.All	Application

The application is created with the correct permissions and you have these identifiers and credentials:

Tenant ID
Client ID
Client Secret
Subscription ID

Resource Group

The secrets engine generates credentials within an Azure resource group.

Navigate to the Resource groups blade.
Click Create.
Choose the subscription from the Subscription select field.
Enter vault-education in the Resource group field.
Click Review + create.
The view changes to display the review page.
Click Create.

The resource group vault-education is created.

Configure Vault

With the necessary resources configured in Azure, you can configure the Azure secrets engine to dynamically generate Azure service principals.

Enable the Azure secrets engine

Enable the azure secrets engine at its default path.

$ vault secrets enable azure

The secrets engine is enabled at the path azure/. To enable the secrets engine at a different path requires that you use the -path parameter and the desired path.

Enable the azure secrets engine at the path named azure.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"type":"azure"}' \
   $VAULT_ADDR/v1/sys/mounts/azure

The data field defines the type, {"type":"azure"}, of secrets engine to enable. The requested URL, /v1/sys/mounts/azure, defines the path of the secrets engine.

Note

Additional configuration parameters may be provided to configure the secrets engine. The path as well may be modified to support your needs.

Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui) and then login.
Select Enable new engine.
Select Azure from the list, and then click Next.
Click Enable Engine to complete. This sets the path to be azure.

Note

In this tutorial, the azure secrets engine is enabled at the /azure path in Vault. However, it is possible to enable your secret engines at any location by entering your desired path in the Path text field.

Configure the Azure secrets engine

(Persona: admin)

The Azure secrets engine requires the credentials you generated in the create an Azure service principal and resource group step to communicate with Azure and generate service principals.

Verify that your Azure subscription ID, client ID, client ID, and tenant ID are stored as environment variables.

$ echo $SUBSCRIPTION_ID; echo $CLIENT_ID; echo $CLIENT_SECRET; echo $TENANT_ID

If any of those variables are missing their value, refer to the previous step and set them before proceeding.

Configure the Azure secrets engine with the Azure credentials.

$ vault write azure/config \
     subscription_id=$SUBSCRIPTION_ID  \
     client_id=$CLIENT_ID \
     client_secret=$CLIENT_SECRET \
     tenant_id=$TENANT_ID \
     use_microsoft_graph_api=true

Create an API request payload containing the Azure credentials.

$ tee payload.json <<EOF
{
  "subscription_id": "$SUBSCRIPTION_ID",
  "tenant_id": "$TENANT_ID",
  "client_id": "$CLIENT_ID",
  "client_secret": "$CLIENT_SECRET",
  "use_microsoft_graph_api": true
}
EOF

Configure the Azure secrets engine with the credentials.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/azure/config

Create a role

(Persona: admin)

A Vault role lets you configure either an existing service principal or a set of Azure roles.

Create a Vault role named, edu-app mapped to the Azure role named, Contributor in the vault-education resource group.

$ vault write azure/roles/edu-app ttl=1h azure_roles=-<<EOF
    [
      {
        "role_name": "Contributor",
        "scope": "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/vault-education"
      }
    ]
EOF

Create an API request payload specifying the role definition.
```
$ tee payload.json <<EOF
{
  "azure_roles": "[
    {
      \"role_name\": \"Contributor\",
      \"scope\":  \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/vault-education\"
    }
  ]",
  "ttl": 3600,
  "max_ttl": "24h"
}
EOF
```
This payload defines that the Vault role is mapped to the Azure role named, Contributor in the vault-education resource group. Credentials are generated with a time-to-live (TTL) of 1 hour and max TTL of 24 hours.

Create the Vault role with the path edu-app with the role defined within the payload.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data @payload.json \
   $VAULT_ADDR/v1/azure/roles/edu-app

The role named edu-app is created.

Request Azure credentials

The role generates credentials with a time-to-live (TTL) of 1 hour and max TTL of 24 hours.

Read credentials from the edu-app azure role.

$ vault read azure/creds/edu-app

Example output:

Key                Value
---                -----
lease_id           azure/creds/edu-app/EA2uTB98qAPR2BRSaasnmnja
lease_duration     1h
lease_renewable    true
client_id          074421c4-60b7-477c-9c5f-07e0925ba6a6
client_secret      Vw17Q~3u3ZRRUd.M4pP-Bl487.i4Fe1~jLpLT

The results display the credentials, its TTL, and the lease ID.

For applications (apps persona) to request credentials, it requires a Vault policy that grants access to this role. Define a policy named apps.
```
$ vault policy write apps - <<EOF
path "azure/creds/edu-app" {
  capabilities = [ "read" ]
}
EOF
```
The apps policy grants the read capability for requests to the path azure/creds/edu-app.
Create a variable named APPS_TOKEN to capture the token created with the apps policy attached.
```
$ APPS_TOKEN=$(vault token create -policy=apps -field=token)
```
Note
AppRole Pull Authentication tutorial demonstrates a more sophisticated way of generating a token for your apps.

Read credentials from the edu-app azure role with the APPS_TOKEN.

$ VAULT_TOKEN=$APPS_TOKEN vault read azure/creds/edu-app

Example output:

Key                Value
---                -----
lease_id           azure/creds/edu-app/W24u6d77acJbBzzf02iq6YHd
lease_duration     1h
lease_renewable    true
client_id          b43b4e84-5568-4efd-8ba5-cbd40936ba12
client_secret      iXK7Q~mFGn-MJjcXhGbevQCQPRhB2Hkg1QGAq

Read credentials from the edu-app azure role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request GET \
   $VAULT_ADDR/v1/azure/creds/edu-app | jq -r ".data"

Note

This example uses jq to process the JSON output for readability.

Example output:

{
  "client_id": "0478e592-8492-4ae5-bc16-6c7ba0541112",
  "client_secret": "F-Y7Q~m1fwJ4PscEq-xa84NhMddgNR7b1vRtG"
}

The results display the credentials, its TTL, and the lease ID.

For applications (apps persona) to request credentials require a Vault policy that grants access to this role. Define a stringified version of the policy definition in a file.
```
$ tee payload.json <<EOF
{
  "policy": "path \"azure/creds/edu-app\" {capabilities = [ \"read\" ]}"
}
EOF
```

Create a policy named apps.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request PUT \
   --data @payload.json \
   $VAULT_ADDR/v1/sys/policies/acl/apps

The apps policy grants the read capability for requests to the path azure/creds/edu-app.

Create a variable named APPS_TOKEN to capture the token created with the apps policy attached.

$ APPS_TOKEN=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request POST \
   --data '{"policies": ["apps"]}' \
   $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token")

Note

AppRole Pull Authentication tutorial demonstrates a more sophisticated way of generating a token for your apps.

Read credentials from the edu-app azure role with the APPS_TOKEN.

$ curl --header "X-Vault-Token: $APPS_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request GET \
   $VAULT_ADDR/v1/azure/creds/edu-app | jq -r ".data"

Example output:

{
  "client_id": "d286adc5-53cf-43bd-b36a-6f939c3bc9c9",
  "client_secret": "B0F7Q~COpioWx5FzPrZsp8~VnjH_5FiAxB1eS"
}

Click the Policies tab, and then select Create ACL policy.
Enter apps in the Name field.
Enter this policy in the Policy field.
```
path "azure/creds/edu-app" {
  capabilities = [ "read" ]
}
```
This policy grants the read capability for requests to the path azure/creds/edu-app.
Click Create Policy.
Click the Vault CLI shell icon (>_) to open a command shell.
Execute vault write auth/token/create policies=apps in the CLI shell to create a new token:
Copy and save the generated client token value.
Sign out of the Vault UI.
Now, sign into the Vault using the newly generated token you just copied.
Click the Vault CLI shell icon (>_) to open a command shell. Execute vault read azure/creds/edu-app in the CLI shell.

The results display the credentials, its TTL, and the lease ID. The credentials for this application (service principal) in the Azure Portal searching by its client_id.

Note

Re-run the command and notice that the role returns a new set of credentials. This means that each app instance acquires a unique set of Azure credentials.

Manage leases

(Persona: admin)

The credentials are managed by the lease ID and remain valid for the lease duration (TTL) or until revoked. Once revoked the credentials are no longer valid.

List the existing leases.

$ vault list sys/leases/lookup/azure/creds/edu-app

Example output:

Keys
----
o2F4EA3hU8Fpjgc39XyQpjtU
fRFeCtlMnoPqelTrjf5j5kGA

All valid leases for Azure credentials are displayed.

Create a variable that stores the first lease ID.

$ LEASE_ID=$(vault list -format=json sys/leases/lookup/azure/creds/edu-app | jq -r ".[0]")

Renew a lease

If you need to extend the use of the generated Azure credentials, you can renew the lease by passing its lease ID.

$ vault lease renew azure/creds/edu-app/$LEASE_ID

Example output:

Key                Value
---                -----
lease_id           azure/creds/edu-app/EA2uTB98qAPR2BRSaasnmnja
lease_duration     1h
lease_renewable    true

The TTL of the renewed lease is set to 1h.

Revoke the leases

When the Azure credentials are no longer needed, you can revoke the lease without waiting for its expiration.

Revoke the least associated with the $LEASE_ID environment variable.

$ vault lease revoke azure/creds/edu-app/$LEASE_ID

All revocation operations queued successfully!

List the existing leases.

$ vault list sys/leases/lookup/azure/creds/edu-app

fRFeCtlMnoPqelTrjf5j5kGA

The first lease is no longer valid.

Read new credentials from the edu-app role.
```
$ vault read azure/creds/edu-app
```
Revoke all the leases with the prefix azure/creds/edu-app.
```
$ vault lease revoke -prefix azure/creds/edu-app
```
The prefix flag matches all valid leases with the path prefix of azure/creds/edu-app.

List the existing leases.

$ vault list sys/leases/lookup/azure/creds/edu-app
No value found at sys/leases/lookup/azure/creds/edu-app

All the leases with this path as a prefix have been revoked.

List the existing lease IDs.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request LIST \
   $VAULT_ADDR/v1/sys/leases/lookup/azure/creds/edu-app | jq -r ".data.keys"

All valid leases for Azure credentials are displayed.

Example output:

[
  "w8KAdJGYmN4ysZVFHPgl6psT",
  "zKl9iK07Yf5qZtmg7qcM5Tgg"
]

Create a variable that stores the first (and only) lease ID.

$ LEASE_ID=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request LIST \
   $VAULT_ADDR/v1/sys/leases/lookup/azure/creds/edu-app | jq -r ".data.keys[0]")

Renew a lease

If you need to extend the use of the generated Azure credentials, you can renew the lease by passing its lease ID.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request PUT \
   --data "{ \"lease_id\": \"azure/creds/edu-app/$LEASE_ID\" }" \
   $VAULT_ADDR/v1/sys/leases/renew | jq

The TTL of the renewed lease is set to 1h.

Example output:

{
  "request_id": "7dee4bd8-73b6-f7f0-693f-78d3d38aef5c",
  "lease_id": "azure/creds/edu-app/w8KAdJGYmN4ysZVFHPgl6psT",
  "renewable": true,
  "lease_duration": 3600,
  "data": null,
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Revoke the leases

When the Azure credentials are no longer needed, you can revoke the lease without waiting for its expiration.

Revoke the lease without waiting for its expiration.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request PUT \
   --data "{ \"lease_id\": \"azure/creds/edu-app/$LEASE_ID\" }" \
   $VAULT_ADDR/v1/sys/leases/revoke

List the existing leases.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request LIST \
   $VAULT_ADDR/v1/sys/leases/lookup/azure/creds/edu-app | jq -r ".data.keys"

Example output:

[
  "zKl9iK07Yf5qZtmg7qcM5Tgg"
]

The deleted lease is no longer valid and is not displayed.

Read new credentials from the edu-app role.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request GET \
   $VAULT_ADDR/v1/azure/creds/edu-app | jq -r ".data"

Revoke all the leases with the prefix azure/creds/edu-app.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request PUT \
   $VAULT_ADDR/v1/sys/leases/revoke-prefix/azure/creds/edu-app

List the existing leases.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \
   --header "X-Vault-Namespace: $VAULT_NAMESPACE" \
   --request LIST \
   $VAULT_ADDR/v1/sys/leases/lookup/azure/creds/edu-app | jq

All the leases with this path as a prefix have been revoked; therefore, it returns an empty array.

{
  "errors": []
}

Clean up

The Azure credentials created to configure the secrets engine should be deleted if they are no longer required.

Launch the Microsoft Azure Portal and sign in.
Navigate to Azure Active Directory.
From the side navigation, select App registrations.
Click the vault-education application (or whatever the name you set for the application).
From the application overview, click delete.
Select Yes to delete the application. The application is deleted.
Navigate to Resource groups.
Click the vault-education resource group.
From the resource group overview, click Delete resource group.
Enter vault-education in the TYPE THE RESOURCE GROUP NAME: field.
Click Delete. The resource group is deleted.

Stop the Vault server

Unset the VAULT_TOKEN environment variable.
```
$ unset VAULT_TOKEN
```
Unset the VAULT_ADDR environment variable.
```
$ unset VAULT_ADDR
```
Vault Dedicated users: Unset the VAULT_NAMESPACE environment variable.
```
$ unset VAULT_NAMESPACE
```
Delete the Vault cluster from the HCP Portal.

Help and Reference

You enabled and configured the Azure secrets engine. Learn more by exploring the documentation or API documentation.

Azure Key Vault can auto-unseal the Vault server. Learn this through this Azure Key Vault Auto-unseal & Dynamic Secrets with HashiCorp Vault demonstration.

LDAP secrets engine

Build your own certificate authority (CA)