Entregar eventos para os pontos de extremidade protegidos do Microsoft Entra

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

Importante

A verificação de acesso adicional foi introduzida como parte da criação ou atualização da assinatura de evento no dia 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser um proprietário ou ter uma função atribuída na entidade de serviço do aplicativo de destino. Reconfigure o 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, confira 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:

• Entregando eventos a um webhook que esteja no mesmo locatário do Microsoft Entra que a assinatura do evento. Você pode utilizar um usuário do Microsoft Entra ou um aplicativo do Microsoft Entra como autor de assinatura de eventos nesse cenário.

• Entregar eventos a um webhook que esteja em um locatário do Microsoft Entra diferente da assinatura do evento. Você só pode utilizar um aplicativo do Microsoft Entra como um autor de assinatura de eventos nesse cenário.

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

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

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

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

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

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

Esta seção mostra como configurar a assinatura de eventos utilizando um usuário do Microsoft Entra.

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

2. Abra o Azure Shell 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 de 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, em seguida, execute o script.

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

   Observação

   Você não precisa modificar o valor de $eventGridAppId. Nesse script, AzureEventGridSecureWebhookSubscriber é definido como $eventGridRoleName. Lembre-se de que é necessário ser membro da função Administrador de Aplicativos do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook no Microsoft Entra ID para executar esse script.

   Se você vir a seguinte mensagem de erro, precisará elevar a entidade de serviço. A verificação de acesso extra foi introduzida como parte da criação ou atualização da assinatura de evento no dia 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser um proprietário 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 Evento.

   4. Na guia Recursos Adicionais, siga estas etapas:

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

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

      3. Copie a ID do aplicativo do Microsoft Entra ID 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 a URI da ID do aplicativo, confira este artigo.

         

Configurar a assinatura do evento utilizando um aplicativo do Microsoft Entra

Esta seção mostra como configurar a assinatura de eventos utilizando um aplicativo do Microsoft Entra.

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

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

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

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

5. Abra o Azure Shell 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 de 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, em seguida, execute o script.

   • Variáveis:
     • $webhookAppObjectId: ID do aplicativo do Microsoft Entra criado para o webhook
     • $eventSubscriptionWriterAppId: ID do aplicativo do Microsoft Entra para o aplicativo autor de assinatura da Grade de Eventos.

   Observação

   Você não precisa modificar o valor de $eventGridAppId. Neste script, AzureEventGridSecureWebhookSubscriber conforme definido para o $eventGridRoleName. Lembre-se de que é necessário ser membro da função Administrador de Aplicativos do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook no Microsoft Entra ID para executar esse script.

8. Entre como o autor de assinatura da Grade de Eventos do 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
   

   Observação

   Este cenário usa um tópico do sistema. Se você deseja 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 da Grade de Eventos.

    Observação

    Nesse ponto, a Grade de Eventos do Azure agora está passando o token de portador do Microsoft Entra para o cliente webhook em cada mensagem. 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 a assinatura do evento e o ponto de extremidade do webhook que estão em diferentes locatários do Microsoft Entra, é necessário usar um aplicativo do Microsoft Entra ID, conforme mostrado nessa seção. Atualmente, não é possível proteger essa conexão usando um usuário do Microsoft Entra ID no portal do Microsoft Entra.

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

Locatário A

Execute etapas a seguir no Locatário A:

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

2. Crie um segredo para o aplicativo do 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 da Grade de Eventos do Azure. Atribua a função Colaborador da Grade de Eventos ao aplicativo do Microsoft Entra do autor de assinatura da Grade de Eventos. Essa etapa permite que o aplicativo tenha acesso ao recurso da Grade de Eventos do Azure quando você entrar no Azure com o aplicativo do Microsoft Entra usando a CLI do Azure.

Locatário B

Execute etapas a seguir no Locatário B:

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

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

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

   • Variáveis:

     • $webhookAadTenantId: a 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, em seguida, execute o script.

   • Variáveis:

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

     • $eventSubscriptionWriterAppId: ID do aplicativo do Entra para o autor de assinatura da Grade de Eventos

       Observação

       Você não precisa modificar o valor de $eventGridAppId. Neste script, AzureEventGridSecureWebhookSubscriber é definido para o $eventGridRoleName. Lembre-se de que é necessário ser membro da função Administrador de Aplicativos do Microsoft Entra ou ser proprietário da entidade de serviço do aplicativo webhook no Microsoft Entra ID para executar esse script.

   Se você vir a seguinte mensagem de erro, precisará elevar a entidade de serviço. A verificação de acesso extra foi introduzida como parte da criação ou atualização da assinatura de evento no dia 30 de março de 2021 para resolver uma vulnerabilidade de segurança. A entidade de serviço do cliente assinante precisa ser um proprietário 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.
   

Locatário A

De volta ao Locatário A, execute etapas a seguir:

1. Abra o Azure Shell e entre como o autor de assinaturas da Grade de Eventos do 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
   

   Observação

   Neste cenário, estamos usando um Tópico do Sistema da Grade de Eventos. Consulte este documento 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 da Grade de Eventos.

   Observação

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

Próximas etapas

• Para obter informações conceituais, consulte Entrega de eventos de webhook.
• Para obter informações sobre o monitoramento de entregas de evento, consulte Entrega de mensagens da Grade de Eventos do Monitor.
• Para saber mais sobre a chave de autenticação, confira Event Grid security and authentication (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, confira Event Grid subscription schema (Esquema de assinatura da Grade de Eventos).