Partilhar via

Autenticar com o corretor MQTT usando autenticação de webhook personalizada (Pré-visualização)

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

A autenticação Webhook permite que terminais HTTP externos (webhooks ou funções) autentiquem conexões MQTT de forma dinâmica. Este método usa a validação JWT do Microsoft Entra ID para garantir o acesso seguro.

Quando um cliente tenta se conectar, o broker invoca um ponto de extremidade HTTP definido pelo usuário que valida credenciais como tokens SAS, nomes de usuário/senhas ou até mesmo executa verificações de CRL (Lista de Certificados Revogados). 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.

Observação

Esta funcionalidade está atualmente em pré-visualização.

Pré-requisitos

Para usar a autenticação de webhook personalizada para namespaces, você precisa ter os seguintes pré-requisitos:

  • Um namespace de Grade de Eventos com identidade gerenciada atribuída pelo sistema ou pelo usuário.
  • A função Webhook Externo ou a função Azure.
  • Conceda acesso à identidade gerenciada do namespace da grade de eventos para a função /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 a identidade gerenciada em seu namespace da Grade de Eventos.
  3. Conceda à identidade gerida acesso à sua função do Azure ou ao Webhook.
  4. Configurar definições personalizadas de webhook no namespace da Event Grid
  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

Siga as instruções do Guia de início rápido: publique e assine mensagens MQTT no Namespace do Event Grid com o portal do Azure para criar um namespace e configurar os seus subrecursos. Ignore as etapas de criação do certificado e do cliente, pois 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 a identidade gerenciada em seu namespace da Grade de Eventos

Use o seguinte comando para habilitar a identidade gerenciada atribuída pelo sistema em seu namespace de Grade de Eventos:

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 controlada o acesso apropriado à 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 estas etapas:

Criar uma aplicação do Microsoft Entra

  1. Crie uma aplicação Microsoft Entra no Microsoft Entra ID.

  2. Na página de visão geral do aplicativo, anote a ID do aplicativo (cliente).

    Captura de tela mostrando a página Visão geral de um aplicativo Microsoft Entra ID com a ID do aplicativo ou cliente realçada.

  3. No menu à esquerda, selecione Expor uma API e, em seguida, selecione Adicionar ao lado de URI da ID do aplicativo.

  4. Anote o URI da ID do aplicativo Na página Editar URI da ID do aplicativo , selecione Salvar.

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

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

Se você tiver uma Função do Azure básica criada a partir do portal do Azure, siga estas etapas para configurar a autenticação e validar o token de ID do Microsoft Entra criado usando uma identidade gerenciada.

  1. Navegue até seu aplicativo de função do Azure.

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

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

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

  4. No registo da aplicação, siga estes passos:

    1. Em ID do cliente, insira a ID do cliente do aplicativo Microsoft Entra que você anotou anteriormente.

    2. Para URL do emissor, adicione o URL do emissor no formato: https://login.microsoftonline.com/<tenantid>/v2.0.

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

  5. Nas audiências de token permitidas, adicione o URI UD do aplicativo Microsoft Entra que você anotou anteriormente.

  6. Na seção Verificações adicionais , siga estas etapas:

    1. Para Desenvolvimento de aplicativos cliente, selecione Permitir solicitações de aplicativos cliente específicos.
    2. Na página 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.

  7. Escolha configurações adicionais com base em 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

Nesta etapa, você define configurações personalizadas de autenticação de webhook em seu namespace de Grade de Eventos usando o portal do Azure e a CLI do Azure. Você precisa criar o namespace primeiro e, em seguida, atualizá-lo usando as etapas a seguir.

Utilize o portal do Azure

  1. Navegue até o seu namespace Event Grid no portal 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. Selecione Tipo de identidade gerenciada .

    2. Para URL de Webhook, insira o valor do ponto de extremidade de URL para o qual o serviço Event Grid envia solicitações de webhook autenticadas usando a identidade gerida especificada.

    3. Para URI de audiência do token, insira o valor do ID de aplicação ou URI da aplicação Microsoft Entra para obter o token de acesso que deve ser incluído como um token de portador nas solicitações de entrega.

    4. Para ID de locatário do Microsoft Entra, insira o valor do ID de locatário do Microsoft Entra usado para adquirir o token de portador para entrega de webhook autenticado.

    5. 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

Use o comando a seguir para atualizar seu namespace com a configuração de autenticação de webhook personalizada.

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

Detalhes da API Webhook

Cabeçalhos dos Pedidos

  • Autorização: Token ao portador
    • token é um token do Microsoft Entra para a identidade gerida configurada para acionar 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
ID do cliente Obrigatório ID do cliente do pacote MQTT CONNECT.
nome de utilizador Opcional Nome de usuário do pacote MQTT CONNECT.
palavra-passe Opcional Senha do pacote MQTT CONNECT na codificação base64.
método de autenticação Opcional Método de autenticação do pacote MQTT CONNECT (somente MQTT5).
dados de autenticação Opcional Dados de autenticação do pacote MQTT CONNECT na codificação base64 (somente MQTT5).
certificado do cliente Opcional Certificado de cliente em formato PEM.
clientCertificateChain Opcional Certificados adicionais fornecidos pelo cliente são necessários para criar a cadeia que vai do certificado do cliente ao certificado da autoridade de certificação.
propriedadesDoUtilizador 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
Decisão (obrigatório) Decisão de autenticação. Pode ser permitido ou negado.
NomeDeAutenticaçãoDoCliente Nome de autenticação do cliente (nome da identidade). (Obrigatório quando a Decisão está definida para permitir).
atributos Dicionário com atributos. Key é o nome do atributo e o valor pode ser int/string/array. (Opcional quando a Decisão está definida para permitir).
expiração Data de validade no formato de hora Unix. (Opcional quando a decisão está configurada para permitir)
razãoErro Mensagem de erro se a decisão estiver definida para negar. Este erro é registado. (Opcional quando a decisão é configurada para negar)

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

Conteúdo relacionado