Merge pull request #268792 from kgremban/mar12-secrets

Update manage secrets

Author: prmerger-automator[bot]

articles/iot-operations/deploy-iot-ops/howto-manage-secrets.md

@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.subservice: orchestrator
 ms.topic: how-to
-ms.date: 12/19/2023
+ms.date: 03/21/2024
 ms.custom: ignite-2023, devx-track-azurecli
 
 #CustomerIntent: As an IT professional, I want prepare an Azure-Arc enabled Kubernetes cluster with Key Vault secrets so that I can deploy Azure IoT Operations to it.
@@ -23,17 +23,17 @@ Secrets management in Azure IoT Operations Preview uses Azure Key Vault as the m
 
 ## Configure a secret store on your cluster
 
-Azure IoT Operations supports Azure Key Vault for storing secrets and certificates. The `az iot ops init` Azure CLI command automates the steps to create a key vault, set up a service principal to give access to the key vault, and configure the secrets that you need for running Azure IoT Operations.
+Azure IoT Operations supports Key Vault for storing secrets and certificates. The `az iot ops init` Azure CLI command automates the steps to set up a service principal to give access to the key vault and configure the secrets that you need for running Azure IoT Operations.
 
 For more information, see [Deploy Azure IoT Operations Preview extensions to a Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md?tabs=cli).
 
-## Configure service principal and Azure Key Vault upfront
+## Configure service principal and Key Vault manually
 
 If the Azure account executing the `az iot ops init` command doesn't have permissions to query the Microsoft Graph and create service principals, you can prepare these upfront and use extra arguments when running the CLI command as described in [Deploy Azure IoT Operations extensions](./howto-deploy-iot-operations.md?tabs=cli).
 
-### Configure service principal for interacting with Azure Key Vault via Microsoft Entra ID
+### Configure service principal for interacting with Key Vault via Microsoft Entra ID
 
-Follow these steps to create a new Application Registration that will be used by the AIO application to authenticate to Key Vault.
+Follow these steps to create a new Application Registration for the Azure IoT Operations application to use to authenticate to Key Vault.
 
 First, register an application with Microsoft Entra ID:
 
@@ -57,7 +57,7 @@ First, register an application with Microsoft Entra ID:
 
 1. Copy the **Application (client) ID** from the app registration overview page. You'll use this value as an argument when running Azure IoT Operations deployment with the `az iot ops init` command.
 
-Next, give your application permissions for key vault:
+Next, give your application permissions for Key Vault:
 
 1. On the resource page for your app, select **API permissions** from the **Manage** section of the app menu.
 
@@ -71,7 +71,7 @@ Next, give your application permissions for key vault:
 
 1. Select **Add permissions**.
 
-Create a client secret that will be added to your Kubernetes cluster to authenticate to your key vault:
+Create a client secret that is added to your Kubernetes cluster to authenticate to your key vault:
 
 1. On the resource page for your app, select **Certificates & secrets** from the **Manage** section of the app menu.
 
@@ -83,11 +83,11 @@ Create a client secret that will be added to your Kubernetes cluster to authenti
 
 Retrieve the service principal Object ID:
 
-1. On the **Overview** page for your app, under the section **Essentials**, click on the **Application name** link under **Managed application in local directory**. This opens the Enterprise Application properties. Copy the Object ID to use when you run `az iot ops init`.
+1. On the **Overview** page for your app, under the **Essentials** section, select the **Application name** link under **Managed application in local directory**. This opens the Enterprise Application properties. Copy the Object ID to use when you run `az iot ops init`.
 
-### Create an Azure Key Vault
+### Create a key vault
 
-Create a new Azure Key Vault service and ensure it has the **Permission Model** set to Vault access policy.
+Create a new Azure Key Vault instance and ensure that it has the **Permission Model** set to **Vault access policy**.
 
 ```bash
 az keyvault create --enable-rbac-authorization false --name "<your unique key vault name>" --resource-group "<the name of the resource group>"
@@ -103,19 +103,24 @@ You'll need the Key Vault resource ID when you run `az iot ops init`. To retriev
 az keyvault show --name "<your unique key vault name>" --resource-group "<the name of the resource group>" --query id  -o tsv
 ```
 
-### Set service principal access policy in Azure Key Vault
+### Set service principal access policy in Key Vault
 
-The newly created service principal needs **Secret** `list` and `get` access policy for the Azure IoT Operations to work with the secret store. 
+The newly created service principal needs **secret** `list` and `get` access policy for the Azure IoT Operations to work with the secret store. 
 
-Run the following to assign **secret** `get` and `list` permissions to the service principal.
+To manage Key Vault access policies, the principal logged in to the CLI needs sufficient Azure permissions. In the Role Based Access Control (RBAC) model, this permission is included in Key Vault contributor or higher roles.
+
+>[!TIP]
+>If you used the logged-in CLI principal to create the key vault, then you probably already have the right permissions. However, if you're pointing to a different or existing key vault then you should check that you have sufficient permissions to set access policies.
+
+Run the following to assign **secret** `list` and `get` permissions to the service principal.
 
 ```bash
-az keyvault set-policy --name "<your unique key vault name>" --resource-group "<the name of the resource group>" --object-id <Object ID copied from Enterprise Application SP in Microsoft Entra ID> --secret-permissions get list --key-permissions get list
+az keyvault set-policy --name "<your unique key vault name>" --resource-group "<the name of the resource group>" --object-id <Object ID copied from Enterprise Application SP in Microsoft Entra ID> --secret-permissions get list
 ```
 
 ### Pass service principal and Key Vault arguments to Azure IoT Operations deployment
 
-When following the guide [Deploy Azure IoT Operations extensions](./howto-deploy-iot-operations.md?tabs=cli), you'll need to pass in additional flags to the `az iot ops init` command in order to use the pre-configured service principal and key vault.
+When following the guide [Deploy Azure IoT Operations extensions](./howto-deploy-iot-operations.md?tabs=cli), pass in additional flags to the `az iot ops init` command in order to use the preconfigured service principal and key vault.
 
 The following example shows how to prepare the cluster for Azure IoT Operations without fully deploying it by using `--no-deploy` flag. You can also run the command without this argument for a default Azure IoT Operations deployment.
 
@@ -128,9 +133,11 @@ az iot ops init --name "<your unique key vault name>" --resource-group "<the nam
     --no-deploy
 ```
 
+One step that the `init` command takes is to ensure all Secret Provider Classes (SPCs) required by Azure IoT Operations have a default secret configured in key vault. If a value for the default secret does not exist `init` will create one. This step requires that the principal logged in to the CLI has secret `set` permissions. If you want to use an existing secret as the default SPC secret, you can specify it with the `--kv-sat-secret-name` parameter, in which case the logged in principal only needs secret `get` permissions.
+
 ## Add a secret to an Azure IoT Operations component
 
-Once you have the secret store set up on your cluster, you can create and add Azure Key Vault secrets.
+Once you have the secret store set up on your cluster, you can create and add Key Vault secrets.
 
 1. Create your secret in Key Vault with whatever name and value you need. You can create a secret by using the [Azure portal](https://portal.azure.com) or the [az keyvault secret set](/cli/azure/keyvault/secret#az-keyvault-secret-set) command.
 
@@ -167,4 +174,4 @@ kubectl delete pod aio-dp-runner-worker-0 -n azure-iot-operations
 
 ## Azure IoT MQ Preview secrets
 
-The steps to manage secrets with Azure Key Vault for Azure IoT MQ Preview are different. For more information, see [Manage Azure IoT MQ secrets using Azure Key Vault](../manage-mqtt-connectivity/howto-manage-secrets.md).
+The steps to manage secrets with Azure Key Vault for Azure IoT MQ Preview are different. For more information, see [Manage MQ secrets using Key Vault](../manage-mqtt-connectivity/howto-manage-secrets.md).