Merge pull request #2635 from MicrosoftDocs/main

Auto Publish – main to live - 2026-03-21 06:00 UTC

Author: learn-build-service-prod[bot]

articles/key-vault/includes/key-management-policy-grammar.md

@@ -257,7 +257,7 @@ The encoding is as follows:
 An Environment Assertion is a signed assertion, in JSON Web Token form, from a trusted authority. An Environment Asserting contains at least a key encryption key and one or more claims about the target environment (for example, TEE type, publisher, version) that are matched against the Key Release Policy. The key encryption key is a public RSA key owned and protected by the target execution environment that is used for key export. It must appear in the TEE keys claim (x-ms-runtime/keys). This claim is a JSON object representing a JSON Web Key Set. Within the JWKS, one of the keys must meet the requirements for use as an encryption key (key_use is "enc", or key_ops contains "encrypt"). The first suitable key is chosen.
 
 ## Key Vault and Managed HSM Attestation Token Requirements
-Azure Key Vault Premium and Managed HSM Secure Key Release were designed alongside [Microsoft Azure Attestation Service](../../attestation/overview.md) but may work with any attestation server’s tokens if it conforms to the expected token structure, supports OpenID connect, and has the expected claims. DigiCert is presently the only public CA that Azure Key Vault Premium and Managed HSM trust for attestation token signing certificates. 
+Azure Key Vault Premium and Managed HSM Secure Key Release were designed alongside [Microsoft Azure Attestation Service](/azure/attestation/overview) but may work with any attestation server's tokens if it conforms to the expected token structure, supports OpenID connect, and has the expected claims. DigiCert is presently the only public CA that Azure Key Vault Premium and Managed HSM trust for attestation token signing certificates.
 
 
 
@@ -279,4 +279,4 @@ The full set of requirements are:
 
   - Marked with **key_use** of encryption or a **key_ops** array containing the Encrypt operation. 
 
-For a sample token see [Examples of an Azure Attestation token](../../attestation/attestation-token-examples.md#sample-jwt-generated-for-sev-snp-attestation).
+For a sample token see [Examples of an Azure Attestation token](/azure/attestation/attestation-token-examples#sample-jwt-generated-for-sev-snp-attestation).

articles/key-vault/includes/managed-hsm/cleanup-warning.md

@@ -0,0 +1,12 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Managed HSM cleanup warning
+---
+
+> [!WARNING]
+> Deleting the resource group puts the Managed HSM into a soft-deleted state. The Managed HSM continues to be billed until it's purged. See [Managed HSM soft-delete and purge protection](/azure/key-vault/managed-hsm/recovery)

articles/key-vault/includes/managed-hsm/intro.md

@@ -0,0 +1,11 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Managed HSM intro description
+---
+
+Managed HSM is a fully managed, highly available, single-tenant, standards-compliant cloud service that enables you to safeguard cryptographic keys for your cloud applications, using **FIPS 140-3 Level 3** validated HSMs. For more information on Managed HSM, review the [Overview](/azure/key-vault/managed-hsm/overview).

articles/key-vault/includes/managed-hsm/sdk-default-credential.md

@@ -0,0 +1,28 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: DefaultAzureCredential explanation table
+---
+
+`DefaultAzureCredential` automatically selects the appropriate credential based on your environment:
+
+| Environment | Credential used |
+|-------------|-----------------|
+| Azure VMs, App Service, Functions | System-assigned or user-assigned managed identity |
+| Azure Kubernetes Service | Workload identity |
+| Local development | Azure CLI, Visual Studio, or VS Code credentials |
+| CI/CD pipelines | Workload identity federation or service principal |
+
+The credential checks these sources in order:
+1. Environment variables
+2. Workload identity
+3. Managed identity
+4. Azure CLI
+5. Azure PowerShell
+6. Visual Studio / VS Code credentials
+
+For production workloads in Azure, managed identities are strongly recommended because they eliminate credential management entirely.

articles/key-vault/includes/managed-hsm/sdk-prereqs.md

@@ -0,0 +1,15 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Managed HSM SDK prerequisites
+---
+
+- An Azure subscription. [Create one for free](https://azure.microsoft.com/free/).
+- A provisioned and activated Managed HSM. See [Quickstart: Provision and activate a managed HSM using Azure CLI](/azure/key-vault/managed-hsm/quick-create-cli).
+- A key created in your Managed HSM. See [Manage keys in a Managed HSM](/azure/key-vault/managed-hsm/key-management).
+- An Azure resource with a managed identity (such as a VM, App Service, or Azure Function) or Azure CLI for local development.
+- The managed identity must have the appropriate Managed HSM local RBAC role assigned. See [Secure access to your managed HSMs](/azure/key-vault/managed-hsm/how-to-secure-access).

articles/key-vault/includes/managed-hsm/sdk-role-assignment.md

@@ -0,0 +1,27 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Managed HSM role assignment CLI example
+---
+
+## Assign Managed HSM roles
+
+For your application to access keys, assign the appropriate Managed HSM local RBAC role to your managed identity:
+
+```azurecli
+# Get the principal ID of your managed identity
+principalId=$(az vm identity show --name myVM --resource-group myRG --query principalId -o tsv)
+
+# Assign the Crypto User role for key operations
+az keyvault role assignment create \
+    --hsm-name ContosoMHSM \
+    --role "Managed HSM Crypto User" \
+    --assignee $principalId \
+    --scope /keys
+```
+
+For more information on roles and permissions, see [Managed HSM local RBAC built-in roles](/azure/key-vault/managed-hsm/built-in-roles).

articles/key-vault/includes/managed-hsm/security-domain-prereqs.md

@@ -0,0 +1,29 @@
+---
+author: msmbaldwin
+ms.author: mbaldwin
+ms.service: azure-key-vault
+ms.subservice: managed-hsm
+ms.topic: include
+ms.date: 03/13/2026
+# Include: Security domain RSA key pair generation prerequisites
+---
+
+To activate your HSM, you need:
+
+- A minimum of three RSA key pairs (maximum 10)
+- The minimum number of keys required to decrypt the security domain (called a *quorum*)
+
+You send at least three (maximum 10) RSA public keys to the HSM. The HSM encrypts the security domain with these keys and sends it back. Once the security domain download completes successfully, your HSM is ready to use. You also need to specify the quorum, which is the minimum number of private keys required to decrypt the security domain.
+
+The following example shows how to use `openssl` to generate three self-signed certificates:
+
+```console
+openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
+openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
+openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer
+```
+
+The certificate expiration date doesn't affect security domain operations—even an "expired" certificate can still be used to restore the security domain.
+
+> [!IMPORTANT]
+> These RSA private keys are the root of trust for your Managed HSM. For production environments, generate these keys using an air-gapped system or on-premises HSM, and store them securely. See [Security domain best practices](/azure/key-vault/managed-hsm/security-domain#generating-the-rsa-key-pairs-securely) for detailed guidance.

articles/key-vault/managed-hsm/how-to-secure-access.md

@@ -7,7 +7,7 @@ ms.custom: devx-track-azurecli
 ms.service: azure-key-vault
 ms.subservice: managed-hsm
 ms.topic: how-to
-ms.date: 01/30/2026
+ms.date: 03/13/2026
 ms.author: mbaldwin
 # Customer intent: As a managed HSM administrator, I want to set access control and configure the Managed HSM, so that I can ensure it's secure and auditors can properly monitor all activities for this Managed HSM.
 ---
@@ -144,6 +144,63 @@ storage_account_principal=$(az storage account show --id $storageresource --quer
 az keyvault role assignment create --hsm-name ContosoMHSM --role "Managed HSM Crypto Service Encryption User" --assignee $storage_account_principal
 ```
 
+## Configure Privileged Identity Management for just-in-time access
+
+For highly sensitive environments, use [Microsoft Entra Privileged Identity Management (PIM)](/entra/id-governance/privileged-identity-management/pim-configure) to enforce just-in-time access for the Managed HSM Administrator role. PIM reduces the attack surface by eliminating standing administrative privileges.
+
+### Prerequisites for PIM integration
+
+- Microsoft Entra ID P2 or Microsoft Entra ID Governance license
+- Privileged Role Administrator or Global Administrator role in Microsoft Entra ID
+
+### Enable PIM for Managed HSM Administrator role
+
+1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com).
+
+1. Navigate to **Identity governance** > **Privileged Identity Management** > **Microsoft Entra roles**.
+
+1. Select **Roles** and search for roles that include "Managed HSM". While the data plane roles (Managed HSM Administrator, Crypto User, etc.) are managed through Managed HSM local RBAC, you can use PIM for the control plane **Managed HSM Contributor** role.
+
+1. Select the role and configure:
+   - **Activation maximum duration**: Set to a limited time window (for example, 4-8 hours)
+   - **Require justification**: Enable to require users to provide a reason for activation
+   - **Require approval**: Enable and specify approvers from your security team
+   - **Require MFA**: Enable for an additional security layer
+
+### Use Microsoft Entra security groups with PIM
+
+For data plane roles managed through Managed HSM local RBAC, combine PIM with Microsoft Entra security groups:
+
+1. Create a Microsoft Entra security group for HSM administrators (for example, "Contoso HSM Admins").
+
+1. Assign the Managed HSM Administrator role to this security group:
+
+   ```azurecli-interactive
+   az keyvault role assignment create --hsm-name ContosoMHSM \
+     --assignee $(az ad group show -g 'Contoso HSM Admins' --query 'id' -o tsv) \
+     --scope / --role "Managed HSM Administrator"
+   ```
+
+1. Configure the security group as PIM-eligible in Microsoft Entra admin center:
+   - Navigate to **Identity governance** > **Privileged Identity Management** > **Groups**
+   - Select **Discover groups** and add "Contoso HSM Admins"
+   - Configure activation settings (duration, approval, MFA)
+
+1. When administrators need access, they activate their group membership through PIM, which temporarily grants them the Managed HSM Administrator role.
+
+### Monitor PIM activations
+
+Configure alerts for PIM role activations to maintain visibility:
+
+1. In Microsoft Entra admin center, navigate to **Privileged Identity Management** > **Microsoft Entra roles** > **Alerts**.
+
+1. Configure alerts for:
+   - Roles being activated too frequently
+   - Roles being assigned outside of PIM
+   - Eligible assignments being created
+
+For comprehensive security monitoring, integrate these alerts with [Microsoft Sentinel](sentinel.md) alongside your Managed HSM audit logs.
+
 ## Considerations for production environments
 
 This tutorial demonstrates a simplified scenario to illustrate access control implementation.
@@ -156,6 +213,8 @@ Adjust permissions for your managed HSM based on your specific requirements. In
 - For a getting-started tutorial for an administrator, see [What is Managed HSM?](overview.md)
 - For more information about usage logging for Managed HSM logging, see [Managed HSM logging](logging.md).
 - To learn about managing roles in Managed HSM, see [Managed HSM local RBAC](role-management.md).
+- Learn about [Microsoft Entra Privileged Identity Management](/entra/id-governance/privileged-identity-management/pim-configure).
+- Review [Secure your Azure Managed HSM deployment](secure-managed-hsm.md).
 - See [Azure RBAC documentation](/azure/role-based-access-control/overview).
 - See [Azure RBAC: Built-in roles](/azure/role-based-access-control/built-in-roles).
 - See [Manage Azure RBAC with Azure CLI](/azure/role-based-access-control/role-assignments-cli).

articles/key-vault/managed-hsm/key-management.md

@@ -27,6 +27,7 @@ To complete the steps in this article, you must have the following items:
 * A Microsoft Azure subscription. If you don't have one, you can sign up for a [free trial](https://azure.microsoft.com/pricing/free-trial).
 * The Azure CLI version 2.25.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install the Azure CLI]( /cli/azure/install-azure-cli).
 * A managed HSM in your subscription. See [Quickstart: Provision and activate a managed HSM using Azure CLI](quick-create-cli.md) to provision and activate a managed HSM.
+* To access keys using Azure SDKs, see [.NET](quickstart-dotnet.md) | [Python](quickstart-python.md) | [JavaScript](quickstart-javascript.md)
 
 [!INCLUDE [cloud-shell-try-it.md](~/reusable-content/ce-skilling/azure/includes/cloud-shell-try-it.md)]
 

articles/key-vault/managed-hsm/quick-create-cli.md

@@ -84,25 +84,7 @@ Your Azure account is now authorized to perform any operations on this Managed H
 
 All data plane commands are disabled until the HSM is activated. For example, you are not able to create keys or assign roles. Only the designated administrators that were assigned during the create command can activate the HSM. To activate the HSM, you must download the [Security Domain](security-domain.md).
 
-To activate your HSM, you need:
-- To provide a minimum of three RSA key-pairs (up to a maximum of 10)
-- To specify the minimum number of keys required to decrypt the security domain (called a *quorum*)
-
-To activate the HSM, you send at least three (maximum 10) RSA public keys to the HSM. The HSM encrypts the security domain with these keys and sends it back. Once this security domain download is successfully completed, your HSM is ready to use. You also need to specify quorum, which is the minimum number of private keys required to decrypt the security domain.
-
-The following example shows how to use  `openssl` to generate three self-signed certificates.
-
-```azurecli-interactive
-openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
-openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
-openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer
-```
-
-> [!NOTE]
-> Even if the certificate has "expired," it can still be used to restore the security domain.
-
-> [!IMPORTANT]
-> Create and store the RSA key pairs and security domain file generated in this step securely.
+[!INCLUDE [Security domain prerequisites](../includes/managed-hsm/security-domain-prereqs.md)]
 
 Use the `az keyvault security-domain download` command to download the security domain and activate your Managed HSM. The following example uses three RSA key pairs (only public keys are needed for this command) and sets the quorum to two.