Configurar a autenticação do Agente MQTT

Artigo
12/09/2024

Importante

Esta página inclui instruções para gerenciar componentes do serviço Operações do Azure IoT usando manifestos de implantação do Kubernetes, que estão em versão prévia. Esse recurso é fornecido com várias limitações, e não deve ser usado para cargas de trabalho de produção.

Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

O agente MQTT dá suporte a vários métodos de autenticação para clientes e você pode definir cada porta de ouvinte para ter suas próprias configurações de autenticação com um recurso BrokerAuthentication. Para uma lista das configurações disponíveis, confira a Referência da API de Autenticação do Broker.

Vincular BrokerListener e BrokerAuthentication

As regras a seguir se aplicam à relação entre os recursos BrokerListener e BrokerAuthentication:

Cada BrokerListener pode ter várias portas. Cada porta pode ser vinculada a um recurso BrokerAuthentication.
Cada BrokerAuthentication pode dar suporte a vários métodos de autenticação ao mesmo tempo.
As portas que não vinculam um recurso BrokerAuthentication têm a autenticação desabilitada.

Para vincular uma porta BrokerListener a um recurso BrokerAuthentication, especifique o campo authenticationRef na configuração ports do recurso BrokerListener. Para saber mais, confira Recurso BrokerListener.

Recurso do BrokerAuthentication padrão

As Operações do Azure IoT implantam um recurso BrokerAuthentication padrão chamado default vinculado ao ouvinte padrão no namespace azure-iot-operations. Ele usa apenas SATs (Tokens de Conta de Serviço) do Kubernetes para autenticação.

Importante

O método de autenticação de token de conta de serviço (SAT) no recurso BrokerAuthentication padrão é obrigatório para que os componentes das Operações do Azure IoT funcionem corretamente. Evite atualizar ou excluir o recurso BrokerAuthentication padrão.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione a guia Autenticação.
Na lista de políticas de autenticação, selecione o nome da política padrão.

Para adicionar novos métodos de autenticação, selecione Adicionar método.

Para editar o ponto de extremidade padrão, crie um arquivo Bicep .bicep com o conteúdo a seguir. Atualize as configurações conforme necessário e substitua os valores de espaço reservado, como <AIO_INSTANCE_NAME> por seus próprios.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource defaultBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: 'default'
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
          ]
        }
      }
    ]
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Para inspecionar o recurso de autenticação do agente padrão, execute:

kubectl get brokerauthentication default -n azure-iot-operations -o yaml

A saída mostra o recurso BrokerAuthentication padrão, com metadados removidos para brevidade:

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata:
  name: default
  namespace: azure-iot-operations
spec:
  authenticationMethods:
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
          - aio-internal

Se precisar fazer alterações, modifique o campo authenticationMethods nesse recurso mantendo o método de autenticação SAT com o público-alvo aio-internal. Em seguida, implante-o usando kubectl apply.

Fluxo de autenticação

A ordem dos métodos de autenticação especificados determina como o agente MQTT autentica clientes. O agente MQTT tenta autenticar as credenciais do cliente usando o primeiro método especificado e itera por meio dos métodos especificados até encontrar uma correspondência ou chegar ao final.

Para cada método, o Agente MQTT verifica primeiro se as credenciais do cliente são relevantes para esse método. Por exemplo, a autenticação SAT requer um nome de usuário que comece com K8S-SAT e a autenticação X.509 requer um certificado de cliente. Se as credenciais do cliente forem relevantes, o Agente MQTT verificará se elas são válidas. Para obter mais informações, confira a seção Configurar método de autenticação.

Para autenticação personalizada, o Agente MQTT trata a falha de comunicação com o servidor de autenticação personalizada como credenciais não relevantes. Esse comportamento permite que o agente do MQTT retorne a outros métodos se o servidor de autenticação personalizado não estiver acessível.

O fluxo de autenticação termina quando:

Uma dessas condições é verdadeira:
- As credenciais do cliente são relevantes e válidas para um dos métodos.
- As credenciais do cliente não são relevantes para nenhum dos métodos.
- As credenciais do cliente são relevantes, mas inválidas para qualquer um dos métodos.
O Agente MQTT concede ou nega acesso ao cliente com base no resultado do fluxo de autenticação.

Por exemplo:

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata: 
  name: default
  namespace: azure-iot-operations
spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # ...
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        # ...

O exemplo anterior especifica autenticação personalizada e SAT. Quando um cliente se conecta, o agente MQTT tenta autenticar o cliente usando os métodos especificados na ordem personalizada e, em seguida, SAT.

O Agente MQTT verifica se as credenciais do cliente são válidas para a autenticação personalizada. Como a autenticação personalizada depende de um servidor externo para determinar a validade das credenciais, o agente considera todas as credenciais relevantes para a autenticação personalizada e as encaminha para o servidor de autenticação personalizado.
Se o servidor de autenticação personalizado responder com um resultado Pass ou Fail, o fluxo de autenticação irá terminar. No entanto, se o servidor de autenticação personalizada não estiver disponível, o Agente MQTT voltará para os métodos especificados restantes, com o SAT sendo o próximo.
O Agente MQTT tenta autenticar as credenciais como credenciais SAT.

Se o servidor de autenticação personalizado não estiver disponível e todos os métodos subsequentes determinarem que as credenciais fornecidas não são relevantes, o agente negará a conexão do cliente.

Configurar o método de autenticação

Você pode adicionar métodos de autenticação como X.509, SAT ou personalizado para políticas de autenticação.

Para adicionar um método de autenticação a uma política:

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione a guia Autenticação.
Escolha uma política de autenticação existente ou crie uma.
Adicione um novo método selecionando Adicionar método.
Escolha o tipo de método na lista suspensa e selecione Adicionar detalhes para configurar o método.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'Custom'
        customSettings: {
          endpoint: 'https://auth-server-template'
          caCertConfigMap: 'custom-auth-ca'
          auth: {
            x509: {
              secretRef: 'custom-auth-client-cert'
            }
          }
          headers: {
            header_key: 'header_value'
          }
        }
      }
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
      {
        method: 'X509'
        x509Settings: {
          trustedClientCaCert: 'client-ca'
          authorizationAttributes: {
            root: {
              attributes: {
                organization: 'contoso'
              }
              subject: 'CN = Contoso Root CA Cert, OU = Engineering, C = US'
            }
            intermediate: {
              attributes: {
                city: 'seattle'
                foo: 'bar'
              }
              subject: 'CN = Contoso Intermediate CA'
            }
            smartfan: {
              attributes: {
                building: '17'
              }
              subject: 'CN = smart-fan'
            }
          }
        }
      }
    ]
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Modifique o recurso BrokerAuthentication para uma política de autenticação adicionando novos métodos à seção authenticationMethods. O exemplo a seguir mostra vários métodos de autenticação para um recurso de BrokerAuthentication:

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthentication
metadata:
  name: my-policy
  namespace: azure-iot-operations
spec:
  authenticationMethods:
  - method: Custom
    customSettings:
      endpoint: https://auth-server-template
      caCertConfigMap: custom-auth-ca
      auth:
        x509:
          secretRef: custom-auth-client-cert
      headers:
        header_key: header_value
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
        - aio-internal
        - my-audience
    - method: X509
      x509Settings:
        trustedClientCaCert: client-ca
        authorizationAttributes:
          root:
            attributes:
              organization: contoso
            subject: CN = Contoso Root CA Cert, OU = Engineering, C = US
          intermediate:
            attributes:
              city: seattle
              foo: bar
            subject: CN = Contoso Intermediate CA
          smart-fan:
            attributes:
              building: "17"
            subject: CN = smart-fan

Para alterar a configuração, modifique a configuração de authenticationMethods neste recurso BrokerAuthentication e, em seguida, implante-a usando kubectl apply.

Para saber mais sobre cada uma das opções de autenticação, confira as próximas seções para cada método.

Para obter mais informações sobre como habilitar configurações seguras configurando um Azure Key Vault e habilitando identidades de carga de trabalho, consulte Habilitar configurações seguras na implantação de Operações do Azure IoT.

X.509

Dica

Para obter um exemplo de ponta a ponta de como configurar a autenticação X.509, consulte Tutorial: TLS, autenticação de cliente X.509 e autorização de ABAC (controle de acesso baseado em atributo).

Com a autenticação X.509, o agente MQTT usa um Certificado de Autoridade de Certificação confiável para validar certificados de cliente. Essa AC confiável pode ser uma AC raiz ou intermediária. O agente verifica a cadeia de certificados do cliente em relação ao Certificado de Autoridade de Certificação confiável. Se a cadeia for válida, o cliente será autenticado.

Para usar a autenticação X.509 com um Certificado de Autoridade de Certificação Confiável, os seguintes requisitos devem ser atendidos:

TLS: como o X.509 depende de certificados de cliente TLS, o TLS deve ser habilitado para portas usando a autenticação X.509.
Algoritmos de chave: as chaves EC e RSA têm suporte, mas todos os certificados na cadeia devem usar o mesmo algoritmo de chave.
Formato: o Certificado de Autoridade de Certificação deve estar no formato PEM.

Dica

O formato PEM é um formato comum para certificados e chaves. Os arquivos PEM são arquivos ASCII base64-encoded com cabeçalhos como -----BEGIN CERTIFICATE----- e -----BEGIN EC PRIVATE KEY-----.

Se você tiver um certificado em outro formato, poderá convertê-lo em PEM usando o OpenSSL. Para obter mais informações, consulte Como converter um certificado no formato apropriado.

Obter um Certificado de Autoridade de Certificação confiável

Em uma configuração de produção, o Certificado de Autoridade de Certificação é fornecido pela PKI (infraestrutura de chave pública) de uma organização ou por uma autoridade de certificação pública.

Para testar, crie um Certificado de Autoridade de Certificação autoassinado com o OpenSSL. Por exemplo, execute o seguinte comando para gerar um Certificado de Autoridade de Certificação autoassinado com uma chave RSA, um nome diferenciado CN=Contoso Root CA Cert e uma validade de 365 dias:

openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca.pem -days 365 -nodes -subj "/CN=Contoso Root CA Cert"

O mesmo comando com o CLI da Etapa, que é uma ferramenta conveniente para gerenciar certificados, é:

step certificate create "Contoso Root CA Cert" ca.pem ca-key.pem --profile root-ca --kty RSA --size 4096 --no-password --insecure
 --not-after 8760h

Esses comandos criam um Certificado de Autoridade de Certificação ca.pem e uma chave privada ca-key.pem no formato PEM. O Certificado de Autoridade de Certificação ca.pem pode ser importado para o agente MQTT para autenticação X.509.

Importar um certificado de autoridade de certificação confiável

Para começar a usar a autenticação X.509, importe o Certificado de Autoridade de Certificação confiável para um ConfigMap no namespace azure-iot-operations. Para importar um Certificado de Autoridade de Certificação confiável ca.pem para um ConfigMap chamado client-ca, execute:

kubectl create configmap client-ca --from-file=ca.pem -n azure-iot-operations

Neste exemplo, o certificado de autoridade de certificação é importado sob a chave ca.pem. O agente MQTT confia em todos os certificados de AC no ConfigMap, portanto, o nome da chave pode ser qualquer coisa.

Para verificar se o certificado de AC raiz foi importado corretamente, execute kubectl describe configmap. O resultado mostra a mesma codificação base64 do arquivo do certificado PEM.

kubectl describe configmap client-ca -n azure-iot-operations

Name:         client-ca
Namespace:    azure-iot-operations

Data
====
ca.pem:
----
-----BEGIN CERTIFICATE-----
MIIFDjCCAvagAwIBAgIRAKQWo1+S13GTwqZSUYLPemswDQYJKoZIhvcNAQELBQAw
...
-----END CERTIFICATE-----


BinaryData
====

Configurar o método de autenticação X.509

Depois que o Certificado de Autoridade de Certificação confiável for importado, habilite a autenticação de cliente X.509 adicionando-o como um método de autenticação em um recurso BrokerAuthentication. Verifique se esse recurso está vinculado a uma porta de ouvinte habilitada para TLS.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione a guia Autenticação.
Escolha uma política de autenticação existente ou crie uma.
Adicione um novo método selecionando Adicionar método.
Escolha o tipo de método X.509 na lista suspensa e selecione Adicionar detalhes para configurar o método.
No painel detalhes da autenticação X.509 painel, especifique o nome ConfigMap do Certificado de Autoridade de Certificação confiável usando o formato JSON.
```
{
    "trustedClientCaCert": "<TRUSTED_CA_CONFIGMAP>"
}
```
Substitua <TRUSTED_CA_CONFIGMAP> pelo nome do ConfigMap que contém o Certificado de Autoridade de Certificação confiável. Por exemplo, "trustedClientCaCert": "client-ca".
Opcionalmente, adicione atributos de autorização para clientes usando certificados X.509. Para saber mais, confira Atributos de certificado para autorização.
Escolha Aplicar para salvar as alterações.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'
param trustedCaConfigMap string = '<TRUSTED_CA_CONFIGMAP>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'X509'
        x509Settings: {
          trustedClientCaCert: trustedCaConfigMap
          // authorizationAttributes: {
            //// Optional authorization attributes
            //// See the next section for more information
          // }
        }
      }
    ]
  }
}

Substitua <TRUSTED_CA_CONFIGMAP> pelo nome do ConfigMap que contém o Certificado de Autoridade de Certificação confiável. Por exemplo, client-ca.

Implante o arquivo Bicep usando o CLI do Azure.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

spec:
  authenticationMethods:
    - method: X509
      x509Settings:
        trustedClientCaCert: <TRUSTED_CA_CONFIGMAP>
        # authorizationAttributes:
          ## Optional authorization attributes
          ## See the next section for more information

Substitua <TRUSTED_CA_CONFIGMAP> pelo nome do ConfigMap que contém o Certificado de Autoridade de Certificação confiável. Por exemplo, client-ca.

Opcional: atributos de certificado para autorização

Os atributos X.509 podem ser especificados no recurso BrokerAuthentication para autorizar clientes com base em suas propriedades de certificado. Os atributos são definidos no campo authorizationAttributes.

Por exemplo:

No portal do Azure, ao configurar o método de autenticação X.509, adicione os atributos de autorização no painel de detalhes da autenticação X.509 no formato JSON.

{
  "trustedClientCaCert": "<TRUSTED_CA_CONFIGMAP>",
  "authorizationAttributes": {
    "root": {
      "subject": "CN = Contoso Root CA Cert, OU = Engineering, C = US",
      "attributes": {
        "organization": "contoso"
      }
    },
    "intermediate": {
      "subject": "CN = Contoso Intermediate CA",
      "attributes": {
        "city": "seattle",
        "foo": "bar"
      }
    },
    "smartfan": {
      "subject": "CN = smart-fan",
      "attributes": {
        "building": "17"
      }
    }
  }
}

x509Settings: {
  trustedClientCaCert: '<TRUSTED_CA_CONFIGMAP>'
  authorizationAttributes: {
    root: {
      subject: 'CN = Contoso Root CA Cert, OU = Engineering, C = US'
      attributes: {
        organization: 'contoso'
      }
    }
    intermediate: {
      subject: 'CN = Contoso Intermediate CA'
      attributes: {
        city: 'seattle'
        foo: 'bar'
      }
    }
    smartfan: {
      subject: 'CN = smart-fan'
      attributes: {
        building: '17'
      }
    }
  }
}

x509Settings:
  trustedClientCaCert: <TRUSTED_CA_CONFIGMAP>
  authorizationAttributes:
    root:
      subject = "CN = Contoso Root CA Cert, OU = Engineering, C = US"
      attributes:
        organization = contoso
    intermediate:
      subject = "CN = Contoso Intermediate CA"
      attributes:
        city = seattle
        foo = bar
    smart-fan:
      subject = "CN = smart-fan"
      attributes:
        building = 17

Neste exemplo, cada cliente que tem um certificado emitido pela AC raiz com nome diferenciado CN = Contoso Root CA Cert, OU = Engineering, C = US ou a AC intermediária com nome diferenciado CN = Contoso Intermediate CA recebe os atributos listados. Além disso, o certificado do cliente de ventilador inteligente recebe atributos específicos a ele.

A correspondência de atributos sempre começa no certificado do cliente folha e, em seguida, vai ao longo da cadeia. A atribuição de atributo é interrompida após a primeira correspondência. No exemplo anterior, mesmo que smart-fan tenha o certificado intermediário CN = Contoso Intermediate CA, ele não obtém os atributos associados.

As regras de autorização podem ser aplicadas a clientes que usam certificados X.509 com esses atributos. Para saber mais, confira Autorizar clientes que usam a autenticação X.509.

Habilitar a autenticação X.509 para uma porta de ouvinte

Depois de importar o Certificado de Autoridade de Certificação confiável e configurar o recurso BrokerAuthentication, vincule-o a uma porta de ouvinte habilitada para TLS. Essa etapa é importante porque a autenticação X.509 depende do TLS para validação de certificado do cliente.

Para obter uma porta de ouvinte habilitada para TLS, consulte Habilitar o gerenciamento manual de certificados TLS para uma porta e habilitar o gerenciamento automático de certificados TLS para uma porta.

Observação

Habilitar o TLS em uma porta de ouvinte de agente significa que o agente usa um certificado de servidor para criptografia TLS. Quando os clientes se conectam a essa porta, eles devem confiar no certificado do servidor tendo o Certificado de Autoridade de Certificação que o assinou em seu repositório de confiança. Esse processo é conhecido como distribuição de confiança ou agrupamento de confiança. É importante entender a diferença entre a validação do servidor e a validação do cliente:

Validação do cliente: o agente MQTT (servidor) verifica o certificado do cliente em relação ao Certificado de Autoridade de Certificação confiável especificado no campo trustedClientCaCert para autenticação de cliente X.509.
Validação do servidor: os clientes (como mosquitto ou MQTTX) verificam o certificado de servidor do agente MQTT em relação ao Certificado de Autoridade de Certificação confiável em seu repositório de confiança. Para clientes mosquitto, use o parâmetro --cafile para especificar o arquivo de Certificado de Autoridade de Certificação. Para MQTTX, adicione o Certificado de Autoridade de Certificação ao repositório de confiança nas configurações.

Depois de habilitar a autenticação X.509, verifique se os clientes confiam no certificado do servidor do agente tendo o Certificado de Autoridade de Certificação do lado do servidor em seu repositório de confiança. Não confunda a confiança no Certificado de Autoridade de Certificação do lado do servidor com o Certificado de Autoridade de Certificação do lado do cliente usado para autenticação de cliente especificado no campo trustedClientCaCert.

Para obter um exemplo completo, consulte Tutorial: autenticação de cliente TLS, X.509 e ABAC (controle de acesso baseado em atributo).

Conectar o cliente mosquitto ao Agente MQTT com certificado de cliente X.509

Um cliente como o mosquitto precisa de dois arquivos para poder se conectar ao agente MQTT com autenticação de cliente TLS e X.509.

O parâmetro --cert especifica o arquivo PEM do certificado do cliente. Esse arquivo também deve incluir quaisquer certificados intermediários para ajudar o agente MQTT a criar a cadeia de certificados completa.
O parâmetro --key especifica o arquivo PEM da chave privada do cliente.

Nos casos em que o agente MQTT está usando um certificado de AC autoassinado para emitir seu certificado de servidor TLS, o parâmetro --cafile é necessário. Esse arquivo contém o Certificado de Autoridade de Certificação (também conhecido como pacote de confiança) que o cliente mosquitto usa para validar o certificado de servidor do agente ao se conectar via TLS. Se o emissor do certificado de servidor do agente MQTT fizer parte do repositório raiz do sistema (como CAs públicas conhecidas), o parâmetro --cafile poderá ser omitido.

Por exemplo:

mosquitto_pub -q 1 -t hello -d -V mqttv5 -m world -i thermostat \
-h "<BROKER_HOST>" \
--cert thermostat_cert.pem \
--key thermostat_key.pem \
--cafile ca.pem

Entenda o fluxo de autenticação de cliente X.509 do Agente MQTT

Diagrama do fluxo de autenticação do cliente X.509.

Estas são as etapas para autenticação do cliente:

Quando a autenticação de cliente X.509 é ativada, a conexão de clientes deve apresentar um certificado de cliente e quaisquer certificados intermediários para permitir que o agente do MQTT crie uma cadeia de certificados com raiz em um de seus certificados confiáveis configurados.
O balanceador de carga direciona a comunicação para um dos agentes de front-end.
Após ter recebido o certificado do cliente, o agente de front-end tenta criar uma cadeia de certificado com raiz em um dos certificados configurados. Se tiver criado uma cadeia com sucesso e a cadeia apresentada for verificada, o agente de front-end irá concluir o handshake TLS. O cliente de conexão é capaz de enviar pacotes MQTT para o front-end por meio do canal TLS.
O canal TLS está aberto, mas a autenticação ou autorização do cliente ainda não foi concluída.
Em seguida, o cliente envia um pacote CONNECT para o Agente MQTT.
O pacote CONNECT é roteado novamente para um front-end.
O front-end coleta todas as credenciais apresentadas pelo cliente até agora, como dados de autenticação do pacote CONNECT e a cadeia de certificados do cliente apresentada durante o handshake do TLS.
O front-end envia essas credenciais para o serviço de autenticação. O serviço de autenticação verifica mais uma vez a cadeia de certificados e coleta os nomes de entidade de todos os certificados na cadeia.
O serviço de autenticação usa suas regras de autorização configuradas para determinar os atributos que os clientes de conexão têm. Esses atributos determinam quais operações o cliente pode executar, incluindo o próprio pacote CONNECT.
O serviço de autenticação retorna a decisão para o agente de front-end.
O agente de front-end sabe quais são os atributos do cliente e se ele tem permissão para se conectar. Em caso afirmativo, a conexão MQTT será concluída e o cliente poderá continuar a enviar e receber pacotes MQTT conforme determinado por suas regras de autorização.

Tokens da Conta de Serviço do Kubernetes

Os Tokens da Conta de Serviço do Kubernetes (SATs) são Tokens Web JSON associados a Contas de Serviço do Kubernetes. Os clientes apresentam SATs ao Agente MQTT para se autenticarem.

O Agente MQTT usa tokens de conta de serviço associados que são detalhados na postagem O que os usuários do GKE precisam saber sobre os novos tokens de conta de serviço do Kubernetes. Aqui estão os recursos que mais se destacam na postagem:

Lançados no Kubernetes 1.13 e tendo se tornado o formato padrão no 1.21, os tokens vinculados abordam toda a funcionalidade limitada de tokens herdados e muito mais:

Os tokens em si são mais difíceis de roubar e usar indevidamente; são limitados por tempo, limitados por público e limitados por objeto.
Além disso, adotam um formato padronizado: OpenID Connect (OIDC), com Descoberta de OIDC completa, facilitando a aceitação dos provedores de serviços.
São distribuídos para os pods com mais segurança, usando um novo tipo de volume projetado do Kubelet.

O agente verifica os tokens usando a API de Revisão de Tokens do Kubernetes. Habilite o recurso Kubernetes TokenRequestProjection para especificar audiences (padrão desde 1.21). Se esse recurso não estiver habilitado, os SATs não poderão ser usados.

Criar uma conta de serviço

Para criar SATs, primeiro crie uma conta de serviço. O comando a seguir cria uma conta de serviço chamada mqtt-client.

kubectl create serviceaccount mqtt-client -n azure-iot-operations

Opcional: adicionar atributos para autorização

Os clientes que se autenticam via SAT podem, opcionalmente, ter suas contas de serviço anotadas com atributos a serem usados com políticas de autorização. Para distinguir essas anotações de outras pessoas, elas começam com o prefixo aio-broker-auth/.

Você pode anotar uma conta de serviço usando kubectl annotate:

kubectl annotate serviceaccount <SERVICE_ACCOUNT_NAME> aio-broker-auth/<ATTRIBUTE>=<VALUE> -n azure-iot-operations

Ou você pode adicionar as anotações ao arquivo de manifesto da conta de serviço:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: <SERVICE_ACCOUNT_NAME>
  namespace: azure-iot-operations
  annotations:
    aio-broker-auth/<ATTRIBUTE_1>: <VALUE_1>
    aio-broker-auth/<ATTRIBUTE_2>: <VALUE_2>

Para saber mais, confira Autorizar clientes que usam Tokens da Conta de Serviço do Kubernetes.

Habilitar a autenticação do Token da Conta de Serviço (SAT)

Modifique a configuração authenticationMethods em um recurso BrokerAuthentication para especificar ServiceAccountToken como um método de autenticação válido. O audiences especifica a lista de públicos válidos para os tokens. Escolha valores exclusivos que identifiquem o serviço do Agente MQTT. Você precisa especificar pelo menos um público e todos os SATs precisam corresponder a um dos públicos especificados.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione a guia Autenticação.
Escolha uma política de autenticação existente ou crie uma.
Adicione um novo método selecionando Adicionar método.
Escolha o tipo de método SAT do Kubernetes na lista suspensa e selecione Adicionar detalhes para configurar o método.

Captura de tela usando o portal do Azure para definir o método de autenticação do SAT do agente MQTT.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'ServiceAccountToken'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
    ]
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

spec:
  authenticationMethods:
    - method: ServiceAccountToken
      serviceAccountTokenSettings:
        audiences:
        - aio-internal
        - my-audience

Aplique suas alterações com o kubectl apply. Pode levar alguns minutos para que as alterações entrem em vigor.

Testar a autenticação do SAT

A autenticação SAT usa os campos de autenticação aprimorados do MQTT v5. Um cliente deve definir o método K8S-SAT de autenticação aprimorado e os dados de autenticação aprimorados para o token.

Por exemplo, usando mosquitto (alguns campos omitidos para brevidade):

mosquitto_pub ... -D CONNECT authentication-method 'K8S-SAT' -D CONNECT authentication-data <TOKEN>

Aqui, <TOKEN> está o token da conta de serviço. Para obter um token de teste, execute:

kubectl create token <SERVICE_ACCOUNT> -n azure-iot-operations --audience <AUDIENCE>

Aqui, <SERVICE_ACCOUNT> está o nome da conta de serviço que você criou e <AUDIENCE> é um dos públicos configurados no recurso BrokerAuthentication.

Para obter um exemplo sobre como configurar um pod Kubernetes para usar a autenticação SAT, consulte Conectar-se ao ouvinte padrão dentro do cluster.

Na configuração do pod, o campo serviceAccountName deve corresponder à conta de serviço associada ao token que está sendo usado e o campo serviceAccountToken.audience deve ser um dos audiences configurados no recurso BrokerAuthentication.

Atualizar tokens de conta de serviço

Os tokens da conta de serviço são válidos por tempo limitado e configurados com expirationSeconds. No entanto, o Kubernetes atualiza automaticamente o token antes que ele expire. O token é atualizado em segundo plano e o cliente não precisa fazer nada além de buscá-lo novamente.

Por exemplo, se o cliente for um pod que usa o token montado como um volume, como no exemplo teste de autenticação SAT, então o token mais recente estará disponível no mesmo caminho /var/run/secrets/tokens/broker-sat. Ao fazer uma nova conexão, o cliente pode buscar o token mais recente e usá-lo para autenticação. O cliente também deve ter um mecanismo para lidar com erros não autorizados do MQTT, buscando o token mais recente e tentando novamente a conexão.

Autenticação personalizada

Estenda a autenticação do cliente para além dos métodos de autenticação fornecidos com a autenticação personalizada. É plugável, já que o serviço pode ser qualquer coisa que possa aderir à API.

Quando um cliente se conecta ao agente MQTT com a autenticação personalizada habilitada, o agente envia uma solicitação HTTPS para um servidor de autenticação personalizado com as credenciais do cliente. Em seguida, o servidor responde com aprovação ou negação, incluindo os atributos de autorização do cliente.

Criar um serviço de autenticação personalizado

O servidor de autenticação personalizada é implementado e implantado separadamente do Agente MQTT.

Uma amostra de servidor de autenticação personalizado e instruções estão disponíveis no GitHub. Use essa amostra como um modelo a usaria e como ponto de partida para implementar sua própria lógica de autenticação personalizada.

API

A API entre o Agente MQTT e o servidor de autenticação personalizada segue a especificação de API para autenticação personalizada. A especificação OpenAPI está disponível em GitHub.

O HTTPS com criptografia TLS é obrigatório

O Agente MQTT envia solicitações contendo credenciais confidenciais do cliente para o servidor de autenticação personalizada. Para proteger essas credenciais, a comunicação entre o Agente MQTT e o servidor de autenticação personalizada deve ser criptografada com TLS.

O servidor de autenticação personalizada deve apresentar um certificado de servidor, e o Agente MQTT deve ter um certificado AC raiz confiável para validar o certificado do servidor. Opcionalmente, o servidor de autenticação personalizada pode exigir que o Agente MQTT apresente um certificado de cliente para se autenticar.

Habilitar a autenticação personalizada para um ouvinte

Modifique a configuração authenticationMethods em um recurso BrokerAuthentication para especificar Custom como um método de autenticação válido. Em seguida, especifique os parâmetros necessários para se comunicar com um servidor de autenticação personalizado.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione a guia Autenticação.
Escolha uma política de autenticação existente ou crie uma.
Adicione um novo método selecionando Adicionar método.
Escolha o tipo de método Personalizado na lista suspensa e selecione Adicionar detalhes para configurar o método.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-11-01' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-11-01' existing = {
  parent: aioInstance
  name: 'default'
}

resource myBrokerAuthentication 'Microsoft.IoTOperations/instances/brokers/authentications@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authenticationMethods: [
      {
        method: 'Custom'
        serviceAccountTokenSettings: {
          audiences: [
            'aio-internal'
            'my-audience'
          ]
        }
      }
    ]
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

az deployment group create --resource-group <RESOURCE_GROUP> --template-file <FILE>.bicep

Esse exemplo mostra todos os parâmetros possíveis. Os parâmetros exatos necessários dependem dos requisitos de cada servidor personalizado.

spec:
  authenticationMethods:
    - method: Custom
      customSettings:
        # Endpoint for custom authentication requests. Required.
        endpoint: https://auth-server-template
        # Optional CA certificate for validating the custom authentication server's certificate.
        caCertConfigMap: custom-auth-ca
        # Authentication between MQTT broker with the custom authentication server.
        # The broker may present X.509 credentials or no credentials to the server.
        auth:
          x509:
            secretRef: custom-auth-client-cert
            namespace: azure-iot-operations
        # Optional additional HTTP headers that the broker will send to the
        # custom authentication server.
        headers:
          header_key: header_value

Desabilitar a autenticação

Para teste, você pode desabilitar a autenticação para uma porta de ouvinte do agente. Não é recomendável desabilitar a autenticação para ambientes de produção.

No portal do Azure, navegue até a instância de Operações de IoT.
Em Componentes, selecione Agente MQTT.
Selecione o ouvinte do corretor que você deseja editar na lista.
Na porta em que você deseja desabilitar a autenticação, selecione Nenhum no menu suspenso de autenticação.

Os clientes se desconectam após a expiração das credenciais

O Agente MQTT desconecta os clientes quando suas credenciais expiram. A desconexão após a expiração da credencial se aplica a todos os clientes que se conectam aos front-ends do Agente MQTT, inclusive:

Os clientes autenticados com SATs se desconectam quando o SAT expira
Clientes autenticados com X.509 se desconectam quando o certificado do cliente expira
Os clientes autenticados com autenticação personalizada se desconectam com base no tempo de expiração retornado pelo servidor de autenticação personalizada.

Na desconexão, a conexão de rede do cliente é fechada. O cliente não recebe um pacote MQTT DISCONNECT, mas o agente registra uma mensagem informando que desconectou o cliente.

Os clientes MQTT v5 autenticados com SATs e autenticação personalizada podem se autenticar novamente com uma nova credencial antes que a credencial inicial expire. Os clientes X.509 não podem se autenticar novamente e devem restabelecer a conexão, pois a autenticação é feita na camada TLS.

Os clientes podem reautenticar enviando um pacote AUTH MQTT v5 com o motivo ReAuth.

Os clientes SAT enviam um cliente AUTH com os campos method: K8S-SAT, data: <token>. Os clientes de autenticação personalizada definem o método e o campo de dados conforme exigido pelo servidor de autenticação personalizada.

A reautenticação bem-sucedida atualiza a expiração da credencial do cliente com o tempo de expiração da sua nova credencial, e o agente responde com um pacote de AUTH de sucesso. A autenticação com falha devido a problemas transitórios, como o servidor de autenticação personalizado não disponível, faz com que o agente responda com um pacote AUTH de ContinueAuthentication. O cliente pode tentar novamente mais tarde. Outras falhas de autenticação fazem com que o agente envie um pacote DISCONNECT e feche a conexão de rede do cliente.

Compartilhar via

Configurar a autenticação do Agente MQTT

Vincular BrokerListener e BrokerAuthentication

Recurso do BrokerAuthentication padrão

Fluxo de autenticação

Configurar o método de autenticação

X.509

Obter um Certificado de Autoridade de Certificação confiável

Importar um certificado de autoridade de certificação confiável

Configurar o método de autenticação X.509

Opcional: atributos de certificado para autorização

Habilitar a autenticação X.509 para uma porta de ouvinte

Conectar o cliente mosquitto ao Agente MQTT com certificado de cliente X.509

Entenda o fluxo de autenticação de cliente X.509 do Agente MQTT

Tokens da Conta de Serviço do Kubernetes

Criar uma conta de serviço

Opcional: adicionar atributos para autorização

Habilitar a autenticação do Token da Conta de Serviço (SAT)

Testar a autenticação do SAT

Atualizar tokens de conta de serviço

Autenticação personalizada

Criar um serviço de autenticação personalizado

API

O HTTPS com criptografia TLS é obrigatório

Habilitar a autenticação personalizada para um ouvinte

Desabilitar a autenticação

Os clientes se desconectam após a expiração das credenciais

Comentários

Recursos adicionais

Compartilhar via

Configurar a autenticação do Agente MQTT

Vincular BrokerListener e BrokerAuthentication

Recurso do BrokerAuthentication padrão

Fluxo de autenticação

Configurar o método de autenticação

X.509

Obter um Certificado de Autoridade de Certificação confiável

Importar um certificado de autoridade de certificação confiável

Configurar o método de autenticação X.509

Opcional: atributos de certificado para autorização

Habilitar a autenticação X.509 para uma porta de ouvinte

Conectar o cliente mosquitto ao Agente MQTT com certificado de cliente X.509

Entenda o fluxo de autenticação de cliente X.509 do Agente MQTT

Tokens da Conta de Serviço do Kubernetes

Criar uma conta de serviço

Opcional: adicionar atributos para autorização

Habilitar a autenticação do Token da Conta de Serviço (SAT)

Testar a autenticação do SAT

Atualizar tokens de conta de serviço

Autenticação personalizada

Criar um serviço de autenticação personalizado

API

O HTTPS com criptografia TLS é obrigatório

Habilitar a autenticação personalizada para um ouvinte

Desabilitar a autenticação

Os clientes se desconectam após a expiração das credenciais

Conteúdo relacionado

Comentários

Recursos adicionais