Autenticar-se com namespaces usando Tokens Web JSON

Artigo
05/21/2024

Este artigo mostra o que fazer para se autenticar com o namespace da Grade de Eventos do Azure usando Tokens Web JSON.

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

Pré-requisitos

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

Um provedor de identidade capaz de emitir Tokens Web JSON.
Um certificado de AC contendo suas chaves públicas usadas para validar os tokens de clientes.
Uma conta do Azure Key Vault para hospedar o certificado de AC contendo suas chaves públicas.

Etapas de alto nível

Para usar a autenticação JWT para namespaces personalizada, siga essas etapas:

Criar um namespace e configurar seus sub-recursos.
Habilitar a identidade gerenciada no namespace da sua Grade de Eventos.
Criar uma conta do Azure Key Vault que hospede o certificado AC contendo suas chaves públicas.
Adicionar uma atribuição de função no Azure Key Vault para a identidade gerenciada do namespace.
Definir as configurações de autenticação personalizadas no namespace da sua Grade de Eventos.
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.

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

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"

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:

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)

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)

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.

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

Nessa etapa, você vai definir as configurações de autenticação personalizadas no namespace da sua 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

Navegue até o namespace da sua Grade de Eventos no portal do Azure.
Na página Namespace da Grade de Eventos, selecione Configuração no menu do lado esquerdo.
Na seção Autenticação JWT personalizada, especifique os valores para as seguintes propriedades:
1. Selecione Habilitar autenticação JWT personalizada.
2. Emissor de Tokens: insira o valor das declarações do emissor dos tokens JWT apresentados pelos clientes MQTT.
3. Selecione Adicionar o certificado do emissor.
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.
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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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 do Token Web JSON

Os Tokens Web Json são divididos em duas seções: Cabeçalho JWT e Conteúdo 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 pode ser uma cadeia de caracteres ou 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`	Expiration. 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"
    }
}

Autenticação do cliente MQTT

Compartilhar via

Autenticar-se com namespaces usando Tokens Web JSON

Pré-requisitos

Etapas de alto nível

Criar um namespace e configurar seus sub-recursos

Habilitar a identidade gerenciada no namespace da sua Grade de Eventos

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

Adicionar uma atribuição de função no Azure Key Vault para a identidade gerenciada do namespace

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

Usar o portal do Azure

Usar a CLI do Azure

Formato do Token Web JSON

Cabeçalho JWT

Conteúdo JWT

Comentários

Recursos adicionais

Compartilhar via

Autenticar-se com namespaces usando Tokens Web JSON

Pré-requisitos

Etapas de alto nível

Criar um namespace e configurar seus sub-recursos

Habilitar a identidade gerenciada no namespace da sua Grade de Eventos

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

Adicionar uma atribuição de função no Azure Key Vault para a identidade gerenciada do namespace

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

Usar o portal do Azure

Usar a CLI do Azure

Formato do Token Web JSON

Cabeçalho JWT

Conteúdo JWT

Conteúdo relacionado

Comentários

Recursos adicionais