将事件发布到受 Azure Active Directory 保护的终结点Publish events to Azure Active Directory protected endpoints

本文介绍如何使用 Azure Active Directory (Azure AD) 来保护事件订阅和 Webhook 终结点之间的连接 。This article describes how to use Azure Active Directory (Azure AD) to secure the connection between your event subscription and your webhook endpoint. 有关 Azure AD 应用程序和服务主体的概述,请参阅 Microsoft 标识平台 (v2.0) 概述For an overview of Azure AD applications and service principals, see Microsoft identity platform (v2.0) overview.

本文使用 Azure 门户进行演示,但也可通过 CLI、PowerShell 或 SDK 来启用此功能。This article uses the Azure portal for demonstration, however the feature can also be enabled using CLI, PowerShell, or the SDKs.

重要

2021 年 3 月 30 日,事件创建或更新中引入了附加访问检查,以解决安全漏洞。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. 请按照下面的新说明重新配置 AAD 应用程序。Please reconfigure your AAD Application following the new instructions below.

创建 Azure AD 应用程序Create an Azure AD Application

通过为受保护的终结点创建 Azure AD 应用程序,向 Azure AD 注册 Webhook。Register your Webhook with Azure AD by creating an Azure AD application for your protected endpoint. 请参阅方案:受保护的 Web APISee Scenario: Protected web API. 将受保护的 API 配置为通过守护程序应用进行调用。Configure your protected API to be called by a daemon app.

允许事件网格使用 Azure AD 应用程序Enable Event Grid to use your Azure AD Application

本部分说明如何启用事件网格来使用 Azure AD 应用程序。This section shows you how to enable Event Grid to use your Azure AD application.

备注

你必须是 Azure AD 应用程序管理员角色的成员才能执行此脚本。You must be a member of the Azure AD Application Administrator role to execute this script.

连接到 Azure 租户Connect to your Azure tenant

首先,使用 Connect-AzureAD 命令连接到 Azure 租户。First, connect to your Azure tenant using the Connect-AzureAD command.

$myWebhookAadTenantId = "<Your Webhook's Azure AD tenant id>"

Connect-AzureAD -AzureEnvironmentName AzureChinaCloud -TenantId $myWebhookAadTenantId

创建 Microsoft.EventGrid 服务主体Create Microsoft.EventGrid service principal

运行以下脚本,为 Microsoft.EventGrid 创建服务主体(如果尚不存在)。Run the following script to create the service principal for Microsoft.EventGrid if it doesn't already exist.

# This is the "Azure Event Grid" Azure Active Directory (AAD) AppId
$eventGridAppId = "4962773b-9cdb-44cf-a8bf-237846a00ab7"

# Create the "Azure Event Grid" AAD Application service principal if it doesn't exist
$eventGridSP = Get-AzureADServicePrincipal -Filter ("appId eq '" + $eventGridAppId + "'")
if ($eventGridSP -match "Microsoft.EventGrid")
{
    Write-Host "The Service principal is already defined.`n"
} else {
    # Create a service principal for the "Azure Event Grid" AAD Application and add it to the role
    Write-Host "Creating the Azure Event Grid service principal"
    $eventGridSP = New-AzureADServicePrincipal -AppId $eventGridAppId
}

为应用程序创建角色Create a role for your application

运行以下脚本,为你的 Azure AD 应用程序创建角色。Run the following script to create a role for your Azure AD application. 在此示例中,角色名称为:AzureEventGridSecureWebhookSubscriber。In this example, the role name is: AzureEventGridSecureWebhookSubscriber. 修改 PowerShell 脚本的 $myTenantId 以使用 Azure AD 租户 ID,并使用 Azure AD 应用程序的对象 ID 修改 $myAzureADApplicationObjectIdModify the PowerShell script's $myTenantId to use your Azure AD Tenant ID, and $myAzureADApplicationObjectId with the Object ID of your Azure AD Application

# This is your Webhook's Azure AD Application's ObjectId. 
$myWebhookAadApplicationObjectId = "<Your webhook's aad application object id>"

# This is the name of the new role we will add to your Azure AD Application
$eventGridRoleName = "AzureEventGridSecureWebhookSubscriber"
       
# Create an application role of given name and description
Function CreateAppRole([string] $Name, [string] $Description)
{
    $appRole = New-Object Microsoft.Open.AzureAD.Model.AppRole
    $appRole.AllowedMemberTypes = New-Object System.Collections.Generic.List[string]
    $appRole.AllowedMemberTypes.Add("Application");
    $appRole.AllowedMemberTypes.Add("User");
    $appRole.DisplayName = $Name
    $appRole.Id = New-Guid
    $appRole.IsEnabled = $true
    $appRole.Description = $Description
    $appRole.Value = $Name;
    return $appRole
}
       
# Get my Azure AD Application, it's roles and service principal
$myApp = Get-AzureADApplication -ObjectId $myWebhookAadApplicationObjectId
$myAppRoles = $myApp.AppRoles

Write-Host "App Roles before addition of new role.."
Write-Host $myAppRoles
       
# Create the role if it doesn't exist
if ($myAppRoles -match $eventGridRoleName)
{
    Write-Host "The Azure Event Grid role is already defined.`n"
} else {      
    # Add our new role to the Azure AD Application
    Write-Host "Creating the Azure Event Grid role in Azure Ad Application: " $myWebhookAadApplicationObjectId
    $newRole = CreateAppRole -Name $eventGridRoleName -Description "Azure Event Grid Role"
    $myAppRoles.Add($newRole)
    Set-AzureADApplication -ObjectId $myApp.ObjectId -AppRoles $myAppRoles
}

# print application's roles
Write-Host "My Azure AD Application's Roles: "
Write-Host $myAppRoles

为创建事件订阅的客户端创建角色分配Create role assignment for the client creating event subscription

应在 Webhook Azure AD 应用中为创建事件订阅的 AAD 应用或 AAD 用户创建角色分配。The role assignment should be created in the Webhook Azure AD App for the AAD app or AAD user creating the event subscription. 根据是 AAD 应用还是 AAD 用户在创建事件订阅,使用以下脚本之一。Use one of the scripts below depending on whether an AAD app or AAD user is creating the event subscription.

重要

2021 年 3 月 30 日,事件创建或更新中引入了附加访问检查,以解决安全漏洞。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. 请按照下面的新说明重新配置 AAD 应用程序。Please reconfigure your AAD Application following the new instructions below.

为事件订阅 AAD 应用创建角色分配Create role assignment for an event subscription AAD app

# This is the app id of the application which will create event subscription. Set to $null if you are not assigning the role to app.
$eventSubscriptionWriterAppId = "<the app id of the application which will create event subscription>"

$myServicePrincipal = Get-AzureADServicePrincipal -Filter ("appId eq '" + $myApp.AppId + "'")

$eventSubscriptionWriterSP = Get-AzureADServicePrincipal -Filter ("appId eq '" + $eventSubscriptionWriterAppId + "'")
if ($eventSubscriptionWriterSP -eq $null)
{
        $eventSubscriptionWriterSP = New-AzureADServicePrincipal -AppId $eventSubscriptionWriterAppId
}

Write-Host "Creating the Azure Ad App Role assignment for application: " $eventSubscriptionWriterAppId
$eventGridAppRole = $myApp.AppRoles | Where-Object -Property "DisplayName" -eq -Value $eventGridRoleName
New-AzureADServiceAppRoleAssignment -Id $eventGridAppRole.Id -ResourceId $myServicePrincipal.ObjectId -ObjectId $eventSubscriptionWriterSP.ObjectId -PrincipalId $eventSubscriptionWriterSP.ObjectId

为事件订阅 AAD 用户创建角色分配Create role assignment for an event subscription AAD user

# This is the user principal name of the user who will create event subscription. Set to $null if you are not assigning the role to user.
$eventSubscriptionWriterUserPrincipalName = "<the user principal name of the user who will create event subscription>"

$myServicePrincipal = Get-AzureADServicePrincipal -Filter ("appId eq '" + $myApp.AppId + "'")
    
Write-Host "Creating the Azure Ad App Role assignment for user: " $eventSubscriptionWriterUserPrincipalName
$eventSubscriptionWriterUser = Get-AzureAdUser -ObjectId $eventSubscriptionWriterUserPrincipalName
$eventGridAppRole = $myApp.AppRoles | Where-Object -Property "DisplayName" -eq -Value $eventGridRoleName
New-AzureADUserAppRoleAssignment -Id $eventGridAppRole.Id -ResourceId $myServicePrincipal.ObjectId -ObjectId $eventSubscriptionWriterUser.ObjectId -PrincipalId $eventSubscriptionWriterUser.ObjectId

为事件网格服务主体创建角色分配Create role assignment for Event Grid Service principal

运行 New-AzureADServiceAppRoleAssignment 命令,将事件网格服务主体分配给你在上一步中创建的角色。Run the New-AzureADServiceAppRoleAssignment command to assign Event Grid service principal to the role you created in the previous step.

$eventGridAppRole = $myApp.AppRoles | Where-Object -Property "DisplayName" -eq -Value $eventGridRoleName
New-AzureADServiceAppRoleAssignment -Id $eventGridAppRole.Id -ResourceId $myServicePrincipal.ObjectId -ObjectId $eventGridSP.ObjectId -PrincipalId $eventGridSP.ObjectId

运行以下命令以输出稍后将使用的信息。Run the following commands to output information that you'll use later.

Write-Host "My Webhook's Azure AD Tenant Id:  $myWebhookAadTenantId"
Write-Host "My Webhook's Azure AD Application Id: $($myApp.AppId)"
Write-Host "My Webhook's Azure AD Application ObjectId Id$($myApp.ObjectId)"

配置事件订阅Configure the event subscription

创建事件订阅时,请执行以下步骤:When creating an event subscription, follow these steps:

  1. 选择“Web Hook”作为终结点类型。Select the endpoint type as Web Hook.

  2. 指定终结点 URI。Specify the endpoint URI.

    选择终结点类型 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. 选择“使用 AAD 身份验证”,并配置租户 ID 和应用程序 ID:Select Use AAD authentication, and configure the tenant ID and application ID:

    2. 从脚本输出中复制 Azure AD 租户 ID,将其输入“AAD 租户 ID”字段中。Copy the Azure AD tenant ID from the output of the script and enter it in the AAD Tenant ID field.

    3. 从脚本输出中复制 Azure AD 应用程序 ID,将其输入“AAD 应用程序 ID”字段中。Copy the Azure AD application ID from the output of the script and enter it in the AAD Application ID field. 或者,可以使用 AAD 应用程序 ID URI。Alternatively, you can use the AAD Application ID URI. 有关应用程序 ID URI 的详细信息,请参阅本文For more information about application ID URI, see this article.

      保护 Webhook 操作

后续步骤Next steps