Edit

Tutorial: Access a Key Vault secret with a managed identity with Azure CLI (preview)

In this tutorial, you use Azure CLI preview to give a workload access to a Key Vault secret through a user-assigned managed identity instead of a stored credential, confirm the access, and then revoke it.

When you finish, the workload has read the test secret by using its managed identity, the same read has failed after you revoked access, and no test identity or active test secret remains.

You run most steps on your workstation. You run the steps marked On the host on the Azure host, such as a VM, that runs the workload.

In this tutorial, you:

  • Create the application's identity
  • Store a test secret
  • Grant access
  • Read the secret as the application
  • Revoke access
  • Clean up

Warning

This walkthrough still requires engineering confirmation of the commands to attach and detach the identity on the host. Use these commands for engineering review only until those steps are supplied and validated. For more information about authentication support, see Get started with the preview.

Prerequisites

  • Bash or zsh on Linux or macOS, or PowerShell 7.6 or later on Windows.
  • Azure CLI preview, installed and signed in as described in Set up and switch sign-in profiles.
  • An Azure host, such as a VM, that can use a user-assigned managed identity and has the Azure CLI preview or modules installed.
  • An existing test Key Vault that uses Azure role-based access control and is reachable from that host.
  • The role definition ID of a built-in role that grants secret read access, and permission to assign it.

Use only synthetic secret values. Don't print or log secret values.

You need an Azure subscription. If you don't have one, create a free account.

Allow time for role changes to take effect before you verify a grant or a revocation. The managed-identity sign-in runs on the host, so set the same subscription, vault, secret, client ID, and run values there.

Set variables

sub="<test-subscription-id>"
location="<region>"
vault="<existing-test-vault-name>"
vault_id="<existing-test-vault-resource-ID>"
role="<secret-read-role-definition-ID>"
run=$(date +%Y%m%d%H%M%S)
rg="azclips-access-$run"
identity="app-identity-$run"
secret="app-secret-$run"
assignment=$(uuidgen)
identity_id="/subscriptions/$sub/resourceGroups/$rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$identity"
fixture="/tmp/$secret.txt"

Create the application's identity

az group create --subscription-id "$sub" --name "$rg" --location "$location"
az identity create --subscription "$sub" --resource-group "$rg" --name "$identity" --location "$location"
az identity show --ids "$identity_id"
principal_id=$(az identity show --ids "$identity_id" --query properties.principalId --output tsv)
client_id=$(az identity show --ids "$identity_id" --query properties.clientId --output tsv)

The az identity show output includes the identity's principal ID and client ID. You use the principal ID to grant access, and the client ID to sign in as the identity on the host.

Store a test secret

printf 'azclips-synthetic' > "$fixture"
az keyvault secret set --vault-name "$vault" --name "$secret" --file "$fixture"
az keyvault secret show --vault-name "$vault" --name "$secret"

Both commands return the secret's metadata, such as its ID and attributes, but not its value. az keyvault secret show returns the value only when you add --as-plain-text.

Grant access

az role assignment create --scope "$vault_id" --assignee-object-id "$principal_id" --assignee-principal-type ServicePrincipal --role "$role" --name "$assignment"
az role assignment list --scope "$vault_id" --assignee-object-id "$principal_id"

Attach the identity to the host: Pending engineering confirmation: command to attach the identity to the host.

The role assignment list includes one assignment for the identity's principal ID, with the role you specified, at the vault's scope.

Read the secret as the application

On the host:

az login --identity --client-id "$client_id" --subscription-id "$sub" --out-profile "workload-$run"
value=$(az keyvault secret show --vault-name "$vault" --name "$secret" --as-plain-text)
if [ "$value" = "azclips-synthetic" ]; then echo "Secret read succeeded"; else echo "Secret value mismatch" >&2; fi
unset value

The script prints Secret read succeeded without printing the secret value. If the read fails with an access-denied error, wait a few minutes for the role assignment to take effect, and then try again.

Revoke access

az role assignment delete --scope "$vault_id" --name "$assignment"
az role assignment list --scope "$vault_id" --assignee-object-id "$principal_id"

The role assignment list is empty. On the host, repeat the read from Read the secret as the application. After the revocation takes effect, the read fails with an access-denied (Forbidden) error. If the read still succeeds, wait a few minutes and try again.

Clean up resources

Detach the identity from the host: Pending engineering confirmation: command to detach the identity from the host.

az identity delete --ids "$identity_id"
az group delete --subscription-id "$sub" --name "$rg"
az group exists --subscription-id "$sub" --name "$rg"
az keyvault secret delete --vault-name "$vault" --name "$secret" --yes
rm -f "$fixture"

az group exists returns false, and the test secret is deleted. Key Vault keeps the deleted secret in a recoverable state for the vault's retention period.

On the host: Sign out and remove the workload profile:

az logout
az profile remove --name "workload-$run"