Merge pull request #275840 from yizha1/add_rabc

prmerger-automator[bot] · web-flow · commit f3e3184c7960 · 2024-06-05T05:50:40.000Z
docs: add Azure RBAC for access control
diff --git a/articles/container-registry/container-registry-tutorial-sign-build-push.md b/articles/container-registry/container-registry-tutorial-sign-build-push.md
@@ -64,6 +64,8 @@ In this tutorial:
 1. Configure AKV resource names.
 
     ```bash
+    AKV_SUB_ID=myAkvSubscriptionId
+    AKV_RG=myAkvResourceGroup
     # Name of the existing AKV used to store the signing keys
     AKV_NAME=myakv
     # Name of the certificate created in AKV
@@ -75,6 +77,8 @@ In this tutorial:
 2. Configure ACR and image resource names.
 
     ```bash
+    ACR_SUB_ID=myAcrSubscriptionId
+    ACR_RG=myAcrResourceGroup
     # Name of the existing registry example: myregistry.azurecr.io
     ACR_NAME=myregistry
     # Existing full domain of the ACR
@@ -95,28 +99,74 @@ az login
 
 To learn more about Azure CLI and how to sign in with it, see [Sign in with Azure CLI](/cli/azure/authenticate-azure-cli).
 
-## Assign access policy in AKV (Azure CLI)
+## Secure access permissions to ACR and AKV
 
-A user principal with the correct access policy permissions is needed to create a self-signed certificate and sign artifacts. This principal can be a user principal, service principal, or managed identity. At a minimum, this principal needs the following permissions:
+When working with ACR and AKV, it’s essential to grant the appropriate permissions to ensure secure and controlled access. You can authorize access for different entities, such as user principals, service principals, or managed identities, depending on your specific scenarios. In this tutorial, the access is authorized to a signed-in Azure user.
 
-- `Create` permissions for certificates
-- `Get` permissions for certificates
-- `Sign` permissions for keys
+### Authorize access to ACR
 
-In this tutorial, the access policy is assigned to a signed-in Azure user. To learn more about assigning policy to a principal, see [Assign Access Policy](/azure/key-vault/general/assign-access-policy).
+The `AcrPull` and `AcrPush` roles are required for signing container images in ACR.
 
-### Set the subscription that contains the AKV resource
+1. Set the subscription that contains the ACR resource
 
-```bash
-az account set --subscription <your_subscription_id>
-```
+    ```bash
+    az account set --subscription $ACR_SUB_ID
+    ```
 
-### Set the access policy in AKV
+2. Assign the roles
 
-```bash
-USER_ID=$(az ad signed-in-user show --query id -o tsv)
-az keyvault set-policy -n $AKV_NAME --certificate-permissions create get --key-permissions sign --object-id $USER_ID
-```
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az role assignment create --role "AcrPull" --role "AcrPush" --assignee $USER_ID --scope "/subscriptions/$ACR_SUB_ID/resourceGroups/$ACR_RG/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"
+    ```
+
+### Authorize access to AKV
+
+In this section, we’ll explore two options for authorizing access to AKV.
+
+#### Use Azure RBAC (Recommended)
+
+The following roles are required for signing using self-signed certificates:
+- `Key Vault Certificates Officer` for creating and reading certificates
+- `Key Vault Certificates User`for reading existing certificates
+- `Key Vault Crypto User` for signing operations
+
+To learn more about Key Vault access with Azure RBAC, see [Use an Azure RBAC for managing access](/azure/key-vault/general/rbac-guide).
+
+1. Set the subscription that contains the AKV resource
+
+    ```bash
+    az account set --subscription $AKV_SUB_ID
+    ```
+
+2. Assign the roles
+
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az role assignment create --role "Key Vault Certificates Officer" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"
+    ```
+
+#### Assign access policy in AKV (legacy)
+
+The following permissions are required for an identity:
+- `Create` permissions for creating a certificate
+- `Get` permissions for reading existing certificates
+- `Sign` permissions for signing operations
+
+To learn more about assigning policy to a principal, see [Assign Access Policy](/azure/key-vault/general/assign-access-policy).
+
+1. Set the subscription that contains the AKV resource:
+
+    ```bash
+    az account set --subscription $AKV_SUB_ID
+    ```
+
+2. Set the access policy in AKV:
+
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az keyvault set-policy -n $AKV_NAME --certificate-permissions create get --key-permissions sign --object-id $USER_ID
+    ```
 
 > [!IMPORTANT]
 > This example shows the minimum permissions needed for creating a certificate and signing a container image. Depending on your requirements, you may need to grant additional permissions.
diff --git a/articles/container-registry/container-registry-tutorial-sign-trusted-ca.md b/articles/container-registry/container-registry-tutorial-sign-trusted-ca.md
@@ -73,10 +73,11 @@ In this article:
 > [!NOTE]
 > This guide uses environment variables for convenience when configuring the AKV and ACR. Update the values of these environment variables for your specific resources.
 
-1. Configure AKV resource names. 
+1. Configure environment variables for AKV and certificates
 
     ```bash
-    # Name of the existing Azure Key Vault used to store the signing keys 
+    AKV_SUB_ID=myAkvSubscriptionId
+    AKV_RG=myAkvResourceGroup
     AKV_NAME=myakv 
     
     # Name of the certificate created or imported in AKV 
@@ -86,9 +87,11 @@ In this article:
     CERT_SUBJECT="CN=wabbit-networks.io,O=Notation,L=Seattle,ST=WA,C=US"
     ```
 
-2. Configure ACR and image resource names. 
+2. Configure environment variables for ACR and images. 
     
     ```bash
+    ACR_SUB_ID=myAcrSubscriptionId
+    ACR_RG=myAcrResourceGroup
     # Name of the existing registry example: myregistry.azurecr.io 
     ACR_NAME=myregistry 
     # Existing full domain of the ACR 
@@ -151,7 +154,28 @@ To import the certificate:
 > [!NOTE]
 > If the certificate does not contain a certificate chain after creation or importing, you can obtain the intermediate and root certificates from your CA vendor. You can ask your vendor to provide you with a PEM file that contains the intermediate certificates (if any) and root certificate. This file can then be used at step 5 of [signing container images](#sign-a-container-image-with-notation-cli-and-akv-plugin).
 
-## Sign a container image with Notation CLI and AKV plugin 
+## Sign a container image with Notation CLI and AKV plugin
+
+When working with ACR and AKV, it’s essential to grant the appropriate permissions to ensure secure and controlled access. You can authorize access for different entities, such as user principals, service principals, or managed identities, depending on your specific scenarios. In this tutorial, the access are authorized to a signed-in Azure user.
+
+### Authoring access to ACR
+
+The `AcrPull` and `AcrPush` roles are required for building and signing container images in ACR.
+
+1. Set the subscription that contains the ACR resource
+
+    ```bash
+    az account set --subscription $ACR_SUB_ID
+    ```
+
+1. Assign the roles
+
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az role assignment create --role "AcrPull" --role "AcrPush" --assignee $USER_ID --scope "/subscriptions/$ACR_SUB_ID/resourceGroups/$ACR_RG/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"
+    ```
+
+### Build and push container images to ACR
 
 1. Authenticate to your ACR by using your individual Azure identity.
 
@@ -162,50 +186,85 @@ To import the certificate:
 > [!IMPORTANT]
 > If you have Docker installed on your system and used `az acr login` or `docker login` to authenticate to your ACR, your credentials are already stored and available to notation. In this case, you don’t need to run `notation login` again to authenticate to your ACR. To learn more about authentication options for notation, see [Authenticate with OCI-compliant registries](https://notaryproject.dev/docs/user-guides/how-to/registry-authentication/).
 
-2. Build and push a new image with ACR Tasks. Always use `digest` to identify the image for signing, since tags are mutable and can be overwritten.
+1. Build and push a new image with ACR Tasks. Always use `digest` to identify the image for signing, since tags are mutable and can be overwritten.
 
     ```bash
     DIGEST=$(az acr build -r $ACR_NAME -t $REGISTRY/${REPO}:$TAG $IMAGE_SOURCE --no-logs --query "outputImages[0].digest" -o tsv)
     IMAGE=$REGISTRY/${REPO}@$DIGEST
     ```
 
-    In this tutorial, if the image has already been built and is stored in the registry, the tag serves as an identifier for that image for convenience.
+In this tutorial, if the image has already been built and is stored in the registry, the tag serves as an identifier for that image for convenience.
+
+```bash
+IMAGE=$REGISTRY/${REPO}@$TAG
+```
+
+### Authoring access to AKV
+
+#### Use Azure RBAC (Recommended)
+
+1. Set the subscription that contains the AKV resource
 
     ```bash
-    IMAGE=$REGISTRY/${REPO}@$TAG
+    az account set --subscription $AKV_SUB_ID
     ```
 
-3. Assign access policy in AKV using the Azure CLI
+1. Assign the roles
 
-   To sign a container image with a certificate in AKV, a principal must have authorized access to AKV. The principal can be a user principal, service principal, or managed identity. In this tutorial, we assign an access policy to a signed-in user. To learn more about assigning policy to a principal, see [Assign Access Policy](/azure/key-vault/general/assign-access-policy). 
-    
-   To set the subscription that contains the AKV resources, run the following command:
+    If the certificate contains the entire certificate chain, the principal must be assigned with the following roles: 
+    - `Key Vault Secrets User` for reading secrets
+    - `Key Vault Certificates User`for reading certificates
+    - `Key Vault Crypto User` for signing operations
 
-   ```bash
-   az account set --subscription <your_subscription_id>
-   ```
-    
-   If the certificate contains the entire certificate chain, the principal must be granted key permission `Sign`, secret permission `Get`, and certificate permissions `Get`. To grant these permissions to the principal:
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az role assignment create --role "Key Vault Secrets User" --role "Key Vault Certificates User" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"
+    ```
 
-   ```bash
-   USER_ID=$(az ad signed-in-user show --query id -o tsv)
-   az keyvault set-policy -n $AKV_NAME --key-permissions sign --secret-permissions get --certificate-permissions get --object-id $USER_ID
-   ```
-    
-   If the certificate doesn't contain the chain, the principal must be granted key permission `Sign`, and certificate permissions `Get`. To grant these permissions to the principal:
+    If the certificate doesn't contain the chain, the principal must be assigned with the following roles:
+    - `Key Vault Certificates User`for reading certificates
+    - `Key Vault Crypto User` for signing operations
+
+    ```bash
+    USER_ID=$(az ad signed-in-user show --query id -o tsv)
+    az role assignment create --role "Key Vault Certificates User" --role "Key Vault Crypto User" --assignee $USER_ID --scope "/subscriptions/$AKV_SUB_ID/resourceGroups/$AKV_RG/providers/Microsoft.KeyVault/vaults/$AKV_NAME"
+    ```
+
+To learn more about Key Vault access with Azure RBAC, see [Use an Azure RBAC for managing access](/azure/key-vault/general/rbac-guide).
+
+#### Use access policy (Legacy)
     
-   ```bash
-   USER_ID=$(az ad signed-in-user show --query id -o tsv)
-   az keyvault set-policy -n $AKV_NAME --key-permissions sign --certificate-permissions get --object-id $USER_ID
-   ```
+To set the subscription that contains the AKV resources, run the following command:
+
+```bash
+az account set --subscription $AKV_SUB_ID
+```
+
+If the certificate contains the entire certificate chain, the principal must be granted key permission `Sign`, secret permission `Get`, and certificate permissions `Get`. To grant these permissions to the principal:
+
+```bash
+USER_ID=$(az ad signed-in-user show --query id -o tsv)
+az keyvault set-policy -n $AKV_NAME --key-permissions sign --secret-permissions get --certificate-permissions get --object-id $USER_ID
+```
+
+If the certificate doesn't contain the chain, the principal must be granted key permission `Sign`, and certificate permissions `Get`. To grant these permissions to the principal:
+
+```bash
+USER_ID=$(az ad signed-in-user show --query id -o tsv)
+az keyvault set-policy -n $AKV_NAME --key-permissions sign --certificate-permissions get --object-id $USER_ID
+```
+
+To learn more about assigning policy to a principal, see [Assign Access Policy](/azure/key-vault/general/assign-access-policy). 
+
+### Sign container images using the certificate in AKV
 
-4. Get the Key ID for a certificate. A certificate in AKV can have multiple versions, the following command gets the Key ID for the latest version of the `$CERT_NAME` certificate.
+1. Get the Key ID for a certificate. A certificate in AKV can have multiple versions, the following command gets the Key ID for the latest version of the `$CERT_NAME` certificate.
 
    ```bash
    KEY_ID=$(az keyvault certificate show -n $CERT_NAME --vault-name $AKV_NAME --query 'kid' -o tsv) 
    ```
 
-5. Sign the container image with the COSE signature format using the Key ID. 
+1. Sign the container image with the COSE signature format using the Key ID. 
 
    If the certificate contains the entire certificate chain, run the following command:
 
@@ -220,7 +279,6 @@ To import the certificate:
    ```
 
    To authenticate with AKV, by default, the following credential types if enabled will be tried in order:
- 
    - [Environment credential](/dotnet/api/azure.identity.environmentcredential)
    - [Workload identity credential](/dotnet/api/azure.identity.workloadidentitycredential)
    - [Managed identity credential](/dotnet/api/azure.identity.managedidentitycredential)
@@ -241,7 +299,7 @@ To import the certificate:
    | Managed identity credential  | `managedid`                |
    | Azure CLI credential         | `azurecli`                 |
 
-6. View the graph of signed images and associated signatures. 
+1. View the graph of signed images and associated signatures. 
 
     ```bash
     notation ls $IMAGE
