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

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.
  • Azure Event Grid notification events for the following conditions: expired, near expiration, and changed vault access policy (the new version event isn't logged). Events are logged even if there's an event subscription created on the key vault. For more information, see Azure Key Vault as Event Grid source.

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.

In this article, 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 the 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 by using the az account list command. Then you connect to one by using the az account set command:

az account list

az account set --subscription "<subscriptionID>"

With Azure PowerShell, you can first list your subscriptions by using the Get-AzSubscription cmdlet. Then you connect to one by 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, here you create a new storage account dedicated to Key Vault logs.

For additional ease of management, you'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.

You 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 lowercase letters only. Lastly, you create 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 assign the output to the variable $sa. You can then see the storage account with $sa.id. (The $sa.Context property is also used later in this article.)

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

The ID of the storage account is in the following format: "/subscriptions/your-subscription-ID/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/your-unique-storage-account-name".

Note

If you decide to use an existing storage account, it must use the same subscription as your key vault. 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 following steps. If you can't 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 the 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 is in the following format: "/subscriptions/your-subscription-ID/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/your-unique-keyvault-name. Note it for the next step.

Enable logging

You can enable logging for Key Vault by using the Azure CLI, Azure PowerShell, or the Azure portal.

Azure CLI

Use the Azure CLI az monitor diagnostic-settings create command, the storage account ID, and the key vault resource ID, as follows:

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}]'

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 might set a retention policy that automatically deletes logs older than 90 days.

With the Azure CLI, use the az monitor diagnostic-settings update command.

az monitor diagnostic-settings update --name "Key vault retention policy" --resource "<key-vault-resource-id>" --set retentionPolicy.days=90

Access your logs

Your Key Vault logs are 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 Get-AzStorageBlob. To list all the blobs in this container, enter:

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

From the output of either the Azure CLI command or the Azure PowerShell cmdlet, you can see that the names of the blobs are in the following 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 Coordinated Universal Time.

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 first, 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 want 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 list 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/*'
    

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, see Monitoring Key Vault.

Next steps