Public documentation for secret archive settings

lb4368 · lb4368 · commit 6e133c8c3ce6 · 2024-11-06T13:02:30.000-06:00
diff --git a/articles/operator-nexus/how-to-credential-manager-key-vault.md b/articles/operator-nexus/how-to-credential-manager-key-vault.md
@@ -11,7 +11,7 @@ ms.custom: template-how-to, devx-track-azurecli
 
 # Set up Key Vault for Managed Credential Rotation in Operator Nexus
 
-Azure Operator Nexus utilizes secrets and certificates to manage component security across the platform. The Operator Nexus platform handles the rotation of these secrets and certificates. By default, Operator Nexus stores the credentials in a managed Key Vault. To keep the rotated credentials in their own Key Vault, the user has to set up the Key Vault for the Azure Operator Nexus instance. Once created, the user needs to add a role assignment on the Customer Key Vault to allow the Operator Nexus Platform to write updated credentials, and additionally link the Customer Key Vault to the Nexus Cluster Resource.
+Azure Operator Nexus utilizes secrets and certificates to manage component security across the platform. The Operator Nexus platform handles the rotation of these secrets and certificates. By default, Operator Nexus stores the credentials in a managed Key Vault. To keep the rotated credentials in their own Key Vault, the user has the option to configure their own Key Vault to receive rotated credentials.  This requires the user to set up the Key Vault for the Azure Operator Nexus instance. Once created, the user needs to add a role assignment on the Customer Key Vault to allow the Operator Nexus Platform to write updated credentials, and additionally link the Customer Key Vault to the Nexus Cluster Resource.
 
 ## Prerequisites
 
@@ -22,9 +22,9 @@ Azure Operator Nexus utilizes secrets and certificates to manage component secur
 > [!NOTE]
 > A single Key Vault can be used for any number of clusters.
 
-## Configure Managed Identity for Cluster Manager
+## Configure Key Vault Using Managed Identity for Cluster Manager
 
-Beginning with the 2024-06-01-public-preview API, managed identities are used in the Cluster Manager for write access to rotated credentials to a key vault. The Cluster Manager identity can be system-assigned or [user-assigned](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities), and can be managed directly via APIs or via CLI.
+Starting with the 2024-07-01 API version, managed identities in the Cluster Manager are used for write access to deliver rotated credentials to a key vault. The Cluster Manager identity may be system-assigned or [user-assigned](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities), and can be managed directly via APIs or via CLI.
 
 These examples describe how to configure a managed identity for a Cluster Manager.
 
@@ -45,18 +45,38 @@ These examples describe how to configure a managed identity for a Cluster Manage
         --resource-group <Resource Group Name> --mi-user-assigned "/subscriptions/subscriptionId/resourceGroups/resourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUAI"
 ```
 
-- Add system assigned identity to Cluster Manager
+- Add system-assigned identity to Cluster Manager
 ```
         az networkcloud clustermanager update --name <Cluster Manager Name> --resource-group <Resource Group Name> --mi-system-assigned
 ```
 
-- Add user assigned identity to Cluster Manager
+- Add user-assigned identity to Cluster Manager
 ```
         az networkcloud clustermanager update --name <Cluster Manager Name> --resource-group <Resource Group Name> \
         --mi-user-assigned "/subscriptions/subscriptionId/resourceGroups/resourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUAI"
 ```
 
-## Get the Principal ID for the Managed Identity
+### Configure Nexus Cluster Secret Archive
+
+Register the Customer Key Vault as the secret archive for the Nexus cluster. The key vault resource ID must be configured in the cluster and enabled to store the secrets of the cluster.
+
+Example:
+
+```console
+# Set and enable Customer Key Vault on Nexus cluster
+az networkcloud cluster update --ids /subscriptions/<subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.NetworkCloud/clusters/<Nexus Cluster Name> --secret-archive "{key-vault-id:<Key Vault Resource ID>,use-key-vault:true}"
+
+# Show Customer Key Vault setting (secretArchive) on the Nexus cluster
+az networkcloud cluster show --ids /subscriptions/<subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.NetworkCloud/clusters/<Nexus Cluster Name> --query secretArchive
+```
+
+For more help:
+
+```console
+az networkcloud cluster update --secret-archive ?? --help
+```
+
+### Get the Principal ID for the Cluster Manager Managed Identity
 
 Once a managed identity is configured, use the CLI to view the identity and the associated principal ID data within the cluster manager.
 
@@ -88,41 +108,156 @@ User-assigned identity example:
     },
 ```
 
-## Writing Credential Updates to a Customer Key Vault on Nexus Cluster
+Refer to [_Grant Managed Identity Access to a Key Vault for Credential Rotation_](#grant-managed-identity-access-to-a-key-vault-for-credential-rotation) to assign the appropriate role to the Managed Identity Principal ID.
 
-- Assign the *Operator Nexus Key Vault Writer Service Role*. Ensure that *Azure role-based access control* is selected as the permission model for the key vault on the *Access configuration* view. Then from the *Access Control* view, select to add a role assignment.
+## Configure Key Vault Using Managed Identity for Cluster
 
-| Role Name                                              | Role Definition ID                   |
-|:-------------------------------------------------------|:-------------------------------------|
-| Operator Nexus Key Vault Writer Service Role (Preview) | 44f0a1a8-6fea-4b35-980a-8ff50c487c97 |
+> [!IMPORTANT]
+> Please note that this method for configuring a key vault for credential rotation is in preview. **This method can only be used with key vault that do not have firewall enabled.** If your environment requires the key vault firewall be enabled, use the existing [Cluster Manager]() identity method.
 
-Example:
+Beginning with the 2024-10-01-preview API, managed identities in the Nexus Cluster resource can be used instead of Cluster Manager. The Cluster identity may be system-assigned or [user-assigned](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities), and can be managed directly via APIs or via CLI.
 
-```console
-az role assignment create --assignee <Managed Identity Principal Id> --role 44f0a1a8-6fea-4b35-980a-8ff50c487c97 --scope /subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.KeyVault/vaults/<Key Vault Name>
+> [!NOTE]
+> If Nexus Cluster managed identity is configured for the key vault, then these settings will supersede settings configured in [_Configure Key Vault Using Managed Identity for Cluster Manager_](#configure-key-vault-using-managed-identity-for-cluster-manager)
+
+These examples describe how to configure a managed identity for a Nexus Cluster.
+
+- Create Nexus Cluster with system-assigned identity
+```azurecli-interactive
+az networkcloud cluster create --name "<cluster-name>" \
+  --resource-group "<cluster-resource-group>" \
+  ...
+  --mi-system-assigned \
+  ...
+  --subscription "<subscription>"
+```
+
+- Create Nexus Cluster with user-assigned identity
+```azurecli-interactive
+az networkcloud cluster create --name "<cluster-name>" \
+  --resource-group "<cluster-resource-group>" \
+  ...
+  --mi-user-assigned "<user-assigned-identity-resource-id>" \
+  ...
+  --subscription "<subscription>"
+```
+
+- Update existing Nexus Cluster with system-assigned identity
+```azurecli-interactive
+az networkcloud cluster update --ids <cluster-resource-id> --mi-system-assigned
 ```
 
-- User associates the Customer Key Vault with the Operator Nexus cluster. The key vault resource ID must be configured in the cluster and enabled to store the secrets of the cluster.
+- Update existing Nexus Cluster with user-assigned identity
+```azurecli-interactive
+az networkcloud cluster update --ids <cluster-resource-id> --mi-user-assigned "<user-assigned-identity-resource-id>"
+```
+
+### Configure Nexus Cluster Secret Archive Settings
+
+Register the Key Vault URI and managed identity to be used in the secret archive settings for the Nexus cluster.
+
+> [!NOTE]
+> Secret archive settings specify the Key Vault URI, not the Key Vault resource ID, and the managed identity specfied must be configured for the Nexus Cluster.
+
+Example:
+
+- Using a system-assigned identity:
+
+  ```azurecli
+  az rest --method PATCH --url ${CLUSTER_ID}?api-version=2024-10-01-preview --body @./sami-body.json
+  ```
+
+  The request body (sami-body.json) example:
+  
+  ```azurecli
+  {
+    "properties": {
+      "secretArchiveSettings": {
+        "vaultUri": "https://<key vault name>.vault.azure.net/",
+        "associatedIdentity": {
+            "identityType": "SystemAssignedIdentity"
+        }
+      }
+    }
+  }
+  ```
+
+- Using a user-assigned identity:
+
+  ```azurecli
+  az rest --method PATCH --url ${CLUSTER_ID}?api-version=2024-10-01-preview --body @./uami-body.json
+  ```
+
+  The request body (uami-body.json) example:
+  
+  ```azurecli
+  {
+    "properties": {
+      "secretArchiveSettings": {
+        "vaultUri": "https://<key vault name>.vault.azure.net/",
+        "associatedIdentity": {
+            "identityType": "UserAssignedIdentity",
+            "userAssignedIdentityResourceId": "<user-assigned-identity-resource-id>"
+        }
+      }
+    }
+  }
+  ```
+
+### Get the Principal ID for the Cluster Managed Identity
+
+Once a managed identity is configured for the Nexus Cluster, use the CLI to view the identity and get the _principalId_ for the managed identity specified in the secret archive settings.
 
 Example:
 
 ```console
-# Set and enable Customer Key Vault on Nexus cluster
-az networkcloud cluster update --ids /subscriptions/<subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.NetworkCloud/clusters/<Nexus Cluster Name> --secret-archive "{key-vault-id:<Key Vault Resource ID>,use-key-vault:true}"
+az networkcloud cluster show --ids <cluster-resource-id>
+```
 
-# Show Customer Key Vault setting (secretArchive) on the Nexus cluster
-az networkcloud cluster show --ids /subscriptions/<subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.NetworkCloud/clusters/<Nexus Cluster Name> --query secretArchive
+System-assigned identity example:
+```
+    "identity": {
+        "principalId": "2cb564c1-b4e5-4c71-bbc1-6ae259aa5f87",
+        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
+        "type": "SystemAssigned"
+    },
 ```
 
-For more help:
+User-assigned identity example:
+```
+    "identity": {
+        "type": "UserAssigned",
+        "userAssignedIdentities": {
+            "/subscriptions/<subscriptionID>/resourcegroups/<resourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<userAssignedIdentityName>": {
+                "clientId": "e67dd610-99cf-4853-9fa0-d236b214e984",
+                "principalId": "8e6d23d6-bb6b-4cf3-a00f-4cd640ab1a24"
+            }
+        }
+    },
+```
+
+Refer to [_Grant Managed Identity Access to a Key Vault for Credential Rotation_](#grant-managed-identity-access-to-a-key-vault-for-credential-rotation) to assign the appropriate role to the Managed Identity Principal ID.
+
+## Grant Managed Identity Access to a Key Vault for Credential Rotation
+
+- Assign the *Operator Nexus Key Vault Writer Service Role*. Ensure that *Azure role-based access control* is selected as the permission model for the key vault on the *Access configuration* view. Then from the *Access Control* view, select to add a role assignment.
+
+| Role Name                                              | Role Definition ID                   |
+|:-------------------------------------------------------|:-------------------------------------|
+| Operator Nexus Key Vault Writer Service Role (Preview) | 44f0a1a8-6fea-4b35-980a-8ff50c487c97 |
+
+Example:
 
 ```console
-az networkcloud cluster update --secret-archive ?? --help
+az role assignment create --assignee <Managed Identity Principal Id> --role 44f0a1a8-6fea-4b35-980a-8ff50c487c97 --scope /subscriptions/<Subscription ID>/resourceGroups/<Resource Group Name>/providers/Microsoft.KeyVault/vaults/<Key Vault Name>
 ```
 
+If using a user-assigned managed identity, proceed to [add permission to user-assigned identity](#add-a-permission-to-user-assigned-identity)
+
 ## Add a permission to User-assigned identity
 
-When using a User-assigned identity, add the following role assignment to the UAI resource:
+When using a user-assigned managed identity, a customer is required to provision access to that identity for the Nexus platform.
+Specifically, `Microsoft.ManagedIdentity/userAssignedIdentities/assign/action` permission needs to be added to the User-assigned identity for `AFOI-NC-MGMT-PME-PROD` Microsoft Entra ID. It is a known limitation of the platform that will be addressed in the future.
 
 1. Open the Azure Portal and locate the User-assigned identity in question.
 2. Under **Access control (IAM)**, click **Add role assignment**.
