|
| 1 | +--- |
| 2 | +title: Integrate Azure Managed HSM with Azure Policy |
| 3 | +description: Learn how to integrate Azure Managed HSM with Azure Policy |
| 4 | +author: msmbaldwin |
| 5 | +ms.author: mbaldwin |
| 6 | +ms.date: 03/31/2021 |
| 7 | +ms.service: key-vault |
| 8 | +ms.subservice: general |
| 9 | +ms.topic: how-to |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +# Integrate Azure Managed HSM with Azure Policy |
| 14 | + |
| 15 | +[Azure Policy](../../governance/policy/index.yml) is a governance tool that gives users the ability to audit and manage their Azure environment at scale. Azure Policy provides the ability to place guardrails on Azure resources to ensure they're compliant with assigned policy rules. It allows users to perform audit, real-time enforcement, and remediation of their Azure environment. The results of audits performed by policy will be available to users in a compliance dashboard where they'll be able to see a drill-down of which resources and components are compliant and which aren't. For more information, see the [Overview of the Azure Policy service](../../governance/policy/overview.md). |
| 16 | + |
| 17 | +Example Usage Scenarios: |
| 18 | + |
| 19 | +- You currently don't have a solution to perform an audit across your organization, or you are conducting manual audits of your environment by asking individual teams within your organization to report their compliance. You're looking for a way to automate this task, perform audits in real time, and guarantee the accuracy of the audit. |
| 20 | +- You want to enforce your company security policies and stop individuals from creating certain cryptographic keys, but you don't have an automated way to block their creation. |
| 21 | +- You want to relax some requirements for your test teams, but you want to maintain tight controls over your production environment. You need a simple automated way to separate enforcement of your resources. |
| 22 | +- You want to be sure that you can roll back enforcement of new policies if there's a live-site issue. You need a one-click solution to turn off enforcement of the policy. |
| 23 | +- You are relying on a third-party solution for auditing your environment and you want to use an internal Microsoft offering. |
| 24 | + |
| 25 | +## Types of policy effects and guidance |
| 26 | + |
| 27 | +**Audit**: When the effect of a policy is set to audit, the policy will not cause any breaking changes to your environment. It will only alert you to components such as keys that do not comply with the policy definitions within a specified scope, by marking these components as non-compliant in the policy compliance dashboard. Audit is default if no policy effect is selected. |
| 28 | + |
| 29 | +**Deny**: When the effect of a policy is set to deny, the policy will block the creation of new components such as weaker keys, and will block new versions of existing keys that do not comply with the policy definition. Existing non-compliant resources within a Managed HSM are not affected. The 'audit' capabilities will continue to operate. |
| 30 | + |
| 31 | + |
| 32 | +### Keys using elliptic curve cryptography should have the specified curve names |
| 33 | + |
| 34 | +If you use elliptic curve cryptography or ECC keys, you can customize an allowed list of curve names from the list below. The default option allows all the following curve names. |
| 35 | + |
| 36 | +- P-256 |
| 37 | +- P-256K |
| 38 | +- P-384 |
| 39 | +- P-521 |
| 40 | + |
| 41 | +### Keys should have expirations dates set |
| 42 | + |
| 43 | +This policy audits all keys in your Managed HSMs and flags keys that do not have an expiration date set as non-compliant. You can also use this policy to block the creation of keys that do not have an expiration date set. |
| 44 | + |
| 45 | +### Keys should have more than the specified number of days before expiration |
| 46 | + |
| 47 | +If a key is too close to expiration, an organizational delay to rotate the key may result in an outage. Keys should be rotated at a specified number of days prior to expiration to provide sufficient time to react to a failure. This policy will audit keys too close to their expiration date and allows you to set this threshold in days. You can also use this policy to prevent the creation of new keys too close to their expiration date. |
| 48 | + |
| 49 | +### Keys using RSA cryptography should have a specified minimum key size |
| 50 | + |
| 51 | +Using RSA keys with smaller key sizes is not a secure design practice. You may be subject to audit and certification standards that mandate the use of a minimum key size. The following policy allows you to set a minimum key size requirement on your Managed HSM. You can audit keys that do not meet this minimum requirement. This policy can also be used to block the creation of new keys that do not meet the minimum key size requirement. |
| 52 | + |
| 53 | +## Enabling and managing a Managed HSM policy through the Azure CLI |
| 54 | + |
| 55 | +### Register preview feature in your subscription |
| 56 | + |
| 57 | +In the subscription that customer owns, run the following Azure CLI command line as Contributor or Owner role of the subscription, |
| 58 | + |
| 59 | +```azurecli-interactive |
| 60 | +az feature register --namespace Microsoft.KeyVault --name MHSMGovernance |
| 61 | +``` |
| 62 | + |
| 63 | +If there is an existing HSM pool in this subscription, update will be carried to these pools. Full enablement of the policy may take up to 30 mins. See [Set up preview features in Azure subscription](../../azure-resource-manager/management/preview-features.md?tabs=azure-cli). |
| 64 | + |
| 65 | +### Giving permission to scan daily |
| 66 | + |
| 67 | +To check the compliance of the pool's inventory keys, the customer must assign the "Managed HSM Crypto Auditor" role to "Azure Key Vault Managed HSM Key Governance Service"(App ID: a1b76039-a76c-499f-a2dd-846b4cc32627) so it can access key's metadata. Without the grant of permission, inventory keys are not going to be reported on Azure Policy compliance report, only new keys, updated keys, imported keys and rotated keys will be checked on compliance. To do so, a user who has role of "Managed HSM Administrator" to the Managed HSM needs to run the following Azure CLI commands: |
| 68 | + |
| 69 | +On windows: |
| 70 | + |
| 71 | +```azurecli-interactive |
| 72 | +az ad sp show --id a1b76039-a76c-499f-a2dd-846b4cc32627 --query objectId |
| 73 | +``` |
| 74 | + |
| 75 | +Copy the `id` printed, paste it in the following command: |
| 76 | + |
| 77 | +```azurecli-interactive |
| 78 | +az keyvault role assignment create --scope / --role "Managed HSM Crypto Auditor" --assignee-object-id "the id printed in previous command" --hsm-name <hsm name> |
| 79 | +``` |
| 80 | + |
| 81 | +On Linux or Windows Subsystem of Linux: |
| 82 | + |
| 83 | +```azurecli-interactive |
| 84 | +spId=$(az ad sp show --id a1b76039-a76c-499f-a2dd-846b4cc32627 --query objectId|cut -d "\"" -f2) |
| 85 | +echo $spId |
| 86 | +az keyvault role assignment create --scope / --role "Managed HSM Crypto Auditor" --assignee-object-id $spId --hsm-name <hsm name> |
| 87 | +``` |
| 88 | + |
| 89 | +### Create policy assignments - define rules of audit and/or deny |
| 90 | + |
| 91 | +Policy assignments have concrete values defined for policy definitions' parameters. In the [Azure portal](https://portal.azure.com/?Microsoft_Azure_ManagedHSM_assettypeoptions=%7B%22ManagedHSM%22:%7B%22options%22:%22%22%7D%7D&Microsoft_Azure_ManagedHSM=true&feature.canmodifyextensions=true}), go to "Policy", filter on the "Key Vault" category, find these four preview key governance policy definitions. Select one, then select "Assign" button on top. Fill in each field. If the policy assignment is for request denials, use a clear name about the policy because, when a request is denied, the policy assignment's name will appear in the error. Select Next, uncheck "Only show parameters that need input or review", and enter values for parameters of the policy definition. Skip the "Remediation", and create the assignment. The service will need up to 30 minutes to enforce "Deny" assignments. |
| 92 | + |
| 93 | +- [Preview]: Azure Key Vault Managed HSM keys should have an expiration date |
| 94 | +- [Preview]: Azure Key Vault Managed HSM keys using RSA cryptography should have a specified minimum key size |
| 95 | +- [Preview]: Azure Key Vault Managed HSM Keys should have more than the specified number of days before expiration |
| 96 | +- [Preview]: Azure Key Vault Managed HSM keys using elliptic curve cryptography should have the specified curve names |
| 97 | + |
| 98 | +You can also do this operation using the Azure CLI. See [Create a policy assignment to identify non-compliant resources with Azure CLI](../../governance/policy/assign-policy-azurecli.md). |
| 99 | + |
| 100 | +### Test your setup |
| 101 | + |
| 102 | +Try to update/create a key that violates the rule, if you have a policy assignment with effect "Deny", it will return 403 to your request. |
| 103 | +Review the scan result of inventory keys of auditing policy assignments. After 12 hours, check the Policy's Compliance menu, filter on the "Key Vault" category, and find your assignments. Select on each of them, to check the compliance result report. |
| 104 | + |
| 105 | +## Troubleshooting |
| 106 | + |
| 107 | +If there are no compliance results of a pool after one day. Check if the role assignment has been done on step 2 successfully. Without Step 2, the key governance service won't be able to access key's metadata. The Azure CLI `az keyvault role assignment list` command can verify whether the role has been assigned. |
| 108 | + |
| 109 | +## Next Steps |
| 110 | + |
| 111 | +- [Logging and frequently asked questions for Azure policy for key vault](../general/troubleshoot-azure-policy-for-key-vault.md) |
| 112 | +- Learn more about the [Azure Policy service](../../governance/policy/overview.md) |
| 113 | +- See Key Vault samples: [Key Vault built-in policy definitions](../../governance/policy/samples/built-in-policies.md#key-vault) |
| 114 | +- Learn about [Microsoft cloud security benchmark on Key vault](/security/benchmark/azure/baselines/key-vault-security-baseline) |
0 commit comments