Deliver events to Azure Active Directory protected endpoints

This article describes how to use Azure Active Directory (Azure AD) to secure the connection between your event subscription and your webhook endpoint. For an overview of Azure AD applications and service principals, see Microsoft identity platform (v2.0) overview.

This article uses the Azure portal for demonstration, however the feature can also be enabled using CLI, PowerShell, or the SDKs.

Important

Additional access check has been introduced as part of create or update of event subscription on March 30, 2021 to address a security vulnerability. The subscriber client's service principal needs to be either an owner or have a role assigned on the destination application service principal. Please reconfigure your AAD Application following the new instructions below.

Deliver events to a Webhook in the same Azure AD tenant

Secure WebHook delivery with Azure AD in Azure Event Grid

Based on the diagram above, follow the next steps to configure the tenant.

Configure the event subscription by using Azure AD User

  1. Create an Azure AD Application for the webhook configured to work with the Microsoft directory (Single tenant).

  2. Open the Azure Shell in the tenant and select the PowerShell environment.

  3. Modify the value of $webhookAadTenantId to connect to the tenant.

    • Variables:
      • $webhookAadTenantId: Azure Tenant ID
    PS /home/user>$webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
    PS /home/user>Connect-AzureAD -TenantId $webhookAadTenantId
    
  4. Open the following script and update the values of $webhookAppObjectId and $eventSubscriptionWriterUserPrincipalName with your identifiers, then continue to run the script.

    • Variables:
      • $webhookAppObjectId: Azure AD Application ID created for the webhook
      • $eventSubscriptionWriterUserPrincipalName: Azure User Principal Name of the user who will create event subscription

    Note

    You don't need to modify the value of $eventGridAppId, for this script we set AzureEventGridSecureWebhookSubscriber as the value for the $eventGridRoleName. Remember, you must be a member of the Azure AD Application Administrator role to execute this script.

  5. In the portal, when creating an event subscription, follow these steps:

    1. Select the endpoint type as Web Hook.

    2. Specify the endpoint URI.

      Select endpoint type webhook

    3. Select the Additional features tab at the top of the Create Event Subscriptions page.

    4. On the Additional features tab, do these steps:

      1. Select Use AAD authentication, and configure the tenant ID and application ID:

      2. Copy the Azure AD tenant ID from the output of the script and enter it in the AAD Tenant ID field.

      3. Copy the Azure AD application ID from the output of the script and enter it in the AAD Application ID field. You can use the AAD Application ID URI instead of using the application ID. For more information about application ID URI, see this article.

        Secure Webhook action

Configure the event subscription by using Azure AD Application

  1. Create an Azure AD Application for the Event Grid subscription writer configured to work with the Microsoft directory (Single tenant).

  2. Create a secret for the Azure AD Application previously created and save the value (you'll need this value later).

  3. Go to the Access control (IAM) in the Event Grid Topic and add the role assignment of the Event Grid subscription writer as Event Grid Contributor, this step will allow us to have access to the Event Grid resource when we logged-in into Azure with the Azure AD Application by using the Azure CLI.

  4. Create an Azure AD Application for the webhook configured to work with the Microsoft directory (Single tenant).

  5. Open the Azure Shell in the tenant and select the PowerShell environment.

  6. Modify the value of $webhookAadTenantId to connect to the tenant.

    • Variables:
      • $webhookAadTenantId: Azure Tenant ID
    PS /home/user>$webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
    PS /home/user>Connect-AzureAD -TenantId $webhookAadTenantId
    
  7. Open the following script and update the values of $webhookAppObjectId and $eventSubscriptionWriterAppId with your identifiers, then continue to run the script.

    • Variables:
      • $webhookAppObjectId: Azure AD Application ID created for the webhook
      • $eventSubscriptionWriterAppId: Azure AD Application ID for Event Grid subscription writer

    Note

    You don't need to modify the value of $eventGridAppId, for this script we set AzureEventGridSecureWebhookSubscriber as the value for the $eventGridRoleName. Remember, you must be a member of the Azure AD Application Administrator role to execute this script.

  8. Login as the Event Grid subscription writer Azure AD Application by running the command.

    PS /home/user>az login --service-principal -u [REPLACE_WITH_EVENT_GRID_SUBSCRIPTION_WRITER_APP_ID] -p [REPLACE_WITH_EVENT_GRID_SUBSCRIPTION_WRITER_APP_SECRET_VALUE] --tenant [REPLACE_WITH_TENANT_ID]
    
  9. Create your subscription by running the command.

    PS /home/user>az eventgrid system-topic event-subscription create --name [REPLACE_WITH_SUBSCRIPTION_NAME] -g [REPLACE_WITH_RESOURCE_GROUP] --system-topic-name [REPLACE_WITH_SYSTEM_TOPIC] --endpoint [REPLACE_WITH_WEBHOOK_ENDPOINT] --event-delivery-schema [REPLACE_WITH_WEBHOOK_EVENT_SCHEMA] --azure-active-directory-tenant-id [REPLACE_WITH_TENANT_ID] --azure-active-directory-application-id-or-uri [REPLACE_WITH_APPLICATION_ID_FROM_SCRIPT] --endpoint-type webhook
    

    Note

    In this scenario we are using an Event Grid System Topic. See here, if you want to create a subscription for Custom Topics or Event Grid Domains by using the Azure CLI.

  10. If everything was correctly configured, you can successfully create the webhook subscription in your Event Grid Topic.

    Note

    At this point Event Grid is now passing the Azure AD Bearer token to the webhook client in every message, you'll need to validate the Authorization token in your webhook.

Deliver events to a Webhook in a different Azure AD tenant

To enable a secure webhook subscription across multiple tenants you'll need to do this task by using an Azure AD Application, this process isn't currently available by using the Azure AD user from the portal.

Multitenant events with Azure AD and Webhooks

Based on the diagram above, follow the next steps to configure both tenants.

  1. Create an Azure AD Application for the Event Grid subscription writer configured to work with any Azure AD directory (Multitenant) in the Tenant A.

  2. Create a secret for the Azure AD Application previously created in the Tenant A and save the value (you'll need this value later).

  3. In the Tenant A, go to the Access control (IAM) in the Event Grid Topic and add the role assignment of the Azure AD Application of the Event Grid subscription writer as Event Grid Contributor, this step will allow us to have access to the Event Grid resource when we logged-in into Azure with the Azure AD Application by using the Azure CLI.

  4. Create an Azure AD Application for the webhook configured to work with the Microsoft directory (Single tenant) in the Tenant B.

  5. Open the Azure Shell in the Tenant B and select the PowerShell environment.

  6. Modify the $webhookAadTenantId value to connect to the Tenant B.

    • Variables:
      • $webhookAadTenantId: Azure Tenant ID for the Tenant B
    PS /home/user>$webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
    PS /home/user>Connect-AzureAD -TenantId $webhookAadTenantId
    
  7. Open the following script and update the values of $webhookAppObjectId and $eventSubscriptionWriterAppId with your identifiers, then continue to run the script.

    • Variables:
      • $webhookAppObjectId: Azure AD Application ID created for the webhook
      • $eventSubscriptionWriterAppId: Azure AD Application ID for Event Grid subscription writer

    Note

    You don't need to modify the value of $eventGridAppId, for this script we set AzureEventGridSecureWebhookSubscriber as the value for the $eventGridRoleName. Remember, you must be a member of the Azure AD Application Administrator role to execute this script.

  8. Open the Azure Shell in the Tenant A and login as the Event Grid subscription writer Azure AD Application by running the command.

    PS /home/user>az login --service-principal -u [REPLACE_WITH_APP_ID] -p [REPLACE_WITH_SECRET_VALUE] --tenant [REPLACE_WITH_TENANT_ID]
    
  9. Create your subscription by running the command.

    PS /home/user>az eventgrid system-topic event-subscription create --name [REPLACE_WITH_SUBSCRIPTION_NAME] -g [REPLACE_WITH_RESOURCE_GROUP] --system-topic-name [REPLACE_WITH_SYSTEM_TOPIC] --endpoint [REPLACE_WITH_WEBHOOK_ENDPOINT] --event-delivery-schema [REPLACE_WITH_WEBHOOK_EVENT_SCHEMA] --azure-active-directory-tenant-id [REPLACE_WITH_TENANT_B_ID] --azure-active-directory-application-id-or-uri [REPLACE_WITH_APPLICATION_ID_FROM_SCRIPT] --endpoint-type webhook
    

    Note

    In this scenario we are using an Event Grid System Topic. See here, if you want to create a subscription for Custom Topics or Event Grid Domains by using the Azure CLI.

  10. If everything was correctly configured, you can successfully create the webhook subscription in your Event Grid Topic.

    Note

    At this point Event Grid is now passing the Azure AD Bearer token to the webhook client in every message, you'll need to validate the Authorization token in your webhook.

Next steps