How to enable Key Vault logging

After you create one or more key vaults, you'll likely want to monitor how and when your key vaults are accessed, and by whom. For full details on the feature, see Key Vault logging.

Prerequisites

To complete this tutorial, you must have the following:

  • An existing key vault that you have been using.
  • Azure Cloud Shell - Bash environment
  • Sufficient storage on Azure for your Key Vault logs.

This guide commands are formatted for Cloud Shell with Bash as an environment.

Connect to your Key Vault subscription

The first step in setting up key logging is connecting to subscription containing your key vault. This is especially important if you have multiple subscriptions associated with your account.

With the Azure CLI, you can view all your subscriptions using the az account list command, and then connect to one using az account set:

az account list

az account set --subscription "<subscriptionID>"

With Azure PowerShell, you can first list your subscriptions using the Get-AzSubscription cmdlet, and then connect to one using the Set-AzContext cmdlet:

Get-AzSubscription

Set-AzContext -SubscriptionId "<subscriptionID>"

Create a storage account for your logs

Although you can use an existing storage account for your logs, we'll create a new storage account dedicated to Key Vault logs.

For additional ease of management, we'll also use the same resource group as the one that contains the key vault. In the Azure CLI quickstart and Azure PowerShell quickstart, this resource group is named myResourceGroup, and the location is eastus. Replace these values with your own, as applicable.

We will also need to provide a storage account name. Storage account names must be unique, between 3 and 24 characters in length, and use numbers and lower-case letters only. Lastly, we will be creating a storage account of the "Standard_LRS" SKU.

With the Azure CLI, use the az storage account create command.

az storage account create --name "<your-unique-storage-account-name>" -g "myResourceGroup" --sku "Standard_LRS"

With Azure PowerShell, use the New-AzStorageAccount cmdlet. You will need to provide the location that corresponds to the resource group.

 New-AzStorageAccount -ResourceGroupName myResourceGroup -Name "<your-unique-storage-account-name>" -Type "Standard_LRS" -Location "eastus"

In either case, note the "id" of the storage account. The Azure CLI operation returns the "id" in the output. To obtain the "id" with Azure PowerShell, use Get-AzStorageAccount and assigned the output to a the variable $sa. You can then see the storage account with $sa.id. (The "$sa.Context" property will also be used, later in this article.)

$sa = Get-AzStorageAccount -Name "<your-unique-storage-account-name>" -ResourceGroup "myResourceGroup"
$sa.id

The "id" of the storage account will be in the format "/subscriptions//resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/".

Note

If you decide to use an existing storage account, it must use the same subscription as your key vault, and it must use the Azure Resource Manager deployment model, rather than the classic deployment model.

Obtain your key vault Resource ID

In the CLI quickstart and PowerShell quickstart, you created a key with a unique name. Use that name again in the steps below. If you cannot remember the name of your key vault, you can use the Azure CLI az keyvault list command or the Azure PowerShell Get-AzKeyVault cmdlet to list them.

Use the name of your key vault to find its Resource ID. With Azure CLI, use the az keyvault show command.

az keyvault show --name "<your-unique-keyvault-name>"

With Azure PowerShell, use the Get-AzKeyVault cmdlet.

Get-AzKeyVault -VaultName "<your-unique-keyvault-name>"

The Resource ID for your key vault will be on the format "/subscriptions//resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/". Note it for the next step.

Enable logging using Azure PowerShell

To enable logging for Key Vault, we'll use the Azure CLI az monitor diagnostic-settings create command, or the Set-AzDiagnosticSetting cmdlet, together with the storage account ID and the key vault Resource ID.

az monitor diagnostic-settings create --storage-account "<storage-account-id>" --resource "<key-vault-resource-id>" --name "Key vault logs" --logs '[{"category": "AuditEvent","enabled": true}]' --metrics '[{"category": "AllMetrics","enabled": true}]'

With Azure PowerShell, we'll use the Set-AzDiagnosticSetting cmdlet, with the -Enabled flag set to $true and the category set to AuditEvent (the only category for Key Vault logging):

Set-AzDiagnosticSetting -ResourceId "<key-vault-resource-id>" -StorageAccountId $sa.id -Enabled $true -Category "AuditEvent"

Optionally, you can set a retention policy for your logs, so that older logs are automatically deleted after a specified amount of time. For example, you could set set retention policy that automatically deletes logs older than 90 days.

With Azure PowerShell, use the Set-AzDiagnosticSetting cmdlet.

Set-AzDiagnosticSetting "<key-vault-resource-id>" -StorageAccountId $sa.id -Enabled $true -Category AuditEvent -RetentionEnabled $true -RetentionInDays 90

What is logged:

  • All authenticated REST API requests, including failed requests as a result of access permissions, system errors, or bad requests.
  • Operations on the key vault itself, including creation, deletion, setting key vault access policies, and updating key vault attributes such as tags.
  • Operations on keys and secrets in the key vault, including:
    • Creating, modifying, or deleting these keys or secrets.
    • Signing, verifying, encrypting, decrypting, wrapping and unwrapping keys, getting secrets, and listing keys and secrets (and their versions).
  • Unauthenticated requests that result in a 401 response. Examples are requests that don't have a bearer token, that are malformed or expired, or that have an invalid token.
  • Event Grid notification events for near expiry, expired and vault access policy changed (new version event is not logged). Events are logged regardless if there is event subscription created on key vault. For more information see, Event Grid event schema for Key Vault

Access your logs

Key Vault 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.

First, list all the blobs in the container. With the Azure CLI, use the az storage blob list command.

az storage blob list --account-name "<your-unique-storage-account-name>" --container-name "insights-logs-auditevent"

With Azure PowerShell, use the Get-AzStorageBlob list all the blobs in this container, enter:

Get-AzStorageBlob -Container "insights-logs-auditevent" -Context $sa.Context

As you will see from the output of either the Azure CLI command or the Azure PowerShell cmdlet, the name of the blobs are in the format resourceId=<ARM resource ID>/y=<year>/m=<month>/d=<day of month>/h=<hour>/m=<minute>/filename.json. The date and time values use UTC.

Because you can use the same storage account to collect logs for multiple resources, the full resource ID in the blob name is useful to access or download just the blobs that you need. But before we do that, we'll first cover how to download all the blobs.

With the Azure CLI, use the az storage blob download command, pass it the names of the blobs, and the path to the file where you wish to save the results.

az storage blob download --container-name "insights-logs-auditevent" --file <path-to-file> --name "<blob-name>" --account-name "<your-unique-storage-account-name>"

With Azure PowerShell, use the Gt-AzStorageBlobs cmdlet to get a list of the blobs, then pipe that to the Get-AzStorageBlobContent cmdlet to download the logs to your chosen path.

$blobs = Get-AzStorageBlob -Container "insights-logs-auditevent" -Context $sa.Context | Get-AzStorageBlobContent -Destination "<path-to-file>"

When you run this second cmdlet in PowerShell, the / delimiter in the blob names creates a full folder structure under the destination folder. You'll use this structure to download and store the blobs as files.

To selectively download blobs, use wildcards. For example:

  • If you have multiple key vaults and want to download logs for just one key vault, named CONTOSOKEYVAULT3:

    Get-AzStorageBlob -Container "insights-logs-auditevent" -Context $sa.Context -Blob '*/VAULTS/CONTOSOKEYVAULT3
    
  • If you have multiple resource groups and want to download logs for just one resource group, use -Blob '*/RESOURCEGROUPS/<resource group name>/*':

    Get-AzStorageBlob -Container "insights-logs-auditevent" -Context $sa.Context -Blob '*/RESOURCEGROUPS/CONTOSORESOURCEGROUP3/*'
    
  • If you want to download all the logs for the month of January 2019, use -Blob '*/year=2019/m=01/*':

    Get-AzStorageBlob -Container "insights-logs-auditevent" -Context $sa.Context -Blob '*/year=2016/m=01/*'
    

You're now ready to start looking at what's in the logs. But before we move on to that, you should know two more commands:

For details on how to read the logs, see Key Vault logging: Interpret your Key Vault logs

Use Azure Monitor logs

You can use the Key Vault solution in Azure Monitor logs to review Key Vault AuditEvent logs. In Azure Monitor logs, you use log queries to analyze data and get the information you need.

For more information, including how to set this up, see Azure Key Vault in Azure Monitor.

Next steps