Autenticar com o agente MQTT usando a autenticação de webhook personalizada

Este artigo mostra como autenticar com namespaces da Grade de Eventos do Azure usando um webhook ou uma função do Azure.

A autenticação de webhook permite que pontos de extremidade HTTP externos (webhooks ou funções) autentiquem conexões MQTT (Transporte Telemétrico de Enfileiramento de Mensagens) dinamicamente. Esse método usa a validação do Token Web JSON da ID do Microsoft Entra para garantir o acesso seguro.

Quando um cliente tenta se conectar, o agente invoca um ponto de extremidade HTTP definido pelo usuário que valida credenciais, como tokens de Assinatura de Acesso Compartilhado, nomes de usuário e senhas, ou até mesmo executa verificações de Lista de Revogação de Certificado. O webhook avalia a solicitação e retorna uma decisão de permitir ou negar a conexão, juntamente com metadados opcionais para autorização refinada. Essa abordagem dá suporte a políticas de autenticação flexíveis e centralizadas em diversas frotas de dispositivos e casos de uso.

Pré-requisitos

• Um namespace da Grade de Eventos com uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário.
• Um webhook externo ou uma função do Azure.
• Acesso concedido à identidade gerenciada do namespace da Grade de Eventos para a função ou webhook do Azure.

Etapas de alto nível

Para usar a autenticação de webhook personalizada para namespaces, siga estas etapas:

1. Criar um namespace e configurar seus sub-recursos.
2. Habilite uma identidade gerenciada no namespace da Grade de Eventos.
3. Conceda à identidade gerenciada acesso à sua função do Azure ou webhook.
4. Defina as configurações de webhook personalizadas no namespace da Grade de Eventos.
5. Conecte seus clientes ao namespace do Grade de Eventos do Azure e seja autenticado por meio do webhook ou da função.

Criar um namespace e configurar seus sub-recursos

Para criar um namespace e configurar seus sub-recursos, siga as instruções no Início Rápido: Publicar e assinar mensagens MQTT em um namespace da Grade de Eventos com o portal do Azure. Ignore as etapas para criar um certificado e um cliente porque as identidades do cliente vêm do token fornecido. Os atributos do cliente são baseados nas declarações personalizadas no token do cliente. Os atributos do cliente são usados na consulta do grupo de clientes, em variáveis do modelo de tópico e na configuração de enriquecimento do roteamento.

Habilitar uma identidade gerenciada no namespace da Grade de Eventos

Para habilitar uma identidade gerenciada atribuída pelo sistema no namespace da Grade de Eventos, use o seguinte comando:

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}" 

Para obter informações sobre como configurar identidades atribuídas pelo sistema e pelo usuário usando o portal do Azure, consulte Habilitar identidade gerenciada para um namespace da Grade de Eventos.

Conceder à identidade gerenciada acesso apropriado a uma função ou webhook

Conceda à identidade gerenciada do namespace da Grade de Eventos o acesso apropriado à função ou ao webhook do Azure de destino.

Para configurar a autenticação personalizada para uma função do Azure, siga as próximas etapas.

Criar um aplicativo do Microsoft Entra

1. Crie um aplicativo do Microsoft Entra no Microsoft Entra ID.

2. Na página Visão geral do aplicativo, anote o valor da ID do aplicativo (cliente).

   

3. No menu à esquerda, selecione Expor uma API. Ao lado de URI da ID do Aplicativo, escolha Adicionar.

4. Anote o valor do URI da ID do aplicativo no painel Editar URI da ID do aplicativo e selecione Salvar.

   

Configurar a autenticação para uma função do Azure

Se você tiver uma função básica do Azure criada no portal do Azure, configure a autenticação e valide o token de ID do Microsoft Entra que foi criado usando uma identidade gerenciada.

1. Acesse seu aplicativo do Azure Functions.

2. No menu à esquerda, selecione Autenticação e, em seguida, selecione Adicionar provedor de identidade.

   

3. Na página Adicionar um provedor de identidade, para Provedor de Identidade, selecione a Microsoft na lista suspensa.

4. Na seção Registro de aplicativo, especifique valores para as seguintes propriedades:

   1. ID do aplicativo (cliente): insira a ID do cliente do aplicativo Microsoft Entra que você anotou anteriormente.

   2. URL do emissor: adicione a URL do emissor no formulário https://login.microsoftonline.com/<tenantid>/v2.0.

      

5. Para Audiências de token permitidas, adicione o URI da ID do aplicativo do aplicativo Microsoft Entra que você anotou anteriormente.

6. Na seção Verificações adicionais, para Desenvolvimento de aplicativos cliente, selecione Permitir solicitações de aplicativos cliente específicos.

7. No painel Aplicativos cliente permitidos, insira a ID do cliente da identidade gerenciada atribuída pelo sistema usada para gerar o token. Você pode encontrar essa ID no aplicativo empresarial do recurso do Microsoft Entra ID.

8. Escolha outras configurações com base em seus requisitos específicos e selecione Adicionar.

Agora, gere e use o token de ID do Microsoft Entra.

1. Gere um token do Microsoft Entra ID usando a identidade gerenciada com o URI da ID do aplicativo como os recursos.
2. Use esse token para invocar a função do Azure incluindo-a no cabeçalho da solicitação.

Configurar configurações personalizadas de autenticação de webhook no namespace do Event Grid

Defina as configurações personalizadas de autenticação de webhook no namespace da Grade de Eventos usando o portal do Azure e a CLI do Azure. Crie o namespace primeiro e, em seguida, atualize-o.

Use o portal do Azure

1. Acesse o namespace da Grade de Eventos no portal do Azure.

2. Na página Namespace da Grade de Eventos, selecione Configuração no menu do lado esquerdo.

3. Na seção Autenticação personalizada do Webhook, especifique valores para as seguintes propriedades:

   1. Tipo de identidade gerenciada: Selecione Usuário atribuído.
   2. URL do webhook: Insira o valor do ponto de extremidade de URL em que o serviço de Grade de Eventos envia solicitações de webhook autenticadas usando a identidade gerenciada especificada.
   3. URI do público-alvo do token: Insira o valor da ID ou URI do aplicativo Do Microsoft Entra para que o token de acesso seja incluído como o token de portador nas solicitações de entrega.
   4. ID do locatário do Microsoft Entra ID: Insira o valor da ID de locatário do Microsoft Entra usada para adquirir o token de portador para entrega de webhook autenticada.

4. Selecione Aplicar.

   

Usar a CLI do Azure

Para atualizar seu namespace com a configuração de autenticação de webhook personalizada, use o seguinte comando:

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2025-04-01-preview \ 
    --identity-type UserAssigned \ 
    --identity-user-assigned-identities "/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX={}" \ 
    --set properties.isZoneRedundant=true \ 
        properties.topicSpacesConfiguration.state=Enabled \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.type=UserAssigned \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.userAssignedIdentity="/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.endpointUrl="https://XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryApplicationIdOrUri="api://XXXXXXXXXXX/.default" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryTenantId="XXXXXXXXXXX" 

Substitua <NAMESPACE_NAME> e <RESOURCE_GROUP_NAME> pelos valores reais. Preencha os espaços reservados na assinatura, grupo de recursos, identidade, ID do aplicativo, URL e ID do locatário. Para aprimorar o desempenho e a confiabilidade da autenticação baseada em webhook para o agente MQTT da Grade de Eventos, é altamente recomendável habilitar o suporte HTTP/2 para o ponto de extremidade do webhook.

Detalhes da API do Webhook

Cabeçalhos da solicitação

Autorização: Token de portador

O token é um token do Microsoft Entra para a identidade gerenciada que foi configurada para chamar o webhook.

Payload da solicitação

{
    "clientId": "<string>",
    "userName": "<string>",
    "password": "<base64 encoded bytes>",
    "authenticationMethod": "<string>",
    "authenticationData": "<base64 encoded bytes>",
    "clientCertificate": "<certificate in PEM format>",
    "clientCertificateChain": "<certificates from chain in PEM format>"
}

Descrições dos campos de conteúdo

Payload de resposta

Resposta bem-sucedida

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 
    "decision": "allow", 
    "clientAuthenticationName": "<string>", 
    "attributes": { 
        "attr": "<int/string/array_of_strings>", 
        ... 
    }, 
    "expiration": "<unix time format>" 
} 

Resposta negada

HTTP/1.1 400 Bad Request 
Content-Type: application/json 

{ 
    "decision": "deny", 
    "errorReason": "<string>" 
}

Descrições do campo de resposta

Exemplos de tipos de atributo com suporte

"num_attr_pos": 1, 
"num_attr_neg": -1, 
"str_attr": "str_value", 
"str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
] 

Todos os tipos de dados corretos (número que se ajusta <int32/string/array_of_strings>) são usados como atributos. No exemplo, as declarações num_attr_pos, num_attr_neg, str_attr e str_list_attr têm tipos de dados corretos e são usadas como atributos.

Conteúdo relacionado

• Autenticação do cliente MQTT
• Autenticar cliente usando JWT personalizado