Autenticar com namespaces usando tokens da Web JSON

Este artigo mostra como autenticar com o namespace Grade de Eventos do Azure usando Tokens Web JSON.

O agente MQTT da Grade de Eventos do Azure dá suporte à autenticação JWT personalizada, que permite que os clientes se conectem e se autentiquem com um namespace de Grade de Eventos usando Tokens Web JSON emitidos por qualquer provedor de identidade, além da ID do Microsoft Entra.

Pré-requisitos

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

• Provedor de identidade que pode emitir Json Web Tokens.
• Certificado de autoridade de certificação que inclui suas chaves públicas usadas para validar os tokens de cliente.
• Conta do Azure Key Vault para hospedar o certificado da autoridade de certificação que inclui suas chaves públicas.

Etapas de alto nível

Para usar a autenticação JWT personalizada para namespaces, execute estas etapas:

1. Crie um namespace e configure seus subrecursos.
2. Habilite a identidade gerenciada em seu namespace da Grade de Eventos.
3. Crie uma conta do Cofre da Chave do Azure que hospede o certificado da autoridade de certificação que inclui suas chaves públicas.
4. Adicione atribuição de função no Cofre de Chaves do Azure para a identidade gerenciada do namespace.
5. Definir configurações de autenticação personalizadas no namespace da Grade de Eventos
6. Seus clientes podem se conectar ao namespace Event Grid usando os tokens fornecidos pelo seu provedor de identidade.

Criar um namespace e configurar seus subrecursos

Siga as instruções de Guia de início rápido: publique e assine mensagens MQTT no namespace de grade de eventos com o portal do Azure para criar um namespace e configurar 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 de cliente são usados na consulta de grupo de clientes, variáveis de modelo de tópico e configuração de enriquecimento de roteamento.

Habilite a identidade gerenciada em seu namespace da Grade de Eventos

O namespace usa a identidade gerenciada para acessar sua instância do Azure Key Vault para obter o certificado do servidor para seu domínio personalizado. 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.

Criar uma conta do Azure Key Vault e carregar o certificado do servidor

1. Use o seguinte comando para criar uma conta do Azure Key Vault:

   az keyvault create --name "<your-unique-keyvault-name>" --resource-group "<resource group name>" --location "centraluseaup" 
   

2. Use o seguinte comando para importar um certificado para o Cofre da Chave do Azure

   az keyvault certificate import --vault-name "<your-key-vault-name>" -n "<cert name>" -f "<path to your certificate pem file> " 
   

   Nota

   Seu certificado deve incluir o nome de domínio no nome alternativo de assunto para DNS. Para obter mais informações, consulte Tutorial: Importar um certificado no Cofre de Chaves do Azure.

Adicionar atribuição de função no Cofre da Chave do Azure para a identidade gerenciada do namespace

Você precisa fornecer acesso ao namespace para acessar sua conta do Azure Key Vault usando as seguintes etapas:

1. Obter ID principal de identidade gerenciada do sistema de namespace de Grade de Eventos usando o seguinte comando

   $principalId=(az eventgrid namespace show --resource-group <resource group name> --name <namespace name> --query identity.principalId -o tsv) 
   

2. Obtenha sua ID de recurso do cofre da Chave do Azure.

   $keyVaultResourceId=(az keyvault show --resource-group <resource group name> --name <your key vault name> --query id -o tsv) 
   

3. Adicione atribuição de função no Cofre da Chave para a identidade gerenciada do namespace.

   az role assignment create --role "Key Vault Certificate User" --assignee $principalId --scope $keyVaultResourceId 
   

   Para obter mais informações sobre o acesso ao Cofre da Chave e a experiência do portal, consulte Fornecer acesso a chaves, certificados e segredos do Cofre da Chave com um controle de acesso baseado em função do Azure.

Definir configurações de autenticação personalizadas no namespace da Grade de Eventos

Nesta etapa, você define configurações de autenticação personalizadas 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.

Utilizar o portal do Azure

1. Navegue até o namespace da Grade de Eventos no portal do Azure.

2. Na página Namespace da Grade de Eventos , selecione Configuração no menu à esquerda.

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

   1. Selecione Ativar autenticação JWT personalizada.

   2. Emissor de token: insira o valor das declarações do emissor dos tokens JWT, apresentados pelos clientes MQTT.

   3. Selecione Adicionar certificado do emissor

      

   4. Na nova página, especifique valores para as propriedades a seguir.

      1. URL do certificado: o Identificador de Certificado do certificado do emissor no Cofre da Chave do Azure que você criou. Em vez disso, você pode escolher Selecionar um certificado usando um cofre de chaves para selecionar o certificado e o cofre de chaves de suas assinaturas.

      2. Identidade: a identidade usada para autenticar com o Cofre da Chave para acessar o certificado do emissor que foi criado.

      3. Selecione Adicionar.

         

4. De volta à página Configuração , selecione Aplicar.

   Nota

   Você pode adicionar até dois iss certificados para fins de rotação de certificados/chaves.

Utilizar a CLI do Azure

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

az resource update --resource-type Microsoft.EventGrid/namespaces --api-version 2024-06-01-preview --ids /subscriptions/69f9e5ac-ca07-42cc-98d2-4718d033bcc5/resourceGroups/dummy-cd-test/providers/Microsoft.EventGrid/namespaces/dummy-cd-test2 --set properties.topicSpacesConfiguration.clientAuthentication='{\"customJwtAuthentication\":{\"tokenIssuer\":\"dmpypin-issuer\",\"issuerCertificates\":[{\"certificateUrl\":\"https://dummyCert-cd-test.vault.azure.net/certificates/dummy-cd-test/4f844b284afd487e9bba0831191087br1\",\"identity\":{\"type\":\"SystemAssigned\"}}]}}' 

Formato JSON Web Token

Os Json Web Tokens são divididos nas seções JWT Header e JWT payload.

Cabeçalho JWT

O cabeçalho deve conter pelo menos typ e alg campos. typ deve ser JWS sempre e alg deve ser RS256sempre. O cabeçalho do token deve ser o seguinte:

{
    "typ": "JWT",
    "alg": "RS256"
}

Carga útil JWT

A Grade de Eventos requer as seguintes declarações: iss, sub, aud, exp, nbf.

Nome	Descrição
iss	Emitente. O valor em JWT deve corresponder ao emissor na configuração do namespace Event Grid para autenticação JWT personalizada.
sub	Assunto. O valor é usado como nome de identidade de autenticação.
aud	Audiência. O valor pode ser uma cadeia de caracteres ou uma matriz de cadeias de caracteres. O valor deve conter o nome de host do namespace da Grade de Eventos padrão e/ou o domínio personalizado para esse namespace da Grade de Eventos (se configurado). A audiência pode conter outras cadeias de caracteres, mas exigimos que pelo menos uma dessas cadeias seja um nome de host de namespace de Grade de Eventos padrão ou um domínio personalizado para esse namespace.
exp	Caducidade. Tempo Unix quando o JWT expira.
nbf	Não antes. Tempo unitário quando o JWT se torna válido.

A Grade de Eventos mapeia todas as declarações para atributos do cliente se elas tiverem um dos seguintes tipos: int32, string, array of strings. As declarações isspadrão , sub, , audexp, são nbf excluídas dos atributos do cliente. No exemplo JWT a seguir, apenas três declarações são convertidas em atributos de cliente, num_attr, str_attr, str_list_attr, porque eles têm tipos int32corretos , string, array of strings. incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 não são convertidos em atributos de cliente, porque têm tipos errados: float, array of integers, object.

{
    "iss": "correct_issuer",
    "sub": "d1",
    "aud": "testns.mqtt-broker-int.azure.net",
    "exp": 1712876224,
    "nbf": 1712869024,
    "num_attr": 1,
    "str_attr": "some string",
    "str_list_attr": [
        "string 1",
        "string 2"
    ],
    "incorrect_attr_1": 1.23,
    "incorrect_attr_2": [
        1,
        2,
        3
    ],
    "incorrect_attr_3": {
        "field": "value"
    }
}

Conteúdos relacionados

• Autenticação de cliente MQTT