Use OAuth 2.0 JSON Web Tokens (JWT) para autenticar em namespaces

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

O agente MQTT da Grade de Eventos do Azure dá suporte à autenticação JWT OAuth 2.0, 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 OAuth 2.0 para namespaces, você precisa ter os seguintes pré-requisitos:

• Provedor de identidade que pode emitir Tokens Web JSON.
• Certificado da Autoridade Certificadora que inclui as suas chaves públicas usadas para validar os tokens de cliente (Cofre de Chaves) ou arquivo PEM dos seus certificados de chave pública (upload direto).

Etapas de alto nível

Para usar a autenticação JWT do OAuth 2.0 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. Configure as configurações de autenticação do OAuth 2.0 no namespace da Grade de Eventos seguindo estas etapas:

   1. Crie uma conta do Cofre da Chave do Azure que hospede o certificado da autoridade de certificação que inclui suas chaves públicas e adicione atribuição de função no Cofre da Chave para a identidade gerenciada do namespace.
   2. Ou carregue o arquivo PEM de seus certificados de chave pública para o namespace.

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

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.

Definir configurações de autenticação JWT do OAuth 2.0 no namespace da Grade de Eventos -Key Vault

Primeiro, crie uma conta do Cofre de Chaves do Azure, carregue o certificado do servidor e atribua à identidade gerenciada do namespace uma função apropriada no cofre de chaves. Em seguida, você define configurações de autenticação personalizadas em seu namespace de Grade de Eventos usando o portal do Azure ou a CLI do Azure. Você precisa criar o namespace primeiro e, em seguida, atualizá-lo usando as etapas a seguir.

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 "centraluseuap" 
   

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. Obtenha o ID principal da identidade gerida do namespace do sistema do Event Grid, usando o seguinte comando

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

2. Obtenha a sua ID de recurso do Cofre de 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.

Usar o portal do Azure para configurar a autenticação

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 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 JWTs, apresentadas pelos clientes MQTT.

   3. Para Certificado do emissor, selecione Azure Key Vault.

      

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

      1. URL do certificado: o identificador do certificado de emissor no Azure Key Vault que foi criado. 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 Azure Key Vault para aceder ao 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/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.EventGrid/namespaces/sample-namespace \
  --set properties.topicSpacesConfiguration.clientAuthentication='{
    \"customJwtAuthentication\":{
      \"tokenIssuer\":\"sample-issuer\",
      \"issuerCertificates\":[
        {
          \"certificateUrl\":\"https://sample-vault.vault.azure.net/certificates/sample-cert/12345abcdef67890\",
          \"identity\":{
            \"type\":\"UserAssigned\",
            \"userAssignedIdentity\":\"/subscriptions/1111a1a1-bb2b-cc3c-dd4d-ffffee5e5e5e/resourceGroups/sample-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/sample-identity\"
          }
        }
      ]
    }
  }'
 

Formato JSON Web Token

Os Web Tokens JSON precisam ter seções de cabeçalho JWT, carga útil JWT e assinatura JWT.

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	Público. Valor é 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). O público alvo pode incluir outras cadeias de caracteres, mas exigimos que pelo menos uma dessas cadeias seja um nome de host de namespace padrão do Evento Grade ou um domínio personalizado para este namespace.
exp	Caducidade. Hora Unix de expiração do JWT.
nbf	Não antes. Tempo unitário quando o JWT se torna válido.

Event Grid mapeia todas as claims para atributos do cliente se tiverem um dos seguintes tipos: int32, string, array of strings. As declarações iss padrão, sub, aud, exp são 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"
    }
}

Configurar configurações de autenticação JWT do OAuth 2.0 no seu namespace do Event Grid - Carregamento direto

Nesta etapa, você define configurações de autenticação JWT 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 JWTs, apresentadas pelos clientes MQTT.

   3. Selecione a opção de certificado do emissor – Direct Upload.

      

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

   1. Certificado: carregue o certificado do seu servidor em formato PEM.

   2. Kid: Um identificador de chave exclusivo para o certificado.

   3. Selecione Adicionar.

      

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

Utilizar a CLI do Azure

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

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2024-12-15-preview \ 
    --set customJwtAuthenticationSettings='{ 
        "tokenIssuer": "issuer-name", 
        "encodedIssuerCertificates": [
            { 
                "kid": "key1", 
                "encodedCertificate": "-----BEGIN CERTIFICATE-----\n<certificate-in-PEM-format>\n-----END CERTIFICATE-----" 
            } 
        ] 
    } 

• Substitua <resource-group-name>, <namespace-name>, <location>, <key-vault-name>, <certificate-name>e <certificate-in-PEM-format> pelos seus valores reais.
• O valor encodedCertificate deve incluir o certificado completo e a chave pública no formato PEM, incluindo cabeçalhos ( "-----BEGIN CERTIFICATE-----", "-----END CERTIFICATE----, ``-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----).
• Verifique se o certificado de chave pública fornecido é válido e confiável pelo seu provedor de identidade.
• Atualize regularmente os certificados encodedIssuerCertificates se os certificados forem alternados ou expirados.

Formato JSON Web Token

Os Web Tokens JSON precisam ter seções de cabeçalho JWT, carga útil JWT e assinatura JWT.

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

• kid é opcional. Se estiver presente, o certificado com correspondência kid é usado para validação.
• Lista de declarações padrão que não são usadas como atributos - iss, sub, aud, exp, nbf, iatjti, .
• Todas as declarações que têm o tipo de dados correto (número que se encaixa em int32, string, matriz de strings) são usadas 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.
• No exemplo bool_attr, num_attr_to_big, num_attr_float, as obj_attr declarações têm tipos de dados incorretos e não devem ser usadas como atributos.

{ 
  "typ": "JWT", 
  "alg": "RS256", 
  "kid": "keyId1" 
}.{ 
  "iss": "some-issuer", 
  "sub": "device1", 
  "aud": "event-grid-namespace.ts.eventgrid.azure.net", 
  "exp": 1770426501, 
  "nbf": 1738886901, 
  "bool_attr": true, 
  "num_attr_pos": 1, 
  "num_attr_neg": -1, 
  "num_attr_to_big": 9223372036854775807, 
  "num_attr_float": 1.23, 
  "str_attr": "str_value", 
  "str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
  ], 
  "obj_attr": { 
      "key": "value" 
  } 
} 

Conteúdos relacionados

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