Entregar eventos para pontos de extremidade protegidos do Microsoft Entra

Este artigo descreve como usar o Microsoft Entra ID para proteger a conexão entre sua assinatura de evento e seu ponto de extremidade webhook. Ele usa o portal do Azure para demonstração, no entanto, o recurso também pode ser habilitado usando CLI, PowerShell ou SDKs.

Importante

A verificação de acesso adicional foi introduzida como parte da criação ou atualização da assinatura de evento em 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser proprietária ou ter uma função atribuída na entidade de serviço do aplicativo de destino. Reconfigure seu aplicativo Microsoft Entra seguindo as novas instruções abaixo. Para obter uma visão geral dos aplicativos e entidades de serviço do Microsoft Entra, consulte Visão geral da plataforma de identidade da Microsoft (v2.0).

Cenários

Este artigo explica como implementar os dois cenários a seguir em detalhes:

• Entrega de eventos para um webhook que está no mesmo locatário do Microsoft Entra que a assinatura do evento. Você pode usar um usuário do Microsoft Entra ou um aplicativo do Microsoft Entra como o gravador de assinatura de evento nesse cenário.

• Entrega de eventos para um webhook que está em um locatário do Microsoft Entra diferente da assinatura do evento. Você só pode usar um aplicativo Microsoft Entra como um gravador de assinatura de evento nesse cenário.

  No primeiro cenário, você executa todas as etapas ou scripts em um único locatário que tenha a assinatura de evento e o webhook. E, no segundo cenário, você executa algumas etapas no locatário que tem a assinatura do evento e algumas etapas no locatário que tem o webhook.

Entregar eventos a um Webhook no mesmo locatário do Microsoft Entra

O diagrama a seguir mostra como os eventos da Grade de Eventos são entregues a um webhook no mesmo locatário que a assinatura do evento.

Há duas subseções nesta seção. Leia os dois cenários ou aquele em que está interessado.

• Configurar a assinatura do evento usando um usuário do Microsoft Entra ID
• Configurar a assinatura do evento usando um aplicativo Microsoft Entra ID

Configurar a assinatura do evento usando um usuário do Microsoft Entra

Esta seção mostra como configurar a assinatura do evento usando um usuário do Microsoft Entra.

1. Crie um aplicativo Microsoft Entra para o webhook configurado para funcionar com o Microsoft Entra (locatário único).

2. Abra o Shell do Azure no locatário e selecione o ambiente do PowerShell.

3. Modifique o valor de $webhookAadTenantId para se conectar ao locatário.

   • Variáveis:
     • $webhookAadTenantId: ID do locatário do Azure

   $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
   Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"
   

4. Abra o script a seguir e atualize os valores de $webhookAppObjectId e $eventSubscriptionWriterUserPrincipalName com seus identificadores e continue a executar o script.

   • Variáveis:
     • $webhookAppObjectId: ID do aplicativo Microsoft Entra criado para o webhook
     • $eventSubscriptionWriterUserPrincipalName: Nome principal do usuário do Azure do usuário que cria a assinatura de evento

   Nota

   Não é necessário modificar o valor de $eventGridAppId. Neste script, AzureEventGridSecureWebhookSubscriber é definido para o $eventGridRoleName. Lembre-se, você deve ser membro da função de Administrador de Aplicativo do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook na ID do Microsoft Entra para executar esse script.

   Se você vir a seguinte mensagem de erro, você precisa elevar para a entidade de serviço. Uma verificação de acesso extra foi introduzida como parte da criação ou atualização da assinatura de evento em 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser proprietária ou ter uma função atribuída na entidade de serviço do aplicativo de destino.

   New-MgServicePrincipalAppRoleAssignment: Error occurred while executing NewServicePrincipalAppRoleAssignment
   Code: Authorization_RequestDenied
   Message: Insufficient privileges to complete the operation.
   

5. No portal, ao criar uma assinatura de evento, siga estas etapas:

   1. Selecione o tipo de ponto de extremidade como Web Hook.

   2. Especifique o URI do ponto de extremidade.

      

   3. Selecione a guia Recursos adicionais na parte superior da página Criar assinaturas de eventos.

   4. Na guia Recursos adicionais, siga estas etapas:

      1. Selecione Usar autenticação do Microsoft Entra e configure a ID do locatário e a ID do aplicativo:

      2. Copie o ID do locatário do Microsoft Entra da saída do script e insira-o no campo ID do locatário do Microsoft Entra.

      3. Copie a ID do aplicativo Microsoft Entra da saída do script e insira-a no campo ID do aplicativo Microsoft Entra. Você pode usar o URI da ID do Aplicativo Microsoft Entra em vez de usar a ID do aplicativo. Para obter mais informações sobre o URI de ID do aplicativo, consulte este artigo.

         

Configurar a assinatura do evento usando um aplicativo Microsoft Entra

Esta seção mostra como configurar a assinatura do evento usando um aplicativo Microsoft Entra.

1. Crie um aplicativo Microsoft Entra para o gravador de assinatura da Grade de Eventos configurado para funcionar com o Microsoft Entra (locatário único).

2. Crie um segredo para o aplicativo Microsoft Entra e salve o valor (você precisará desse valor mais tarde).

3. Vá para a página Controle de acesso (IAM) para o tópico Grade de Eventos e atribua a função de Colaborador da Grade de Eventos ao aplicativo de gravador de assinatura da Grade de Eventos. Esta etapa permite que você tenha acesso ao recurso Grade de Eventos quando você entrou no Azure com o aplicativo Microsoft Entra usando a CLI do Azure.

4. Crie um aplicativo Microsoft Entra para o webhook configurado para funcionar com o Microsoft Entra (locatário único).

5. Abra o Shell do Azure no locatário e selecione o ambiente do PowerShell.

6. Modifique o valor de $webhookAadTenantId para se conectar ao locatário.

   • Variáveis:
     • $webhookAadTenantId: ID do locatário do Azure

   $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
   Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"
   

7. Abra o script a seguir e atualize os valores de $webhookAppObjectId e $eventSubscriptionWriterAppId com seus identificadores e continue a executar o script.

   • Variáveis:
     • $webhookAppObjectId: ID do aplicativo Microsoft Entra criado para o webhook
     • $eventSubscriptionWriterAppId: ID do aplicativo Microsoft Entra para o aplicativo escritor de assinatura Event Grid.

   Nota

   Não é necessário modificar o valor de $eventGridAppId. Neste script, AzureEventGridSecureWebhookSubscriber conforme definido para o $eventGridRoleName. Lembre-se, você deve ser membro da função de Administrador de Aplicativo do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook na ID do Microsoft Entra para executar esse script.

8. Entre como o gravador de assinatura da Grade de Eventos Aplicativo Microsoft Entra executando o comando.

   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. Crie sua assinatura executando o comando.

   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
   

   Nota

   Este cenário usa um tópico do sistema. Se você quiser criar uma assinatura para tópicos ou domínios personalizados usando a CLI do Azure, consulte Referência da CLI.

10. Se tudo estiver configurado corretamente, você poderá criar com êxito a assinatura do webhook no tópico Grade de Eventos.

    Nota

    Neste ponto, a Grade de Eventos agora está passando o token de portador do Microsoft Entra para o cliente webhook em todas as mensagens. Você precisará validar o token de autorização em seu webhook.

Entregar eventos a um Webhook em um locatário diferente do Microsoft Entra

Para proteger a conexão entre sua assinatura de evento e seu ponto de extremidade webhook que estão em locatários diferentes do Microsoft Entra, você precisa usar um aplicativo Microsoft Entra ID, conforme mostrado nesta seção. Atualmente, não é possível proteger essa conexão usando um usuário do Microsoft Entra ID no portal do Azure.

Com base no diagrama, siga as próximas etapas para configurar ambos os locatários.

Inquilino A

Execute as seguintes etapas no Locatário A:

1. Crie um aplicativo Microsoft Entra para o gravador de assinatura da Grade de Eventos configurado para funcionar com qualquer Microsoft Entra (multilocatário).

2. Crie um segredo para o aplicativo Microsoft Entra e salve o valor (você precisará desse valor mais tarde).

3. Navegue até a página Controle de acesso (IAM) para o tópico Grade de eventos. Atribua a função de Colaborador da Grade de Eventos ao aplicativo Microsoft Entra do gravador de assinatura da Grade de Eventos. Esta etapa permite que o aplicativo tenha acesso ao recurso Grade de Eventos quando você entra no Azure com o aplicativo Microsoft Entra usando a CLI do Azure.

Inquilino B

Execute as seguintes etapas no Locatário B:

1. Crie um Aplicativo Microsoft Entra para o webhook configurado para funcionar com o Microsoft Entra (locatário único).

2. Abra o Shell do Azure e selecione o ambiente do PowerShell.

3. Modifique o valor $webhookAadTenantId para se conectar ao locatário B.

   • Variáveis:

     • $webhookAadTenantId: ID do Locatário do Azure para o Locatário B

     $webhookAadTenantId = "[REPLACE_WITH_YOUR_TENANT_ID]"
     Connect-MgGraph -TenantId $webhookAadTenantId -Scopes "Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All"
     

4. Abra o script a seguir e atualize os valores de $webhookAppObjectId e $eventSubscriptionWriterAppId com seus identificadores e continue a executar o script.

   • Variáveis:

     • $webhookAppObjectId: ID do aplicativo Microsoft Entra criado para o webhook

     • $eventSubscriptionWriterAppId: ID do aplicativo Microsoft Entra para gravador de assinatura da Grade de Eventos

       Nota

       Não é necessário modificar o valor de $eventGridAppId. Neste script, AzureEventGridSecureWebhookSubscriber está definido como $eventGridRoleName. Lembre-se, você deve ser membro da função de Administrador de Aplicativo do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook na ID do Microsoft Entra para executar esse script.

   Se você vir a seguinte mensagem de erro, você precisa elevar para a entidade de serviço. Uma verificação de acesso extra foi introduzida como parte da criação ou atualização da assinatura de evento em 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser proprietária ou ter uma função atribuída na entidade de serviço do aplicativo de destino.

   New-MgServicePrincipalAppRoleAssignment: Error occurred while executing NewServicePrincipalAppRoleAssignment
   Code: Authorization_RequestDenied
   Message: Insufficient privileges to complete the operation.
   

Inquilino A

De volta ao Locatário A, execute as seguintes etapas:

1. Abra o Shell do Azure e entre como o gravador de assinatura da Grade de Eventos Aplicativo Microsoft Entra executando o comando.

   az login --service-principal -u [REPLACE_WITH_APP_ID] -p [REPLACE_WITH_SECRET_VALUE] --tenant [REPLACE_WITH_TENANT_ID]
   

2. Crie sua assinatura executando o comando.

   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
   

   Nota

   Neste cenário, estamos usando um tópico do sistema de grade de eventos. Veja aqui, se você quiser criar uma assinatura para tópicos personalizados ou domínios da Grade de Eventos usando a CLI do Azure.

3. Se tudo estiver configurado corretamente, você poderá criar com êxito a assinatura do webhook no tópico Grade de Eventos.

   Nota

   Neste ponto, a Grade de Eventos agora está passando o token Microsoft Entra Bearer para o cliente webhook em todas as mensagens. Você precisará validar o token de Autorização em seu webhook.

Próximos passos

• Para obter informações conceituais, consulte Entrega de eventos WebHook.
• Para obter informações sobre como monitorar entregas de eventos, consulte Monitorar a entrega de mensagens da grade de eventos.
• Para obter mais informações sobre a chave de autenticação, consulte Segurança e autenticação da grade de eventos.
• Para obter mais informações sobre como criar uma assinatura da Grade de Eventos do Azure, consulte Esquema de assinatura da Grade de Eventos.