Update manage-oracle-transparent-data-encryption-azure-key-vault.md

articles/oracle/oracle-db/manage-oracle-transparent-data-encryption-azure-key-vault.md

@@ -4,94 +4,97 @@ description:  Comprehensive step-by-step guide for integrating Oracle Exadata Da
 author: jjaygbay1
 ms.service: oracle-on-azure
 ms.collection: linux
-ms.topic: overview
+ms.topic: how-to
 ms.date: 04/15/2025
 ms.custom: engagement-fy23
 ms.author: jacobjaygbay
 ---
 
-# Oracle Exadata Database with Azure Key Vault
-Exadata Database Service on Oracle Database@Azure now supports storing and managing Oracle Transparent Data Encryption (TDE) master encryption keys (MEK) using all three tiers of Azure Key Vault (AKV) services:
+# Integrate Oracle Exadata Database@Azure with Azure Key vault
+In this article, you learn to store and manage Oracle Transparent Data Encryption (TDE) master encryption keys (MEK) for Exadata Database Service on Oracle Database@Azure.  You can use all three tiers of the Azure Key Vault (AKV) services:  
 
 * **AKV Standard**
 * **AKV Premium**
 * **AKV Managed HSM**
 
 This integration enables Oracle Database@Azure customers to meet a wide spectrum of **security**, **compliance**, and **key management** needs - ranging from software-based key storage to single-tenant, FIPS 140-3 Level 3 validated hardware security modules.
 
-## Step-by-step integration guide
+:::image type="content" source="media\akv-on-odaa-architecture-diagram.png" alt-text="Architecure diagram for Oracle Database at Azure using Azure Key Vault"::: 
 
-Integrating **Oracle Database@Azure** (Exadata VM Cluster) with **Azure Key Vault** (AKV) allows you to store and manage Oracle Transparent Data Encryption (TDE) master encryption keys (MEK) in Azure’s secure vault, enhancing security and simplifying key lifecycle management.  
 
-## Prerequisites and assumptions
+## Prerequisites
 
 Before beginning the integration, ensure the following prerequisites are met:
 
-* **Oracle Database@Azure provisioned**: 
-You have an **Exadata VM cluster** deployed in Azure via Oracle Database@Azure. This includes a delegated subnet within an Azure Virtual Network for the Exadata VM Cluster. The cluster is up and running, and you have access to the Oracle Cloud Infrastructure (OCI) console for management.
-* **Advanced networking eEnabled**: If not already configured, complete the delegated subnet registration as per the [Network planning for Oracle Database@Azure | Microsoft Learn](/azure/oracle/oracle-db/oracle-database-network-plan) guide (This ensures the subnet supports Azure Arc and Private Link capabilities.)
-* **Azure Key Vault private connectivity**: Private Endpoint for Azure Key Vault has been configured and reachable by Exadata. DNS has also been configured, and endpoints can be resolved from Exadata. 
-* **NAT Gateway**: NAT Gateway must be configured on the delegated subnet to complete the Identity Connector setup.
+* **Oracle Database@Azure provisioned**: You have an Exadata VM cluster deployed in a delegated subnet within an Azure Virtual Network and you have access to the Oracle Cloud Infrastructure (OCI) console for management.
+* **Advanced networking enabled**:If not already configured, ensure Advanced Networking feature is enabled as per the [Network planning for Oracle Database@Azure | Microsoft Learn](/azure/oracle/oracle-db/oracle-database-network-plan)guide to enable Private Link connectivity required for Managed HSM and Azure Arc. 
+* **Azure Key Vault private connectivity**: Private Endpoint with DNS configuration for Azure Key Vault has been configured and reachable by Exadata. For details, see  [Integrate Key Vault with Azure Private Link | Microsoft Learn](/azure/key-vault/general/private-link-service)
+* **NAT Gateway**: Outbound internet connectivity is required for the Identity Connector setup to access Microsoft Entra Public endpoint. This connectivity can be achieved by using an Azure NAT gateway, Azure Firewall or a Network Virtual Appliance (NVA) of your choice if you do not have one in the same VNET as your Oracle deployment or in the shared HUB if using Hub/spoke topology. 
 * **Private Link Scope and Private Endpoint configuration for Azure Arc (optional)**: If using Private Link for the Azure Arc agent installation, the Azure Arc Private Link Scope and Private Endpoint must be configured and reachable from Exadata. DNS must also be configured and endpoints resolvable from Exadata.
 * **Azure subscription and permissions**: You have sufficient Azure permissions:
     * Azure role **Owner/contributor** on the subscription or resource group where Key Vault is created (to create resources and assign roles).
     * Microsoft Entra ID **User Administrator** (or equivalent) if you create security groups for managing permissions.
     * Azure **Global Administrator** is not required, but you should be able to obtain a Microsoft Entra ID access token for Arc registration (explained in Step 3).
-* **OCI privileges**: In OCI (Oracle Cloud Infrastructure console), ensure you have permission to manage the multicloud integration.
+* **OCI privileges**: In the Oracle Cloud Infrastructure (OCI) console, ensure that you have permission to manage the multicloud integration. Oracle recommends an IAM policy in your OCI tenancy such as: 
 
+   * *allow any-user to manage oracle-db-azure-vaults in tenancy*
+   * *where request.principal.type = 'cloudvmcluster'*  
+
+This IAM policy allows the Exadata VM Cluster resource to manage Key Vault associations. 
+
+>[!Note]
+>Your cloud administrator might have already set this up; otherwise, it must be added by an OCI admin before configuring the database to use Azure Key Vault. 
 ## Step 1: Create and prepare an Azure Key Vault
 
-**Goal**: Set up an Azure Key Vault to hold your Oracle database encryption keys. If you already have a suitable Key Vault and key, you can use it, but ensure it’s dedicated or appropriately secured for this purpose.
+Set up an Azure Key Vault to hold your Oracle database encryption keys. If you already have a suitable Key Vault and key, you can use it, but ensure it’s dedicated or appropriately secured for this purpose.
 
 1. **Create an Azure Key Vault**: You can use the Microsoft Azure portal or Azure CLI.  
     * **AKV Standard**: Follow [Azure Key Vault CLI Quickstart](/azure/key-vault/general/quick-create-cli)
     * **AKV Premium**: Same as Standard but select **Premium SKU**
     * **Managed HSM**: Follow [Managed HSM Quickstart](/azure/key-vault/managed-hsm/quick-create-cli)
 
-    Ensure the Key Vault’s region matches the region where Oracle Exadata Database@Azure is deployed (for performance and compliance). You can choose Standard or Premium tier (both support integration). Premium is HSM-backed. If you require a dedicated HSM cluster, use Managed HSM (in that case the creation command is different, as shown commented above, and remember Managed HSM requires private networking).
+    Ensure the Key Vault’s region matches the region where Oracle Exadata Database@Azure is deployed (for performance and compliance). You can choose Standard or Premium tier (both support integration). Premium is HSM-backed. If you require a dedicated HSM cluster, use Managed HSM (in that case the creation command is different, as shown above, and remember ManPrivate Endpoint is strongly recommended for secure access and enhanced access control).
 
 2. **Create a Key in the vault**: Oracle TDE requires an encryption key (Master Encryption Key) to be present in the vault. Create at least one key now. Oracle supports RSA keys for this purpose (2048-bit is typical):
 
-    Alternatively, you can import a key if you have specific requirements (BYOK), but for most cases generating a new RSA key in Azure is simplest. Make sure the key is enabled and note the key name. (Oracle later refers to this key by its Azure name when we link the database.)
+    Alternatively, you can import a key if you have specific requirements (BYOK), but for most cases generating a new RSA key in Azure is simplest. Make sure the key is enabled and note the key name. (Oracle later refers to this key by its Azure name when linking the database.)
+
+    **Why create the key now?** During vault registration, Oracle control plane checks that at least one key exists in the vault. If none is found, the vault registration fails. Creating a key upfront avoids that issue.
 
-    **Why create the key now?** During vault registration, Oracle’s process checks that at least one key exists in the vault. If none is found, the vault registration fails. Creating a key upfront avoids that issue.
+3. **(For Managed HSM)**: If you chose Managed HSM, after provisioning, you must activate the HSM (if not already) and create a key in it:
+      ```az keyvault key create --hsm-name <HSM_Name> -n $KEY_NAME ...```
 
-3. **(For Managed HSM)**: If you chose Managed HSM, after provisioning, you must activate the HSM (if not already) and create a key in it similarly (az keyvault key create --hsm-name <HSM_Name> -n $KEY_NAME ...). Also, note that Managed HSM uses a different permission model (local HSM roles). We’ll cover the role assignments in the next step.
+   Note that Managed HSM uses a different permission model (local HSM roles). We’ll cover the role assignments in the next step.
 
-    At this point, you have an Azure Key Vault (or HSM) ready, with a master key that is used for Oracle TDE. Next, we need to set up permissions so that the Oracle Exadata VM cluster can access this vault and key securely.
+    At this point, you have an Azure Key Vault (or HSM) ready, with a master key that is used for Oracle TDE. Next step is to set up permissions so that the Oracle Exadata VM cluster can access this vault and key securely.
 
 ## Step 2: Configure Microsoft Entra ID permissions for Key Vault access
 
-**Goal**: Allow the Oracle Exadata VM Cluster (specifically, the Azure Arc identity of its VMs) to access the Key Vault and perform key operations (like unwrap keys, create new key versions for rotation, etc.), without over-privileging. We achieve this via Microsoft Entra ID Role-Based Access Control (RBAC). The general approach is:
+Allow the Oracle Exadata VM Cluster specifically, the Azure Arc identity of its VMs, to access the Key Vault and perform key operations (like unwrap keys, create new key versions for rotation, etc.), without over-privileging. This can be achieved with Microsoft Entra ID Role-Based Access Control (RBAC). The general approach is as follows:
 
 * Create a security group in Microsoft Entra ID.
 * After the Oracle VM Cluster is Arc-enabled (next step), add the machine’s managed identity to this group.
 * Assign Key Vault roles to the group.
 
 This way, if you have multiple database VMs or clusters, you can manage their access via group membership and roles.
 
-1. **Create an Microsoft Entra ID security group** (optional but recommended):  
+1. **Create a Microsoft Entra ID security group** (optional, recommended):  
     * You can create a group via Azure portal (Microsoft Entra ID blade > Groups > New Group) or CLI:
 
-    Make note of the $GROUP_OBJECT_ID. This group remains empty for now. We add members in Step 3 after the Arc connector is set up (because the identities that need access is created during that process).
+    Make note of the $GROUP_OBJECT_ID. This group remains empty for now. You add members in [Step 3](#Step 3: Set Up the Oracle Identity Connector) after the Arc connector is set up; the identities needed to access the Arc connector is created in that process.
 2. **Assign Azure Key Vault roles**: We assign two roles to the security principal (the group, in this case) for the Key Vault:
-    * **Key Vault crypto officer** – Allows management of keys (create, delete, list key versions) and performing cryptographic operations (unwrap/decrypt, etc.).
+    * **Key Vault crypto officer** – Allows management of keys (create, delete, list key versions) and performance of cryptographic operations (unwrap/decrypt, etc.).
     * **Key Vault reader** – Allows viewing Key Vault properties
 3. Using Azure CLI, assign these roles on the Key Vault scope:
 
 > [!NOTE]
-> If you prefer to use Key Vault access policies instead of RBAC, you could use az keyvault set-policy to allow an Entra ID principal to perform "nwrap key" and "et key" operations. However, the RBAC method shown is the modern approach and aligns with Oracle’s documented roles.
+> If you prefer to use Key Vault access policies instead of RBAC, use az keyvault set-policy to allow an Entra ID principal to perform "nwrap key" and "et key" operations. However, the RBAC method is the modern approach and aligns with Oracle’s documented roles.
 
 4. For **Managed HSM**:
     * Azure RBAC uses a different set of roles. According to Oracle’s guidance, for Managed HSM you should assign the Azure RBAC Reader role for the HSM resource. Then, use the HSM local RBAC to assign "Managed HSM Crypto Officer" and "Managed HSM Crypto User" to your principal. This can be done in the Azure portal’s Managed HSM access control page. The security group can also be used for these assignments. Ensure that the principal has been added as an HSM Crypto Officer at minimum. Crypto Officer can generate new key versions for rotation, and Crypto User can use the keys.
 
-5. **Double-check roles**: After assignments, you can verify:
-    This should list the roles assigned to the group for the vault. There’s no harm in completing this role assignment step now. If the group has no members yet, the permissions are not used until a member is added.
-
-    At this stage, Azure is configured: you have a vault with a key, and a Microsoft Entra ID group with appropriate access to that vault. Now we move to the Oracle side to set up the integration.
-
 ## Step 3: Set Up the Oracle Identity Connector
-**Goal**: Set up the Oracle Identity Connector. This automatically configures the Azure Arc Agent to allow communication with Azure services (Key Vault) using an Azure identity.  
+Set up the Oracle Identity Connector. This automatically configures the Azure Arc Agent to allow communication with Azure services (Key Vault) using an Azure identity.  
 
 When you create an Identity Connector via the OCI console, each VM in the cluster is registered as an Azure Arc-enabled server in your Azure subscription. This grants the VMs an identity in Microsoft Entra ID (a managed identity) which is applied for Key Vault access.
 
@@ -110,7 +113,7 @@ Here’s how to create the connector:
     * Log in to the OCI Console for Oracle Database@Azure. Navigate to your Exadata VM Cluster resource. (Menu: Oracle Database > Oracle Exadata Database Service on Dedicated Infrastructure > Exadata VM Clusters > click your cluster name.)
     * On the VM Cluster details page, find the "Multicloud Information" section. You should see an Identity Connector field, which likely shows "None" if not set up yet.
 
-        Click Create or Setup Connector. A form appears.
+        Select Create or Setup Connector. A form appears.
 
     :::image type="content" source="media/oracle-create-identity-connector.png" alt-text="Screenshot that shows where to select create for identity connector.":::  
 
@@ -133,9 +136,9 @@ Here’s how to create the connector:
     * Oracle’s console shows the Identity Connector status. Navigate to *Database Multicloud Integrations > Identity Connectors* to verify the connector exists. On the VM Cluster page, the Identity Connector field should now show the connector name instead of "None."
 
     ### Troubleshooting tip 
-    If the connector creation fails, double-check the token (it might have expired – generate a fresh one) and Tenant ID. Also verify that the Azure subscription ID and resource group displayed are correct. The user generating the token must have rights to create Arc resources (Azure automatically creates a service principal for the Arc agent. Make sure the Azure resource provider Microsoft.HybridCompute is registered in your subscription).
+    If creating the connector fails, double-check the token (it might have expired – generate a fresh one) and Tenant ID. Also verify that the Azure subscription ID and resource group displayed are correct. The user generating the token must have rights to create Arc resources. Azure automatically creates a service principal for the Arc agent. Make sure the Azure resource provider Microsoft.HybridCompute is registered in your subscription.
 
-3. **Add Arc Machine Identities to Microsoft Entra ID group**: Once the connector is up, your Exadata VMs now each has a managed identity in Microsoft Entra ID. We need to grant these identities the Key Vault access (set up in Step 2). If you used a security group:
+3. **Add Arc Machine Identities to Microsoft Entra ID group**: Once the connector is up, your Exadata VMs now each has a managed identity in Microsoft Entra ID. We need to grant these identities the Key Vault access (set up in [Step 2](#Step 2: Configure Microsoft Entra ID permissions for Key Vault access). If you used a security group:
     * Find the object IDs of the new Arc server identities. In Azure portal, go to the Microsoft Entra ID blade > Entities > Enterprise applications or the Azure Arc resource – the principal Object ID might be listed. An easier way: use Azure CLI to list Azure Arc connected machines and get their principal IDs:
 
     Each Arc machine has an identity with a principalId. Alternatively:
@@ -150,14 +153,14 @@ Here’s how to create the connector:
 
 ## Step 4: Enable Azure Key Vault key management on the VM Cluster
 
-**Goal**: Activate the Key Vault integration at the Exadata VM Cluster level. This installs the required Oracle library/plugin on the cluster VMs that allows databases to use Azure Key Vault as a keystore.
+Activate the Key Vault integration at the Exadata VM Cluster level. This installs the required Oracle library/plugin on the cluster VMs that allows databases to use Azure Key Vault as a keystore.
 
 In the OCI console:
 
 * Go to the Exadata VM Cluster details page where you created the connector.
 * In the Multicloud Information section, find Azure key store or Azure Key Management status. It should currently say "Disabled."
-* Click Enable next to Azure key store.
-* Confirm the action in the dialog that appears (click Enable).
+* Select Enable next to Azure key store.
+* Confirm the action in the dialog that appears (select Enable).
 
 :::image type="content" source="media/oracle-enable-azure-key-management.png" alt-text="Screenshot that shows where to Enable Azure key management in the OCI console.":::
 
@@ -328,4 +331,4 @@ Finally, remember that this integration bridges two cloud services – so ensure
 
 * Learn about [Azure Key Vault Overview](/azure/key-vault/general/overview)
 
-* Learn about [Managed HSM Documentation](/azure/key-vault/managed-hsm/overview)
+* Learn about [Managed HSM Documentation](/azure/key-vault/managed-hsm/overview)