NFSAAS-149992: Add Portal instructions and troubleshooting for cross-tenant CMK

Author: netapp-manishc

articles/azure-netapp-files/customer-managed-keys-cross-tenant.md

@@ -6,7 +6,7 @@ author: b-ahibbard
 ms.service: azure-netapp-files
 ms.topic: how-to
 ms.custom: devx-track-azurecli, devx-track-azurepowershell
-ms.date: 09/03/2025
+ms.date: 02/17/2026
 ms.author: anfdocs
 # Customer intent: As an IT administrator managing Azure resources across multiple tenants, I want to configure cross-tenant customer-managed keys for volume encryption in Azure NetApp Files, so that I can enhance security and control over encryption keys used for sensitive data.
 ---
@@ -91,10 +91,22 @@ The configuration process for cross-tenant customer-managed keys has portions th
 
 ### Configure the NetApp account to use your keys 
 
->[!NOTE]
->Using the `az rest` command is the only supported way to configure your NetApp account to use CMK in a different tenant.
+> [!IMPORTANT]
+> If the NetApp account is currently configured with same-tenant customer-managed keys, you must first switch the account back to Microsoft-managed keys before configuring cross-tenant CMK. To switch, navigate to **Encryption** for the NetApp account in the Azure portal and change the encryption key source to **Microsoft-managed key**, then select **Save**.
 
-<!-- check API version preview -->
+#### [Portal](#tab/portal-configure)
+
+1. In the Azure portal, navigate to your NetApp account and select **Encryption**.
+1. On the **Encryption** page, select **Customer-managed key** as the encryption key source.
+1. Under **Key URI**, select **Enter key URI** and provide the URI of the encryption key from the customer's key vault in the other tenant.
+1. Under **Identity type**, select **User-assigned**.
+1. Select **Select an identity**, then choose the user-assigned managed identity you created earlier that has the federated credential configured.
+1. Under **Federated client ID**, enter the application (client) ID of the multitenant application you created in step 1.
+1. Select **Save**.
+
+After saving, verify that the account is configured for cross-tenant CMK by checking the account's JSON view for the presence of `federatedClientId` in the encryption properties.
+
+#### [Azure CLI / REST API](#tab/cli-configure)
 
 1. With the `az rest` command, configure the NetApp account to use CMK in a different tenant:  
 
@@ -120,17 +132,100 @@ The configuration process for cross-tenant customer-managed keys has portions th
     ```
     Once you have sent the `az rest` command, your NetApp Account has been successfully configured with cross-tenant CMK. 
 
+    Verify the configuration by running:
+
+    ```azurecli
+    az netappfiles account show --resource-group <resourceGroupName> --name <NetAppAccountName> --query "{encryption: properties.encryption}" -o json
+    ```
+
+    The output should include `federatedClientId` in the encryption identity properties, confirming cross-tenant CMK is configured.
+
+---
+
 ### Create a volume 
 
->[!NOTE]
->To create a volume using cross-tenant CMK, you must use the Azure CLI.
+#### [Portal](#tab/portal-volume)
+
+1. From Azure NetApp Files, select **Volumes** and then **+ Add volume**.
+1. Follow the instructions in [Configure network features for an Azure NetApp Files volume](configure-network-features.md):
+    * [Set the Network Features option in volume creation page](configure-network-features.md#set-the-network-features-option).
+    * The network security group for the volume's delegated subnet must allow incoming traffic from NetApp's storage VM.
+1. For a NetApp account configured with cross-tenant customer-managed keys, the **Create Volume** page includes the **Encryption Key Source** option.
+    * Select **Customer-Managed Key** in the **Encryption Key Source** dropdown menu.
+    * When you create a volume using a customer-managed key, you must also select **Standard** for the **Network features** option. Basic network features aren't supported.
+    * Select a **key vault private endpoint**. The dropdown menu displays private endpoints in the selected virtual network. If there's no private endpoint for the customer's key vault in the selected virtual network, the dropdown is empty. In this scenario, see [Azure Private Endpoint](../private-link/private-endpoint-overview.md).
+1. Continue to complete the volume creation process. Refer to:
+    * [Create an NFS volume](azure-netapp-files-create-volumes.md)
+    * [Create an SMB volume](azure-netapp-files-create-volumes-smb.md)
+    * [Create a dual-protocol volume](create-volumes-dual-protocol.md)
+
+#### [Azure CLI](#tab/cli-volume)
 
-1. Create the volume using the CLI: 
+Create the volume using the CLI: 
 
 ```azurecli
 az netappfiles volume create -g <resource group name> --account-name <NetApp account name> --pool-name <pool name> --name <volume name> -l southcentralus --service-level premium --usage-threshold 100 --file-path "<file path>" --vnet <virtual network name> --subnet default --network-features Standard --encryption-key-source Microsoft.KeyVault --kv-private-endpoint-id <full resource ID to the private endpoint to the customer's vault> --debug 
 ```
 
+---
+
+## Troubleshoot cross-tenant customer-managed keys
+
+This section describes common issues encountered when configuring cross-tenant CMK and how to resolve them.
+
+### Verify cross-tenant CMK configuration
+
+To confirm whether a NetApp account is correctly configured for cross-tenant CMK, check for the presence of `federatedClientId` in the account's encryption properties.
+
+#### Use the Azure CLI
+
+Run the following command to inspect the account's encryption configuration:
+
+```azurecli
+az netappfiles account show \
+    --resource-group <resourceGroupName> \
+    --name <NetAppAccountName> \
+    --query "{keySource: encryption.keySource, federatedClientId: encryption.identity.federatedClientId, userAssignedIdentity: encryption.identity.userAssignedIdentity}" \
+    -o json
+```
+
+The output should include:
+- `keySource` set to `Microsoft.KeyVault`
+- `federatedClientId` set to the application (client) ID of the multitenant application
+- `userAssignedIdentity` set to the resource ID of the user-assigned managed identity
+
+If `federatedClientId` is missing or `null`, the account is configured with same-tenant CMK, not cross-tenant CMK.
+
+#### Use the Azure portal
+
+Navigate to your NetApp account, select **Overview**, then select **JSON View**. The encryption properties include `federatedClientId` if cross-tenant CMK is correctly configured.
+
+### Missing Key URI or Encryption Key Source option in the portal
+
+**Symptom:** When creating a volume in the Azure portal, the **Encryption Key Source** dropdown menu doesn't show **Customer-Managed Key**, or fields for **Key URI**, **subscription**, or **identity type** aren't visible.
+
+**Cause:** This symptom typically occurs when the NetApp account is configured with same-tenant CMK instead of cross-tenant CMK, or the account hasn't been configured for CMK at all.
+
+**Resolution:**
+1. First, verify the current configuration using the CLI or portal JSON view as described in [Verify cross-tenant CMK configuration](#verify-cross-tenant-cmk-configuration).
+1. If the account is configured with same-tenant CMK (no `federatedClientId`), switch the account to Microsoft-managed keys first:
+    1. Navigate to the NetApp account's **Encryption** page in the Azure portal.
+    1. Change the encryption key source to **Microsoft-managed key**.
+    1. Select **Save**.
+1. Reconfigure the account for cross-tenant CMK by following the steps in [Configure the NetApp account to use your keys](#configure-the-netapp-account-to-use-your-keys).
+
+### Volume creation fails with cross-tenant CMK
+
+**Symptom:** Volume creation via REST API or portal fails with errors related to encryption key access.
+
+**Cause:** This can happen due to misconfigured federated identity, expired keys, or incorrect private endpoint configuration.
+
+**Resolution:**
+1. Verify the `federatedClientId` is correctly set using `az netappfiles account show`.
+1. Verify the multitenant application is installed in the customer tenant and has the correct key vault access (Get, Encrypt, Decrypt permissions).
+1. Verify the private endpoint to the customer's key vault is approved and connected.
+1. Verify the encryption key in the customer's key vault is active and not expired.
+
 ## Next steps
 * [Configure customer-managed keys](configure-customer-managed-keys.md)
 * [Understand data encryption in Azure NetApp Files](understand-data-encryption.md)