Use Tokens Web JSON (JWT) OAuth 2.0 para autenticar com 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 do OAuth 2.0, que permite que os clientes se conectem e autentiquem com um namespace da 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 do OAuth 2.0 para namespaces, você precisa ter os seguintes pré-requisitos:

• Provedor de identidade que pode emitir Tokens Web JSON.
• Certificado de autoridade de certificação que inclui suas chaves públicas usadas para validar os tokens de cliente (Key Vault) ou o arquivo PEM de 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, siga estas etapas:

1. Criar um namespace e configurar seus sub-recursos.

2. Habilitar a identidade gerenciada no namespace da sua Grade de Eventos.

3. Defina as configurações de autenticação do OAuth 2.0 no namespace da Grade de Eventos seguindo estas etapas:

   1. Crie uma conta do Azure Key Vault que hospeda o certificado de AC que inclui suas chaves públicas e adicione uma atribuição de função no Key Vault para a identidade gerenciada do namespace.
   2. Ou carregue o arquivo PEM de seus certificados de chave pública no namespace.

4. Seus clientes podem se conectar ao namespace da Grade de Eventos usando os tokens fornecidos por seu provedor de identidade.

Criar um namespace e configurar seus sub-recursos

Siga as instruções do Início Rápido: publicar e assinar mensagens MQTT no Namespace da Grade de Eventos com o portal do Azure para criar um namespace e configurar seus sub-recursos. Ignore as etapas de criação do certificado e do cliente, já que 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 a identidade gerenciada no namespace da sua Grade de Eventos

O namespace usa a identidade gerenciada para acessar sua instância do Azure Key Vault e obter o certificado do servidor para seu domínio personalizado. Use o seguinte comando para habilitar a identidade gerenciada atribuída pelo sistema no namespace da sua 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, confira Habilitar uma identidade gerenciada para um namespace da Grade de Eventos.

Configurar as configurações de autenticação JWT do OAuth 2.0 no namespace do Event Grid -Key Vault

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

Criar uma conta do Azure Key Vault e carregar seu 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 comando a seguir para importar um certificado para o Azure Key Vault

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

   Observação

   Seu certificado precisa incluir o nome de domínio no Nome Alternativo do Titular do DNS. Para obter mais informações, consulte Tutorial: Importar um certificado no Azure Key Vault.

Adicionar uma atribuição de função no Azure Key Vault 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 a ID da entidade de segurança da identidade gerenciada pelo sistema do namespace da Grade de Eventos usando o comando a seguir

   $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 Azure Key Vault.

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

3. Adicione a atribuição de função no Key Vault 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 Key Vault e a experiência do portal, confira Fornecer acesso a chaves, certificados e segredos do Key Vault 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 namespace da sua 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 JWT personalizada, especifique os valores para as seguintes propriedades:

   1. Selecione Habilitar autenticação JWT personalizada.

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

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

      

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

      1. URL do certificado: o Identificador de Certificado do certificado do emissor no Azure Key Vault que você criou. Alternativamente, você pode escolher Selecionar um certificado usando um cofre de chaves para selecionar o certificado e o cofre de chaves a partir das suas assinaturas.

      2. Identidade: a identidade usada para se autenticar no Key Vault para acessar o certificado do emissor que foi criado.

      3. Selecione Adicionar.

         

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

   Observação

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

Usar a CLI do Azure

Use o comando a seguir para atualizar seu namespace com a configuração da 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 do Token Web JSON

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

Cabeçalho JWT

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

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

Conteúdo JWT

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

Nome	Descrição
iss	Emissor. O valor no JWT precisa corresponder ao emissor na configuração do namespace da Grade de Eventos para a autenticação JWT personalizada.
sub	Assunto. O valor é usado como o nome da identidade de autenticação.
aud	Público-alvo. O valor é uma matriz de cadeias de caracteres. O valor precisa conter o nome do 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 destinatário pode conter outras cadeias de caracteres, mas exigimos que pelo menos uma dessas cadeias de caracteres seja um nome do host do namespace da Grade de Eventos padrão ou um domínio personalizado para esse namespace.
exp	Expiração. Hora Unix em que o JWT irá expirar.
nbf	Não antes de. Hora da Unidade em que o JWT se tornou válido.

A Grade de Eventos mapeia todas as declarações para os atributos do cliente se tiverem um dos seguintes tipos: int32, string, array of strings. As declarações padrão iss, sub, aud, exp, nbf são excluídas dos atributos do cliente. No exemplo de JWT a seguir, apenas três declarações são convertidas em atributos de cliente — num_attr, str_attr, str_list_attr — porque têm os tipos corretos int32, string, array of strings.  incorrect_attr_1, incorrect_attr_2, incorrect_attr_3 não são convertidas em atributos de cliente porque têm os 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"
    }
}

Definir as configurações de autenticação JWT do OAuth 2.0 no namespace da Grade de Eventos – Upload direto

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

Usar 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 de autenticação JWT personalizada, especifique valores para as seguintes propriedades:

   1. Selecione Habilitar autenticação JWT personalizada.

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

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

      

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

   1. Certificado: carregue o certificado do servidor no formato PEM.

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

   3. Selecione Adicionar.

      

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

Usar a CLI do Azure

Use o comando a seguir para atualizar o namespace com a configuração de autenticação JWT do 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> com seus valores reais.
• O valor de certificado codificado 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 encodedIssuerCertificates se os certificados forem rotacionados ou expirados.

Formato do Token Web JSON

Os Tokens Web JSON precisam ter seções de cabeçalho JWT, conteúdo 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 será usado para validação.
• Lista de declarações padrão que não são usadas como atributos - iss, sub, aud, exp, nbf, iat, jti.
• Todas as declarações que têm o tipo de dados correto (número que se ajusta a int32, cadeia de caracteres, matriz de cadeias de caracteres) são usadas como atributos. No exemplonum_attr_pos, as num_attr_negstr_attrstr_list_attr declarações têm tipos de dados corretos e são usadas como atributos.
• No exemplobool_attr, num_attr_to_bigas num_attr_floatobj_attr declarações têm tipos de dados incorretos e não são 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údo relacionado

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