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 4 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
4 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
6d4197e
Update Key Vault access policy guidance
maor-klir Jan 8, 2026
c5004dc
docs: remove en-us locale prefix from Microsoft docs URLs
maor-klir Jun 16, 2026
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
31 changes: 22 additions & 9 deletions docs/book/src/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,25 +111,38 @@ az identity create --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${R

</details>

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

If using Azure AD Application:

Azure RBAC (the recommended approach):

The `Key Vault Secrets User` [built-in role](https://learn.microsoft.com/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)"
az keyvault set-policy --name "${KEYVAULT_NAME}" \
--secret-permissions get \
--spn "${APPLICATION_CLIENT_ID}"
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:
If using user-assigned managed identity:

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 USER_ASSIGNED_IDENTITY_OBJECT_ID="$(az identity show --name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --query 'principalId' -otsv)"
az keyvault set-policy --name "${KEYVAULT_NAME}" \
--secret-permissions get \
--object-id "${USER_ASSIGNED_IDENTITY_OBJECT_ID}"
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
Expand Down