Receive and respond to key vault notifications with Azure Event Grid
Azure Key Vault integration with Azure Event Grid enables user notification when the status of a secret stored in a key vault has changed. For an overview of this feature, see Monitoring Key Vault with Event Grid.
This guide describes how to receive Key Vault notifications through Event Grid, and how to respond to status changes through Azure Automation.
Prerequisites
- An Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
- A key vault in your Azure Subscription. You can quickly create a new key vault by following the steps in Set and retrieve a secret from Azure Key Vault using Azure CLI.
Concepts
Event Grid is an eventing service for the cloud. By following the steps in this guide, you'll subscribe to events for Key Vault and route events to Automation. When one of the secrets in the key vault is about to expire (defined as 30 days before expiration date), Event Grid is notified of the status change and makes an HTTP POST to the endpoint. A web hook then triggers an Automation execution of a PowerShell script.
Create an Automation account
Create an Automation account through the Azure portal:
Go to portal.azure.com and log in to your subscription.
In the search box, enter Automation Accounts.
Under the Services section of the drop-down list on the search bar, select Automation Accounts.
Select Add.
Enter the required information in the Add Automation Account pane and then select Create.
Create a runbook
After your Automation account is ready, create a runbook.
Select the Automation account you created.
Select Runbooks under Process Automation.
Select Create a runbook.
Name your runbook and select PowerShell as the runbook type.
Select the runbook you created and then select the Edit button.
Enter the following code (for testing purposes) and select the Publish button. This action returns the result of the POST request received.
param
(
[Parameter (Mandatory = $false)]
[object] $WebhookData
)
#If runbook was called from Webhook, WebhookData will not be null.
if ($WebhookData) {
#rotate secret:
#generate new secret version in key vault
#update db/service with generated secret
#Write-Output "WebhookData <$WebhookData>"
Write-Output $WebhookData.RequestBody
}
else
{
# Error
write-Error "No input data found."
}
Create a webhook
Create a webhook to trigger your newly created runbook.
Select Webhooks from the Resources section of the runbook you published.
Select Add Webhook.
Select Create new Webhook.
Name the webhook, set an expiration date, and copy the URL.
Important
You can't view the URL after you create it. Make sure you save a copy in a secure location where you can access it for the remainder of this guide.
Select Parameters and run settings and then select OK. Don't enter any parameters. The Create button will be enabled.
Select OK and then select Create.
Create an Event Grid subscription
Create an Event Grid subscription through the Azure portal.
Go to your key vault and select the Events tab.
Select the Event Subscription button.
Create a descriptive name for the subscription.
Choose Event Grid Schema.
Topic Resource should be the key vault you want to monitor for status changes.
For Filter to Event Types, leave all options selected (9 selected).
For Endpoint Type, select Webhook.
Choose Select an endpoint. In the new context pane, paste the webhook URL from the Create a webhook step into the Subscriber Endpoint field.
Select Confirm Selection on the context pane.
Select Create.
Test and verify
Verify that your Event Grid subscription is properly configured. This test assumes you have subscribed to the "Secret New Version Created" notification in the Create an Event Grid subscription, and that you have the necessary permissions to create a new version of a secret in a key vault.
Go to your key vault on the Azure portal.
Create a new secret. For testing purposes, set the expiration to date to the next day.
On the Events tab in your key vault, select the Event Grid subscription you created.
Under Metrics, check whether an event was captured. Two events are expected: SecretNewVersion and SecretNearExpiry. These events validate that Event Grid successfully captured the status change of the secret in your key vault.
Go to your Automation account.
Select the Runbooks tab, and then select the runbook you created.
Select the Webhooks tab, and confirm that the "last triggered" time stamp is within 60 seconds of when you created the new secret. This result confirms that Event Grid made a POST to the webhook with the event details of the status change in your key vault and that the webhook was triggered.
Return to your runbook and select the Overview tab.
Look at the Recent Jobs list. You should see that a job was created and that the status is complete. This confirms that the webhook triggered the runbook to start executing its script.
Select the recent job and look at the POST request that was sent from Event Grid to the webhook. Examine the JSON and make sure that the parameters for your key vault and event type are correct. If the "event type" parameter in the JSON object matches the event that occurred in the key vault (in this example, Microsoft.KeyVault.SecretNearExpiry), the test was successful.
Troubleshooting
You can't create an event subscription
Reregister Event Grid and the key vault provider in your Azure subscription resource providers. See Azure resource providers and types.
Next steps
Congratulations! If you've correctly followed all these steps, you're now ready to programmatically respond to status changes of secrets stored in your key vault.
If you've been using a polling-based system to search for status changes of secrets in your key vaults, you can now start using this notification feature. You can also replace the test script in your runbook with code to programmatically renew your secrets when they're about to expire.
Learn more: