Merge pull request #87105 from msmbaldwin/akveventgrid

Key Vault Event Grid

Author: TedA-M

articles/event-grid/event-schema-key-vault.md

@@ -0,0 +1,85 @@
+---
+title: Azure Event Grid Azure Key Vault event schema
+description: Describes the properties and schema provided for Azure Key Vault events with Azure Event Grid
+services: event-grid
+author: msmbaldwin
+ms.service: event-grid
+ms.topic: reference
+ms.date: 10/25/2019
+ms.author: mbaldwin
+---
+
+# Azure Event Grid event schema for Azure Key Vault (preview)
+
+This article provides the properties and schema for [Azure Key Vault](../key-vault/index.yml) events, currently in preview. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
+
+## Available event types
+
+An Azure Key Vault account emits the following event types:
+
+| Event full Name | Event display name | description |
+| ---------- | ----------- |---|
+| Microsoft.KeyVault.CertificateNewVersionCreated | Certificate New Version Created | Triggered when new certificate or new certificate version is created |
+| Microsoft.KeyVault.CertificateNearExpiry | Certificate Near Expiry | Triggered when current version of certificate is about to expire (default  is 30 days before expiration date) |
+| Microsoft.KeyVault.CertificateExpired | Certificate Expired | Triggered when certificate is expired |
+| Microsoft.KeyVault.KeyNewVersionCreated | Key New Version Created | Triggered when new key or new key version is created |
+| Microsoft.KeyVault.KeyNearExpiry | Key Near Expiry | Triggered when current version of key is about to expire (default  is 30 days before expiration date) |
+| Microsoft.KeyVault.KeyExpired | Key Expired | Triggered when key is expired |
+| Microsoft.KeyVault.SecretNewVersionCreated | Secret New Version Created | Triggered when new secret or new secret version is created |
+| Microsoft.KeyVault.SecretNearExpiry | Secret Near Expiry | Triggered when current version of secret is about to expire (default  is 30 days before expiration date) |
+| Microsoft.KeyVault.SecretExpired | Secret Expired | Triggered when secret is expired |
+
+## Event examples
+
+The following example show schema for **Microsoft.KeyVault.SecretNewVersionCreated**.
+
+```JSON
+[
+   {
+      "id":"00eccf70-95a7-4e7c-8299-2eb17ee9ad64",
+      "topic":"/subscriptions/{subscription-id}/resourceGroups/sample-rg/providers/Microsoft.KeyVault/vaults/sample-kv",
+      "subject":"newsecret",
+      "eventType":"Microsoft.KeyVault.SecretNewVersionCreated",
+      "eventTime":"2019-07-25T01:08:33.1036736Z",
+      "data":{
+         "Id":"https://sample-kv.vault.azure.net/secrets/newsecret/ee059b2bb5bc48398a53b168c6cdcb10",
+         "vaultName":"sample-kv",
+         "objectType":"Secret",
+         "objectName ":"newsecret",
+         "version":" ee059b2bb5bc48398a53b168c6cdcb10",
+         "nbf":"1559081980",
+         "exp":"1559082102"
+      },
+      "dataVersion":"1",
+      "metadataVersion":"1"
+   }
+]
+```
+
+## Event properties
+
+An event has the following top-level data:
+
+| Property | Type | Description |
+| ---------- | ----------- |---|
+| id | string | The ID of the object that triggered this event. |
+| vaultName | string | Key vault name of the object that triggered this event. |
+| objectType | string | The type of the object that triggered this event |
+| objectName | string | The name of the object that triggered this event |
+| version | string | The version of the object that triggered this event |
+| nbf | number | Not before date in seconds since 1970-01-01T00:00:00Z of the object that triggered this event |
+| exp | number | The expiration date in seconds since 1970-01-01T00:00:00Z of the object that triggered this event |
+
+
+## Next steps
+
+* For an introduction to Azure Event Grid, see [What is Event Grid?](overview.md)
+* For more information about creating an Azure Event Grid subscription, see [Event Grid subscription schema](subscription-creation-schema.md).
+* To learn more about Key Vault / Event Grid integration, see [Monitoring Key Vault with Azure Event Grid (preview)](../key-vault/event-grid-overview.md)
+* To see a tutorial on Key Vault / Event Grid integration, see [How to: Route Key Vault Events to Automation Runbook (preview)](../key-vault/event-grid-tutorial.md).
+
+- [Azure Key Vault overview](../key-vault/key-vault-overview.md)
+- [Azure Event Grid overview](overview.md)
+- [Monitoring Key Vault with Azure Event Grid (preview)](../key-vault/event-grid-overview.md)
+- [How to: Route Key Vault Events to Automation Runbook (preview)](../key-vault/event-grid-tutorial.md).
+- [Azure Automation overview](../automation/index.yml)

articles/event-grid/event-sources.md

@@ -79,6 +79,18 @@ Subscribe to IoT Hub events to respond to device created, deleted, connected, di
 | [Event schema](event-schema-iot-hub.md) | Shows fields in IoT Hub events. |
 | [Order device connected and device disconnected events](../iot-hub/iot-hub-how-to-order-connection-state-events.md) | Shows how to order device connection state events. |
 
+## Key Vault (preview)
+
+Key Vault integration with Event Grid is currently in preview. 
+
+Subscribe to Key Vault events to be notified when a secret is about to expire, a secret expires, or a secret has a new version available. 
+
+|Title  |Description  |
+|---------|---------|
+| [Monitoring Key Vault events with Azure Event Grid](../key-vault/event-grid-overview.md) | Overview of integrating Key Vault with Event Grid. |
+| [Tutorial: Create and monitor Key Vault events with Event Grid](../key-vault/event-grid-tutorial.md) | Learn how to set up Event Grid notifications for Key Vault. |
+| [Event schema](event-schema-key-vault.md) | Shows fields in Key Vault events. |
+
 ## Media Services
 
 Subscribe to Media Services events to respond to job state events.
@@ -143,7 +155,7 @@ Subscribe to Azure App Configuration events to respond to key-value modification
 |Title | Description |
 |---------|---------|
 | [React to Azure App Configuration events by using Event Grid](../azure-app-configuration/concept-app-configuration-event.md?toc=%2fazure%2fevent-grid%2ftoc.json) | Overview of integrating Azure App Configuration with Event Grid. |
-| [QuickStart: route Azure App Configuration events to a custom web endpoint with Azure CLI](../azure-app-configuration/howto-app-configuration-event.md?toc=%2fazure%2fevent-grid%2ftoc.json) | Shows how to use Azure CLI to send Azure App Configuration events to a WebHook. |
+| [Quickstart: route Azure App Configuration events to a custom web endpoint with Azure CLI](../azure-app-configuration/howto-app-configuration-event.md?toc=%2fazure%2fevent-grid%2ftoc.json) | Shows how to use Azure CLI to send Azure App Configuration events to a WebHook. |
 | [Event schema](event-schema-app-configuration.md) | Shows fields in Azure App Configuration events. |
 
 ## Azure SignalR

articles/event-grid/toc.yml

@@ -162,6 +162,8 @@
       href: event-schema-event-hubs.md
     - name: IoT Hub
       href: event-schema-iot-hub.md
+    - name: Key Vault
+      href: event-schema-key-vault.md
     - name: Media Services
       href: ../media-services/latest/media-services-event-schemas.md?toc=%2fazure%2fevent-grid%2ftoc.json
     - name: Resource groups

articles/key-vault/event-grid-overview.md

@@ -0,0 +1,46 @@
+---
+title: Monitoring Key Vault with Azure Event Grid
+description: Use Azure Event Grid to subscribe to Key Vault events
+services: media-services
+author: msmbaldwin
+manager: rkarlin
+
+ms.service: key-vault
+ms.topic: article
+ms.date: 10/25/2019
+ms.author: mbaldwin
+---
+ 
+# Monitoring Key Vault with Azure Event Grid (preview)
+
+Key Vault integration with Event Grid is currently in preview. It allows users to be notified when the status of a secret stored in key vault has changed. A status change is defined as a secret that is about to expire (within 30 days of expiration), a secret that has expired, or a secret that has a new version available. Notifications for all three secret types (key, certificate, and secret) are supported.
+
+Applications can react to these events using modern serverless architectures, without the need for complicated code or expensive and inefficient polling services. Events are pushed through [Azure Event Grid](https://azure.microsoft.com/services/event-grid/) to event handlers such as [Azure Functions](https://azure.microsoft.com/services/functions/), [Azure Logic Apps](https://azure.microsoft.com/services/logic-apps/), or even to your own Webhook, and you only pay for what you use. For information about pricing, see [Event Grid pricing](https://azure.microsoft.com/pricing/details/event-grid/).
+
+## Key Vault events and schemas
+
+Event grid uses [event subscriptions](../event-grid/concepts.md#event-subscriptions) to route event messages to subscribers. Key Vault events contain all the information you need to respond to changes in your data. You can identify a Key Vault event because the eventType property starts with "Microsoft.KeyVault".
+
+For more information, see the [Key Vault event schema](../event-grid/event-schema-key-vault.md).
+
+> [!NOTE]
+> Events are triggered only for secret versions (all three types) created after subscription is set.
+>
+> For existing secrets, you must generate new versions.
+
+## Practices for consuming events
+
+Applications that handle Key Vault events should follow a few recommended practices:
+
+* Multiple subscriptions can be configured to route events to the same event handler. It is important not to assume events are from a particular source, but to check the topic of the message to ensure that it comes from the key vault you are expecting.
+* Similarly, check that the eventType is one you are prepared to process, and do not assume that all events you receive will be the types you expect.
+* Ignore fields you don't understand.  This practice will help keep you resilient to new features that might be added in the future.
+* Use the "subject" prefix and suffix matches to limit events to a particular event.
+
+## Next steps
+
+- [Azure Key Vault overview](key-vault-overview.md)
+- [Azure Event Grid overview](../event-grid/overview.md)
+- [How to: Route Key Vault Events to Automation Runbook (preview)](event-grid-tutorial.md).
+- [Azure Event Grid event schema for Azure Key Vault (preview)](../event-grid/event-schema-key-vault.md)
+- [Azure Automation overview](../automation/index.yml)

articles/key-vault/event-grid-tutorial.md

@@ -0,0 +1,200 @@
+---
+title: Receive and respond to key vault notifications with Azure Event Grid 
+description: Learn how to integrate Key Vault with Azure Event Grid.
+services: key-vault
+author: msmbaldwin
+manager: rkarlin
+tags: azure-resource-manager
+
+ms.service: key-vault
+ms.topic: tutorial
+ms.date: 10/25/2019
+ms.author: mbaldwin
+
+---
+
+# How to: Receive and respond to key vault notifications with Azure Event Grid (preview)
+
+Key Vault integration with Azure Event Grid, currently in preview, enables users to be notified when the status of a secret stored in key vault has changed. For an overview of the feature, see [Monitoring Key Vault with Azure Event Grid](event-grid-overview.md).
+
+This guide will show you how to receive Key Vault notifications through Azure Event Grid, and how to respond to status changes with Azure Automation.
+
+## Prerequisites
+
+- An Azure Subscription. If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) 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](quick-create-cli.md)
+
+## Concepts
+
+Azure Event Grid is an eventing service for the cloud. In this guide, you will subscribe to events for key vault and route events to Azure Automation. When one of the secrets in the key vault is about to expire, Event Grid is notified of the status change and makes an HTTP POST to the endpoint. A web hook then triggers an Azure Automation execution of PowerShell script.
+
+![image](media/image1.png)
+
+## Create an Azure Automation account
+
+Create an Azure Automation account through the [Azure portal](https://portal.azure.com).
+
+1.  Go to portal.azure.com and log in to your subscription.
+
+1.  In the search box, type in "Automation Accounts".
+
+1.  Under the "Services" Section of the drop-down from the search bar, select "Automation Accounts".
+
+1.  Click Add.
+
+    ![](media/image2.png)
+
+1.  Fill the required information in the "Add Automation Account" Blade and select "Create".
+
+## Create a Runbook
+
+After your Azure Automation account is ready, create a runbook.
+
+![](media/image3.png)
+
+1.  Select the automation account you just created.
+
+1.  Select "Runbooks" under the Process Automation section.
+
+1.  Click the "Create a runbook".
+
+1.  Name your runbook and select "PowerShell" as the runbook type.
+
+1.  Click on the runbook you created, and select the "Edit" Button.
+
+1.  Enter the following code (for testing purposes) and click the "Publish" button. This will output the result of the POST request received.
+
+```azurepowershell
+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." 
+}
+```
+
+![](media/image4.png)
+
+## Create a webhook
+
+Now create a webhook, to trigger your newly created runbook.
+
+1.  Select "Webhooks" from the resources section of the runbook you just published.
+
+1.  Click "Add Webhook".
+
+    ![](media/image5.png)
+
+1.  Select "Create new Webhook".
+
+1. Name the webhook, set an expiration date, and **copy the URL**.
+
+    > [!IMPORTANT] 
+    > You cannot view the URL after you create it. Make sure you save a copy a secure location where you can access it for the remainder of this guide.
+
+1. Click "Parameters and run settings", and select "OK". Do not enter any parameters. This will enable the "Create" button.
+
+1. Select "OK", and select "Create".
+
+    ![](media/image6.png)
+
+## Create an Event Grid subscription
+
+Create an Event Grid subscription through the [Azure portal](https://portal.azure.com).
+
+1.  Open the Azure portal using the following link: https://ms.portal.azure.com/?Microsoft_Azure_KeyVault_ShowEvents=true&Microsoft_Azure_EventGrid_publisherPreview=true
+
+1.  Go to your key vault and select the "Events" tab. If you cannot see the Events tab, make sure that you are using the [preview version of the portal](https://ms.portal.azure.com/?Microsoft_Azure_KeyVault_ShowEvents=true&Microsoft_Azure_EventGrid_publisherPreview=true).
+
+    ![](media/image7.png)
+
+1.  Click the "+ Event Subscription" button.
+
+1.  Create a descriptive name for the subscription.
+
+1.  Choose "Event Grid Schema".
+
+1.  "Topic Resource" should be the key vault you want to monitor for status changes.
+
+1.  For "Filter to Event Types", leave all checked ("9 selected").
+
+1.  For "Endpoint Type", select "Webhook".
+
+1.  Select "Select an endpoint". In the new context pane, paste the webhook URL from the [Create a webhook](#create-a-webhook) step into the "Subscriber Endpoint" field.
+
+1.  Select "Confirm Selection" on the context pane.
+
+1.  Select "Create".
+
+    ![](media/image8.png)
+
+## Test and verify
+
+Verify that your Event Grid subscription is property configured.  This test assumes that you have subscribed to "Secret New Version Created" notification in the [Create an Event Grid subscription](#create-an-event-grid-subscription), and that you have the necessary privileges to create a new version of a secret in a key vault.
+
+![](media/image9.png)
+
+![](media/image10.png)
+
+1.  Go to your key vault on the Azure portal
+
+1.  Create a new secret. For testing purposes, set expiration to date to next day.
+
+1.  Navigate to the events tab in your key vault.
+
+1.  Select the event grid subscription you created.
+
+1.  Under metrics, see if an event was captured. Two events are expected: SecretNewVersion and SecretNearExpiry. This validates that event grid successfully captured the status change of the secret in your key vault.
+
+    ![](media/image11.png)
+
+1.  Go to your Azure Automation account.
+
+1.  Select the "Runbooks" tab, and select the runbook you created.
+
+1.  Select the "Webhooks" tab, and confirm that the "last triggered" timestamp is within 60 seconds of when you created the new secret.  This confirms that Event Grid made a POST to the webhook with the event details of the status change in your key vault, and the webhook was triggered.
+
+    ![](media/image12.png)
+
+1. Return to your Runbook and select the "Overview" Tab.
+
+1. 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.
+
+    ![](media/image13.png)
+
+1. 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 which occurred in the key vault (in this example, Microsoft.KeyVault.SecretNearExpiry) the test was successful.
+
+## Troubleshooting
+
+### Unable to create event subscription
+
+Reregister Event Grid and Key Vault provider in your azure subscription resource providers. See [Azure resource providers and types](../azure-resource-manager/resource-manager-supported-services.md).
+
+## Next steps
+
+Congratulations! If you have followed all the steps above, you are now ready to programmatically respond to status changes of secrets stored in your key vault.
+
+If you have been using a polling-based system to look for status changes of secrets in your key vaults, migrate to using this notification feature. You can also replace the test script in your runbook with code to programmatically renew your secrets when they are about to expire.
+
+Learn more:
+
+- [Azure Key Vault overview](key-vault-overview.md)
+- [Azure Event Grid overview](../event-grid/overview.md)
+- [Monitoring Key Vault with Azure Event Grid (preview)](event-grid-overview.md)
+- [Azure Event Grid event schema for Azure Key Vault (preview)](../event-grid/event-schema-key-vault.md)
+- [Azure Automation overview](../automation/index.yml)