对 Azure 事件网格资源的访问进行身份验证Authenticating access to Azure Event Grid resources

本文提供了关于以下方案的信息:This article provides information on the following scenarios:

  • 使用共享访问签名 (SAS) 或密钥对将事件发布到 Azure 事件网格主题的客户端进行身份验证。Authenticate clients that publish events to Azure Event Grid topics using Shared Access Signature (SAS) or key.
  • 使用 Azure Active Directory (Azure AD) 保护 Webhook 终结点,以向事件网格进行身份验证,从而将事件传递到终结点。Secure your webhook endpoint using Azure Active Directory (Azure AD) to authenticate Event Grid to deliver events to the endpoint.

使用 SAS 或密钥对发布客户端进行身份验证Authenticate publishing clients using SAS or key

自定义主题使用共享访问签名 (SAS) 或密钥身份验证。Custom topics use either Shared Access Signature (SAS) or key authentication. 建议使用 SAS,但密钥身份验证提供简单的编程,并与多个现有 webhook 发布服务器兼容。We recommend SAS, but key authentication provides simple programming, and is compatible with many existing webhook publishers.

HTTP 标头中包括身份验证值。You include the authentication value in the HTTP header. 对于 SAS,使用 aeg-sas-token 作为标头值。For SAS, use aeg-sas-token for the header value. 对于密钥身份验证,使用 aeg-sas-key 作为标头值。For key authentication, use aeg-sas-key for the header value.

密钥身份验证Key authentication

密钥身份验证是最简单的身份验证形式。Key authentication is the simplest form of authentication. 使用以下格式:aeg-sas-key: <your key>Use the format: aeg-sas-key: <your key>

例如,使用以下项传递密钥:For example, you pass a key with:

aeg-sas-key: VXbGWce53249Mt8wuotr0GPmyJ/nDT4hgdEj9DpBeRr38arnnm5OFg==

SAS 令牌SAS tokens

事件网格的 SAS 令牌包括资源、过期时间和签名。SAS tokens for Event Grid include the resource, an expiration time, and a signature. SAS 令牌的格式是:r={resource}&e={expiration}&s={signature}The format of the SAS token is: r={resource}&e={expiration}&s={signature}.

资源是要将事件发送到的事件网格主题的路径。The resource is the path for the event grid topic to which you're sending events. 例如,有效的资源路径是 https://<yourtopic>.<region>.eventgrid.chinacloudapi.cn/eventGrid/api/events?api-version=2019-06-01For example, a valid resource path is: https://<yourtopic>.<region>.eventgrid.chinacloudapi.cn/eventGrid/api/events?api-version=2019-06-01. 若要查看所有受支持的 API 版本,请参阅 Microsoft.EventGrid 资源类型To see all the supported API versions, see Microsoft.EventGrid resource types.

从密钥生成签名。You generate the signature from a key.

例如,有效的 aeg-sas-token 值是:For example, a valid aeg-sas-token value is:

aeg-sas-token: r=https%3a%2f%2fmytopic.eventgrid.chinacloudapi.cn%2feventGrid%2fapi%2fevent&e=6%2f15%2f2017+6%3a20%3a15+PM&s=a4oNHpRZygINC%2fBPjdDLOrc6THPy3tDcGHw1zP4OajQ%3d

以下示例会创建用于事件网格的 SAS 令牌:The following example creates a SAS token for use with Event Grid:

static string BuildSharedAccessSignature(string resource, DateTime expirationUtc, string key)
{
    const char Resource = 'r';
    const char Expiration = 'e';
    const char Signature = 's';

    string encodedResource = HttpUtility.UrlEncode(resource);
    var culture = CultureInfo.CreateSpecificCulture("en-US");
    var encodedExpirationUtc = HttpUtility.UrlEncode(expirationUtc.ToString(culture));

    string unsignedSas = $"{Resource}={encodedResource}&{Expiration}={encodedExpirationUtc}";
    using (var hmac = new HMACSHA256(Convert.FromBase64String(key)))
    {
        string signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(unsignedSas)));
        string encodedSignature = HttpUtility.UrlEncode(signature);
        string signedSas = $"{unsignedSas}&{Signature}={encodedSignature}";

        return signedSas;
    }
}

静态加密Encryption at rest

由事件网格服务写入到磁盘的所有事件或数据都使用 Microsoft 托管密钥进行加密,同时确保进行的是静态加密。All events or data written to disk by the Event Grid service is encrypted by a Microsoft-managed key ensuring that it's encrypted at rest. 此外,根据事件网格重试策略,事件或数据的最长保留期为 24 小时。Additionally, the maximum period of time that events or data retained is 24 hours in adherence with the Event Grid retry policy. 事件网格将在 24 小时或事件生存时间到期(无论哪个在先)后自动删除所有事件或数据。Event Grid will automatically delete all events or data after 24 hours, or the event time-to-live, whichever is less.

对 Webhook 终结点的事件传递进行身份验证Authenticate event delivery to webhook endpoints

下面各部分介绍了如何对 Webhook 终结点的事件传递进行身份验证。The following sections describe how to authenticate event delivery to webhook endpoints. 无论使用何种方法,都需要使用验证握手机制。You need to use a validation handshake mechanism irrespective of the method you use. 有关详细信息,请参阅 Webhook 事件传递See Webhook event delivery for details.

使用 Azure Active Directory (Azure AD)Using Azure Active Directory (Azure AD)

可以保护 Webhook 终结点,具体方法为使用 Azure Active Directory (Azure AD) 向事件网格进行身份验证和授权,以将事件传递到终结点。You can secure your webhook endpoint by using Azure Active Directory (Azure AD) to authenticate and authorize Event Grid to deliver events to your endpoints. 需要创建 Azure AD 应用程序,并在授权事件网格的应用程序中创建角色和服务主体,同时还需要将事件订阅配置为使用 Azure AD 应用程序。You'll need to create an Azure AD Application, create a role and service principle in your application authorizing Event Grid, and configure the event subscription to use the Azure AD Application. 了解如何为事件网格配置 Azure Active DirectoryLearn how to configure Azure Active Directory with Event Grid.

使用客户端密码作为查询参数Using client secret as a query parameter

在创建事件订阅时,可以通过向 Webhook URL 中添加查询参数来保护 Webhook 终结点。You can secure your webhook endpoint by adding query parameters to the webhook URL when creating an Event Subscription. 将这些查询参数之一设置为客户端密码,如访问令牌或共享密码。Set one of these query parameters to be a client secret such as an access token or a shared secret. Webhook 可以使用该机密来识别事件是否来自具有有效权限的事件网格。The webhook can use the secret to recognize the event is coming from Event Grid with valid permissions. 事件网格会在前往 Webhook 的每个事件传递中包括这些查询参数。Event Grid will include these query parameters in every event delivery to the webhook. 如果更新了客户端密码,还需要更新事件订阅。If the client secret is updated, event subscription also needs to be updated. 为了避免在此密码轮换期间出现传递失败,让 Webhook 在有限的时间内同时接受新旧密码。To avoid delivery failures during this secret rotation, make the webhook accept both old and new secrets for a limited duration.

由于查询参数可能包含客户端密码,因此需要格外小心地处理它们。As query parameters could contain client secrets, they are handled with extra care. 它们以加密的形式存储,不可由服务操作员访问。They are stored as encrypted and not accessible to service operators. 它们不作为服务日志/跟踪的一部分进行记录。They are not logged as part of the service logs/traces. 编辑事件订阅时,除非在 Azure CLI 中使用了 --include-full-endpoint-url 参数,否则,不会显示或返回查询参数。When editing the Event Subscription, the query parameters aren't displayed or returned unless the --include-full-endpoint-url parameter is used in Azure CLI.

若要详细了解如何将事件传递到 Webhook,请参阅 Webhook 事件传递For more information on delivering events to webhooks, see Webhook event delivery

Important

Azure 事件网格只支持 HTTPS Webhook 终结点。Azure Event Grid only supports HTTPS webhook endpoints.

后续步骤Next steps