Edit

Share via

Managed HSM logging

  • Article

After you create one or more Managed HSMs, you'll likely want to monitor how and when your HSMs are accessed, and by who. You can do this by enabling logging, which saves information in an Azure storage account that you provide. A new container named insights-logs-auditevent is automatically created for your specified storage account. You can use this same storage account for collecting logs for multiple Managed HSMs.

You can access your logging information 10 minutes (at most) after the Managed HSM operation. In most cases, it will be quicker than this. It's up to you to manage your logs in your storage account:

  • Use standard Azure access control methods to secure your logs by restricting who can access them.
  • Delete logs that you no longer want to keep in your storage account.

Use this tutorial to help you get started with Managed HSM logging. You'll create a storage account, enable logging, and interpret the collected log information.

Note

This tutorial does not include instructions for how to create Managed HSMs or keys. This article provides Azure CLI instructions for updating diagnostic logging.

Prerequisites

To complete the steps in this article, you must have the following items:

Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code or command block. Selecting Try It doesn't automatically copy the code or command to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Button to launch Azure Cloud Shell.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To use Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block (or command block) to copy the code or command.

  3. Paste the code or command into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code or command.

Connect to your Azure subscription

The first step in setting up key logging is to point Azure CLI to the Managed HSM that you want to log.

az login

For more information on login options via the CLI take a look at sign in with Azure CLI

You might have to specify the subscription that you used to create your Managed HSM. Enter the following command to see the subscriptions for your account:

Identify the managed HSM and storage account

hsmresource=$(az keyvault show --hsm-name ContosoMHSM --query id -o tsv)
storageresource=$(az storage account show --name ContosoMHSMLogs --query id -o tsv)

Enable logging

To enable logging for Managed HSM, use the az monitor diagnostic-settings create command, together with the variables that we created for the new storage account and the Managed HSM. We'll also set the -Enabled flag to $true and set the category to AuditEvent (the only category for Managed HSM logging):

This output confirms that logging is now enabled for your Managed HSM, and it will save information to your storage account.

Optionally, you can set a retention policy for your logs such that older logs are automatically deleted. For example, set retention policy by setting the -RetentionEnabled flag to $true, and set the -RetentionInDays parameter to 90 so that logs older than 90 days are automatically deleted.

az monitor diagnostic-settings create --name ContosoMHSM-Diagnostics --resource $hsmresource --logs '[{"category": "AuditEvent","enabled": true}]' --storage-account $storageresource

What's logged:

  • All authenticated REST API requests, including failed requests as a result of access permissions, system errors, firewall blocks, or bad requests.
  • Managed plane operations on the Managed HSM resource itself, including creation, deletion, and updating attributes such as tags.
  • Security Domain related operations such as initialize & download, initialize recovery, upload
  • Full HSM backup, restore and selective restore operations
  • Role management operations such as create/view/delete role assignments and create/view/delete custom role definitions
  • Operations on keys, including:
    • Creating, modifying, or deleting the keys.
    • Signing, verifying, encrypting, decrypting, wrapping and unwrapping keys, listing keys.
    • Key backup, restore, purge
    • Key release
  • Invalid paths that result in a 404 response.

Access your logs

Managed HSM logs are stored in the insights-logs-auditevent container in the storage account that you provided. To view the logs, you have to download blobs. For information on Azure Storage, see Create, download, and list blobs with Azure CLI.

Individual blobs are stored as text, formatted as a JSON. Let's look at an example log entry. The example below shows the log entry when a request to create a full backup is sent to the managed HSM.

[
  {
    "TenantId": "{tenant-id}",
    "time": "2020-08-31T19:52:39.763Z",
    "resourceId": "/SUBSCRIPTIONS/{subscription-id}/RESOURCEGROUPS/CONTOSORESOURCEGROUP/PROVIDERS/MICROSOFT.KEYVAULT/MANAGEDHSMS/CONTOSOMHSM",
    "operationName": "BackupCreate",
    "operationVersion": "7.0",
    "category": "AuditEvent",
    "resultType": "Success",
    "properties": {
        "PoolType": "M-HSM",
        "sku_Family": "B",
        "sku_Name": "Standard_B1"
    },
    "durationMs": 488,
    "callerIpAddress": "X.X.X.X",
    "identity": "{\"claim\":{\"appid\":\"{application-id}\",\"http_schemas_microsoft_com_identity\":{\"claims\":{\"objectidentifier\":\"{object-id}\"}},\"http_schemas_xmlsoap_org_ws_2005_05_identity\":{\"claims\":{\"upn\":\"admin@contoso.com\"}}}}",
    "clientInfo": "azsdk-python-core/1.7.0 Python/3.8.2 (Linux-4.19.84-microsoft-standard-x86_64-with-glibc2.29) azsdk-python-azure-keyvault/7.2",
    "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "subnetId": "(unknown)",
    "httpStatusCode": 202,
    "PoolName": "mhsmdemo",
    "requestUri": "https://ContosoMHSM.managedhsm.azure.net/backup",
    "resourceGroup": "ContosoResourceGroup",
    "resourceProvider": "MICROSOFT.KEYVAULT",
    "resource": "ContosoMHSM",
    "resourceType": "managedHSMs"
  }
]

Next steps