Merge pull request #118156 from katriendg/patch-2

AIO - Manage Secrets - adding preconfigure service principal and key vault policies

Author: Jak-MS

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/06/2023
+ms.date: 12/19/2023
 ms.custom:
   - ignite-2023
 
@@ -26,6 +26,107 @@ Azure IoT Operations supports Azure Key Vault for storing secrets and certificat
 
 For more information, see [Deploy Azure IoT Operations extensions](./howto-deploy-iot-operations.md?tabs=cli).
 
+## Configure service principal and Azure Key Vault upfront
+
+If the Azure account executing the `az iot ops init` command does not have permissions to query the Azure Resource 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
+
+Follow these steps to create a new Application Registration that will be used by the AIO application to authenticate to Key Vault.
+
+First, register an application with Microsoft Entra ID.
+
+1. In the Azure portal search bar, search for and select **Microsoft Entra ID**.
+
+1. Select **App registrations** from the **Manage** section of the Microsoft Entra ID menu.
+
+1. Select **New registration**.
+
+1. On the **Register an application** page, provide the following information:
+
+   | Field | Value |
+   | ----- | ----- |
+   | **Name** | Provide a name for your application. |
+   | **Supported account types** | Ensure that **Accounts in this organizational directory only (<YOUR_TENANT_NAME> only - Single tenant)** is selected. |
+   | **Redirect URI** | Select **Web** as the platform. You can leave the web address empty. |
+
+1. Select **Register**.
+
+   When your application is created, you are directed to its resource page.
+
+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.
+
+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.
+
+1. Select **Add a permission**.
+
+1. On the **Request API permissions** page, scroll down and select **Azure Key Vault**.
+
+1. Select **Delegated permissions**.
+
+1. Check the box to select **user_impersonation** permissions.
+
+1. Select **Add permissions**.
+
+Create a client secret that will be 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.
+
+1. Select **New client secret**.
+
+1. Provide an optional description for the secret, then select **Add**.
+
+1. Copy the **Value** and **Secret ID** from your new secret. You'll use these values later below.
+
+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`.
+
+### Create an Azure Key Vault
+
+Create a new Azure Key Vault service and ensure 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>"
+```
+If you have an existing key vault, you can change the permission model by executing the following:
+
+```bash
+az keyvault update --name "<your unique key vault name>" --resource-group "<the name of the resource group>" --enable-rbac-authorization false 
+```
+You will need the Key Vault resource ID when you run `az iot ops init`. To retrieve the resource ID, run:
+
+```bash
+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 Azue 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. 
+
+Run the following to assign **secret** `get` and `list` 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
+```
+
+### 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 will 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.
+
+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.
+
+```bash
+az iot ops init --name "<your unique key vault name>" --resource-group "<the name of the resource group>" \
+    --kv-id <Key Vault Resource ID> \
+    --sp-app-id <Application registration App ID (client ID) from Microsoft Entra ID> \
+    --sp-object-id <Object ID copied from Enterprise Application in Microsoft Entra ID> \
+    --sp-secret "<Client Secret from App registration in Microsoft Entra ID>" \
+    --no-deploy
+```
+
 ## 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.