Partilhar via

Autenticar com o agente MQTT usando 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 Webhook permite que pontos de extremidade HTTP externos (webhooks ou funções) autentiquem conexões MQTT (Transporte de Telemetria de Enfileiramento de Mensagens) dinamicamente. Este método usa a validação do Microsoft Entra ID JSON Web Token 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 da Lista de Revogação de Certificados. 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 oferece suporte a políticas de autenticação flexíveis e centralizadas em diversas frotas de dispositivos e casos de uso.

Pré-requisitos

  • Um namespace de Grade de Eventos com uma identidade gerenciada atribuída pelo sistema ou pelo usuário.
  • Um webhook externo ou função do Azure.
  • Acesso concedido à identidade gerenciada do namespace 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. Crie um namespace e configure seus subrecursos.
  2. Habilite uma identidade gerenciada em seu namespace de Grade de Eventos.
  3. Conceda à identidade gerenciada acesso à sua função ou webhook do Azure.
  4. Configure configurações personalizadas de webhook em seu namespace de Grade de Eventos.
  5. Conecte os seus clientes ao namespace Event Grid e autentique-se através do webhook ou da função.

Criar um namespace e configurar seus subrecursos

Para criar um namespace e configurar seus subrecursos, siga as instruções em Guia de início rápido: publicar e assinar mensagens MQTT em um namespace de 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, nas variáveis do modelo de tópico e na configuração do enriquecimento de roteamento.

Habilite uma identidade gerenciada em seu namespace de Grade de Eventos

Para habilitar uma identidade gerenciada atribuída pelo sistema em seu namespace de 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 de Grade de Eventos.

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

Conceda à identidade gerida do seu namespace na Event Grid o acesso apropriado à função ou webhook de destino no Azure.

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

Criar uma aplicação do Microsoft Entra

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

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

    Captura de tela que mostra a página Visão geral de um aplicativo Microsoft Entra ID com a ID do aplicativo (cliente) realçada.

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

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

    Captura de tela que mostra o URI da ID do aplicativo Microsoft Entra.

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

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

  1. Aceda à sua aplicação Azure Functions.

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

    Captura de ecrã que mostra a página Autenticação.

  3. Na página Adicionar um provedor de identidade , para Provedor de Identidade, selecione 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 o URL do emissor no formulário https://login.microsoftonline.com/<tenantid>/v2.0.

      Captura de tela que mostra Adicionar um provedor de identidade com a Microsoft como um provedor de identidade.

  5. Para Audiências de token permitidas, adicione o valor de 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 ao sistema usada para gerar o token. Você pode encontrar essa ID no aplicativo corporativo do recurso 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 de ID do Microsoft Entra usando a identidade gerenciada com o URI da ID do aplicativo como recursos.
  2. Use esse token para invocar a função do Azure incluindo-a no cabeçalho da solicitação.

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

Configure configurações de autenticação de webhook personalizadas em seu namespace de Grade de Eventos usando o portal do Azure e a CLI do Azure. Você cria o namespace primeiro e, em seguida, atualiza-o.

Utilizar o portal do Azure

  1. Vá para o namespace da Grade de Eventos no portal do Azure.

  2. Na página Event Grid Namespace, selecione Configuração no menu à esquerda.

  3. Na seção Autenticação de Webhook personalizada , 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 da URL para o qual o serviço de Grade de Eventos envia solicitações de webhook autenticadas usando a identidade gerenciada especificada.
    3. URI de audiência de token: insira o valor do ID ou URI do aplicativo Microsoft Entra para obter o token de acesso a ser incluído como o token de portador nas solicitações de entrega.
    4. ID do locatário do Microsoft Entra ID: insira o valor do ID do locatário do Microsoft Entra usado para adquirir o token de portador para entrega de webhook autenticado.

  4. Selecione Aplicar.

    Captura de ecrã que mostra a configuração da autenticação de webhook para um namespace do Event Grid.

Utilizar 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 seus valores reais. Preencha os espaços reservados na assinatura, grupo de recursos, identidade, ID do aplicativo, URL e ID do locatário. Para melhorar o desempenho e a confiabilidade da autenticação baseada em webhook para o broker MQTT da Grade de Eventos, é altamente recomendável que você habilite o suporte a HTTP/2 para seu ponto de extremidade webhook.

Detalhes da API Webhook

Cabeçalhos da requisição

Autorização: Token ao portador

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

Solicitar carga útil

{
    "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 carga útil

Campo Obrigatório/Opcional Descrição
clientId Obrigatório ID do cliente do pacote MQTT CONNECT.
userName Opcional Nome de usuário do pacote MQTT CONNECT.
password Opcional Senha do pacote MQTT CONNECT na codificação Base64.
authenticationMethod Opcional Método de autenticação do pacote MQTT CONNECT (somente MQTT5).
authenticationData Opcional Dados de autenticação do pacote MQTT CONNECT na codificação Base64 (somente MQTT5).
clientCertificate Opcional Certificado de cliente em formato PEM.
clientCertificateChain Opcional Outros certificados fornecidos pelo cliente necessários para construir a cadeia do certificado do cliente para o certificado da Autoridade de Certificação.
userProperties Opcional Propriedades do usuário do pacote CONNECT (somente MQTT5).

Carga útil de resposta

Resposta com êxito

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 dos campos de resposta

Campo Descrição
decision (obrigatório) A decisão de autenticação é ou allowdeny.
clientAuthenticationName Nome de autenticação do cliente (nome da identidade). (Obrigatório quando decision definido como allow.)
attributes Dicionário com atributos. Chave é o nome do atributo e o valor é um int/string/array. (Opcional quando decision definido como allow.)
expiration Data de validade no formato de hora Unix. (Opcional quando decision definido como allow.)
errorReason Mensagem de erro se decision estiver definida como deny. Este erro é registado. (Opcional quando decision definido como deny.)

Exemplos de tipos de atributos suportados

"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 encaixa <int32/string/array_of_strings>) são usados como atributos. No exemplo, num_attr_pos, num_attr_neg, str_attr, e str_list_attr as declarações têm tipos de dados corretos e são usados como atributos.

Conteúdo relacionado

  • Last updated on