Skip to content

docs: add Azure RBAC role assignment best practice for Azure Key Vault #1688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maor-klir wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add Azure RBAC role assignment best practice for Azure Key Vault #1688

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba84f32
docs: add Azure RBAC role assignment best practice
maor-klir Dec 8, 2025
16ab86c
Update docs/book/src/quick-start.md
maor-klir Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion docs/book/src/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,16 +113,38 @@ az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${R

Set access policy for the AAD application or user-assigned managed identity to access the keyvault secret:

Microsoft [recommends](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-access-policy) for improved security to use the **Azure Role-Based Access Control (RBAC) permission model** instead of the legacy Key Vault access policy model when managing an Azure Key Vault.

If using Azure AD Application:

Key Vault access policy (legacy):

```bash
export APPLICATION_CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
az keyvault set-policy --name "${KEYVAULT_NAME}" \
--secret-permissions get \
--spn "${APPLICATION_CLIENT_ID}"
```

if using user-assigned managed identity:
Azure RBAC (the recommended approach):

The `Key Vault Secrets User` [built-in role](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli#azure-built-in-roles-for-key-vault-data-plane-operations) is sufficient and adheres to the principle of least privilege for fetching secret content from an Azure Key Vault with Azure Workload Identity.

> **Role description:** Read secret contents including secret portion of a certificate with private key. Only works for key vaults that use the 'Azure role-based access control' permission model.

```bash
export APPLICATION_CLIENT_ID="$(az ad sp list --display-name "${APPLICATION_NAME}" --query '[0].appId' -otsv)"
export KEYVAULT_RESOURCE_ID="$(az keyvault show --name "${KEYVAULT_NAME}" --query 'id' -otsv)"

az role assignment create \
--role "Key Vault Secrets User" \
--scope "${KEYVAULT_RESOURCE_ID}" \
--assignee "${APPLICATION_CLIENT_ID}"
```

If using user-assigned managed identity:

Key Vault access policy (legacy):

```bash
export USER_ASSIGNED_IDENTITY_CLIENT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --query 'clientId' -otsv)"
Expand All @@ -132,6 +154,18 @@ az keyvault set-policy --name "${KEYVAULT_NAME}" \
--object-id "${USER_ASSIGNED_IDENTITY_OBJECT_ID}"
```

Azure RBAC (the recommended approach):

```bash
export USER_ASSIGNED_IDENTITY_CLIENT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --query 'clientId' -otsv)"
export KEYVAULT_RESOURCE_ID="$(az keyvault show --name "${KEYVAULT_NAME}" --query 'id' -otsv)"

az role assignment create \
--role "Key Vault Secrets User" \
--scope "${KEYVAULT_RESOURCE_ID}" \
--assignee "${USER_ASSIGNED_IDENTITY_CLIENT_ID}"
```

## 5. Create a Kubernetes service account

Create a Kubernetes service account and annotate it with the client ID of the AAD application we created in step 4:
Expand Down