Configurar a autenticação do agente MQTT

Importante

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

Veja Termos de Utilização Complementares da Pré-visualizações do Microsoft Azure para obter os termos legais que se aplicam às funcionalidades do Azure que estão na versão beta, na pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

O broker MQTT suporta vários métodos de autenticação para clientes, e você pode configurar cada porta de ouvinte para ter suas próprias configurações de autenticação com um recurso BrokerAuthentication . Para obter uma lista das configurações disponíveis, consulte a referência da API de autenticação do broker.

Link 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 suportar 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 authenticationRef campo na ports configuração do recurso BrokerListener. Para saber mais, consulte Recurso BrokerListener.

Recurso BrokerAuthentication padrão

O Azure IoT Operations implanta um recurso BrokerAuthentication padrão chamado default vinculado ao ouvinte padrão no azure-iot-operations namespace. Ele usa apenas tokens de conta de serviço (SATs) 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 é necessário para que os componentes nas Operações IoT do Azure funcionem corretamente. Evite atualizar ou excluir o recurso BrokerAuthentication padrão.

Portal

1. No portal do Azure, navegue até sua instância de Operações IoT.

2. Em Componentes, selecione MQTT Broker.

3. Selecione a guia Autenticação .

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

Bicep

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

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 a CLI do Azure.

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

Kubernetes (visualização)

Para inspecionar o recurso de autenticação do broker 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 você precisar fazer alterações, modifique o authenticationMethods campo neste recurso, mantendo o método de autenticação SAT com a aio-internal audiência. Em seguida, implante-o usando kubectl applyo .

Fluxo de autenticação

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

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

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

O fluxo de autenticação termina quando:

• Uma destas 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 broker 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 custom e SAT. Quando um cliente se conecta, o broker MQTT tenta autenticar o cliente usando os métodos especificados na ordem personalizada e, em seguida , SAT.

1. O broker MQTT verifica se as credenciais do cliente são válidas para 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 personalizada.
2. Se o servidor de autenticação personalizado responder com Pass ou Fail resultar, o fluxo de autenticação será encerrado. No entanto, se o servidor de autenticação personalizado não estiver disponível, o broker MQTT retornará aos métodos especificados restantes, com o SAT sendo o próximo.
3. O broker 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 broker negará a conexão do cliente.

Configurar método de autenticação

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

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

Portal

1. No portal do Azure, navegue até sua instância de Operações IoT.

2. Em Componentes, selecione MQTT Broker.

3. Selecione a guia Autenticação .

4. Escolha uma política de autenticação existente ou crie uma nova.

5. Adicione um novo método selecionando Adicionar método.

6. Escolha o tipo de método na lista suspensa e selecione Adicionar detalhes para configurar o método.

   

Bicep

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 a CLI do Azure.

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

Kubernetes (visualização)

Modifique o recurso BrokerAuthentication para uma política de autenticação adicionando novos métodos à authenticationMethods seção. O exemplo a seguir mostra vários métodos de autenticação para um recurso 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 authenticationMethods configuração neste recurso BrokerAuthentication e implante-a usando kubectl apply.

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

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

X.509

Gorjeta

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

Com a autenticação X.509, o broker MQTT usa um certificado de CA confiável para validar certificados de cliente. Essa autoridade de certificação confiável pode ser uma autoridade de certificação raiz ou intermediária. O broker verifica a cadeia de certificados do cliente em relação ao certificado de CA 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 que usam a autenticação X.509.
• Algoritmos de chave: As chaves EC e RSA são suportadas, mas todos os certificados na cadeia devem usar o mesmo algoritmo de chave.
• Formato: O certificado da autoridade de certificação deve estar no formato PEM.

Gorjeta

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

Se você tiver um certificado em outro formato, você pode convertê-lo para PEM usando 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 da 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 testes, crie um certificado de CA autoassinado com OpenSSL. Por exemplo, execute o seguinte comando para gerar um certificado de autoridade de certificação autoassinado com uma chave RSA, um nome CN=Contoso Root CA Certdistinto 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 Step CLI, 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 ca.pem de autoridade de certificação e uma chave ca-key.pem privada no formato PEM. O certificado da autoridade de ca.pem certificação pode ser importado para o broker 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 CA confiável para um ConfigMap no azure-iot-operations namespace. Para importar um certificado ca.pem de autoridade de certificação confiável para um ConfigMap chamado client-ca, execute:

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

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

Para verificar se o certificado da autoridade de certificação raiz foi importado corretamente, execute kubectl describe configmap. O resultado mostra a mesma codificação base64 do arquivo de 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 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-a 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.

Portal

1. No portal do Azure, navegue até sua instância de Operações IoT.

2. Em Componentes, selecione MQTT Broker.

3. Selecione a guia Autenticação .

4. Escolha uma política de autenticação existente ou crie uma nova.

5. Adicione um novo método selecionando Adicionar método.

6. Escolha o tipo de método X.509 na lista suspensa e selecione Adicionar detalhes para configurar o método.

7. No painel de detalhes de autenticação X.509, especifique o nome ConfigMap do certificado de CA 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".

   

8. Opcionalmente, adicione atributos de autorização para clientes que usam certificados X.509. Para saber mais, consulte Atributos de certificado para autorização.

9. Selecione Aplicar para salvar as alterações.

Bicep

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 a CLI do Azure.

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

Kubernetes (visualização)

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 authorizationAttributes campo.

Por exemplo:

Portal

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

Bicep

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'
      }
    }
  }
}

Kubernetes (visualização)

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 autoridade de certificação raiz com nome CN = Contoso Root CA Cert, OU = Engineering, C = US distinto ou pela autoridade de certificação intermediária com nome CN = Contoso Intermediate CA distinto recebe os atributos listados. Além disso, o certificado de cliente de ventilador inteligente recebe atributos específicos para ele.

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

As regras de autorização podem ser aplicadas a clientes usando certificados X.509 com esses atributos. Para saber mais, consulte 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 CA confiável e configurar o recurso BrokerAuthentication , vincule-o a uma porta de ouvinte habilitada para TLS. Esta etapa é importante porque a autenticação X.509 depende do TLS para validação de certificado de 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.

Nota

Habilitar o TLS em uma porta de ouvinte do broker significa que o broker 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 da autoridade de certificação que o assinou em seu armazenamento confiável. Esse processo é conhecido como distribuição de confiança ou agregação de confiança. É importante entender a diferença entre validação de servidor e validação de cliente:

• Validação do cliente: O broker MQTT (servidor) verifica o certificado do cliente em relação ao trustedClientCaCert certificado de CA confiável especificado no campo para autenticação de cliente X.509.
• Validação do servidor: Os clientes (como mosquitto ou MQTTX) verificam o certificado do servidor do broker MQTT em relação ao certificado de CA confiável em seu armazenamento confiável. Para clientes mosquitto, use o --cafile parâmetro para especificar o arquivo de certificado da autoridade de certificação. Para MQTTX, adicione o certificado da autoridade de certificação ao armazenamento confiável nas configurações.

Depois de habilitar a autenticação X.509, certifique-se de que os clientes confiem no certificado do servidor do broker tendo o certificado da CA do lado do servidor em seu armazenamento confiável. Não confunda confiar 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 trustedClientCaCert cliente especificado no campo.

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

Conecte o cliente mosquitto ao corretor MQTT com certificado de cliente X.509

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

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

Nos casos em que o broker MQTT está usando um certificado de CA autoassinado para emitir seu certificado de servidor TLS, o --cafile parâmetro é necessário. Esse arquivo contém o certificado de CA (também conhecido como pacote de confiança) que o cliente mosquitto usa para validar o certificado do servidor do broker ao se conectar por TLS. Se o emissor do certificado do servidor do broker MQTT fizer parte do armazenamento raiz do sistema (como CAs públicas conhecidas), o --cafile parâmetro 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 do cliente X.509 do broker MQTT

A seguir estão as etapas para autenticação de cliente:

1. Quando a autenticação de cliente X.509 está ativada, os clientes conectados devem apresentar um certificado de cliente e quaisquer certificados intermediários para permitir que o corretor MQTT construa uma cadeia de certificados enraizada em um de seus certificados confiáveis configurados.
2. O balanceador de carga direciona a comunicação para um dos agentes frontend.
3. Depois que o agente de front-end recebe o certificado do cliente, ele tenta criar uma cadeia de certificados enraizada em um dos certificados configurados. Se o agente frontend construiu com êxito uma cadeia e a cadeia apresentada for verificada, ele concluirá o handshake TLS. O cliente de conexão é capaz de enviar pacotes MQTT para o frontend através do canal TLS.
4. O canal TLS está aberto, mas a autenticação ou autorização do cliente ainda não foi concluída.
5. Em seguida, o cliente envia um pacote CONNECT para o broker MQTT.
6. O pacote CONNECT é roteado para um frontend novamente.
7. O frontend coleta todas as credenciais que o cliente apresentou até agora, como dados de autenticação do pacote CONNECT e a cadeia de certificados do cliente apresentada durante o handshake TLS.
8. O frontend envia essas credenciais para o serviço de autenticação. O serviço de autenticação verifica a cadeia de certificados mais uma vez e coleta os nomes de assunto de todos os certificados na cadeia.
9. O serviço de autenticação usa suas regras de autorização configuradas para determinar quais atributos os clientes de conexão têm. Esses atributos determinam quais operações o cliente pode executar, incluindo o próprio pacote CONNECT.
10. O serviço de autenticação retorna a decisão para o agente frontend.
11. O agente frontend conhece 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 de conta de serviço Kubernetes

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

O corretor MQTT usa tokens de conta de serviço vinculados que são detalhados na postagem O que os usuários do GKE precisam saber sobre a nova postagem de tokens de conta de serviço do Kubernetes. Aqui estão as características salientes do post:

Lançados no Kubernetes 1.13 e se tornando o formato padrão na versão 1.21, os tokens vinculados abordam todas as funcionalidades limitadas dos tokens herdados e muito mais:

• Os tokens em si são mais difíceis de roubar e usar indevidamente; eles têm limite de tempo, de audiência e de objeto.
• Eles adotam um formato padronizado: OpenID Connect (OIDC), com OIDC Discovery completo, tornando mais fácil para os provedores de serviços aceitá-los.
• Eles são distribuídos para pods com mais segurança, usando um novo tipo de volume projetado Kubelet.

O broker verifica os tokens usando a API de revisão de token 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, elas começam com aio-broker-auth/ prefixo.

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, consulte Autorizar clientes que usam tokens de conta de serviço do Kubernetes.

Ativar autenticação de Token de Conta de Serviço (SAT)

Modifique a authenticationMethods configuração em um recurso BrokerAuthentication para especificar ServiceAccountToken como um método de autenticação válido. O audiences especifica a lista de audiências válidas para tokens. Escolha valores exclusivos que identifiquem o serviço de broker MQTT. Você deve especificar pelo menos uma audiência, e todas as SATs devem corresponder a uma das audiências especificadas.

Portal

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

Bicep

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 a CLI do Azure.

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

Kubernetes (visualização)

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

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

Testar autenticação SAT

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

Por exemplo, usando mosquitto (alguns campos omitidos por 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> é o nome da conta de serviço que você criou e <AUDIENCE> é uma das audiências configuradas no recurso BrokerAuthentication .

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

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

Atualizar tokens de conta de serviço

Os tokens de 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 de autenticação SAT de teste, 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 autenticar. O cliente também deve ter um mecanismo para lidar com erros não autorizados MQTT, buscando o token mais recente e tentando novamente a conexão.

Autenticação personalizada

Estenda a autenticação do cliente além dos métodos de autenticação fornecidos com autenticação personalizada. É conectável , uma vez que o serviço pode ser qualquer coisa, desde que adera à API.

Quando um cliente se conecta ao broker MQTT com a autenticação personalizada habilitada, o broker 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 serviço de autenticação personalizado

O servidor de autenticação personalizado é implementado e implantado separadamente do broker MQTT.

Um exemplo de servidor de autenticação personalizado e instruções estão disponíveis no GitHub. Use este exemplo como um modelo e 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 personalizado segue a especificação da API para autenticação personalizada. A especificação OpenAPI está disponível no GitHub.

HTTPS com criptografia TLS é necessário

O broker MQTT envia solicitações contendo credenciais de cliente confidenciais para o servidor de autenticação personalizado. Para proteger essas credenciais, a comunicação entre o agente MQTT e o servidor de autenticação personalizado 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 de CA raiz confiável para validar o certificado do servidor. Opcionalmente, o servidor de autenticação personalizado pode exigir que o agente MQTT apresente um certificado de cliente para autenticar-se.

Habilitar autenticação personalizada para um ouvinte

Modifique a authenticationMethods configuração 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.

Portal

1. No portal do Azure, navegue até sua instância de Operações IoT.

2. Em Componentes, selecione MQTT Broker.

3. Selecione a guia Autenticação .

4. Escolha uma política de autenticação existente ou crie uma nova.

5. Adicione um novo método selecionando Adicionar método.

6. Escolha o tipo de método Personalizado na lista suspensa e selecione Adicionar detalhes para configurar o método.

   

Bicep

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 a CLI do Azure.

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

Kubernetes (visualização)

Este 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

Desativar autenticação

Para testes, você pode desabilitar a autenticação para uma porta de ouvinte do broker. A desativação da autenticação não é recomendada para ambientes de produção.

Portal

1. No portal do Azure, navegue até sua instância de Operações IoT.
2. Em Componentes, selecione MQTT Broker.
3. Selecione o ouvinte do broker que você deseja editar na lista.
4. Na porta que você deseja desabilitar a autenticação, selecione Nenhuma na lista suspensa de autenticação.

Bicep

Para desativar a autenticação, omita o authenticationRef ports na configuração do seu recurso BrokerListener .

Kubernetes (visualização)

Para desativar a autenticação, omita o authenticationRef ports na configuração do seu recurso BrokerListener .

Os clientes se desconectam depois que as credenciais expiram

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

• Os clientes autenticados com SATs se desconectam quando o SAT expira
• Os 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 do servidor de autenticação personalizado.

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

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

Os clientes podem se autenticar novamente enviando um pacote MQTT v5 AUTH com razão 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 personalizado.

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

Conteúdos relacionados

• Sobre o recurso BrokerListener
• Configurar autorização para um BrokerListener
• Tutorial: TLS, autenticação de cliente X.509 e autorização de controle de acesso baseado em atributo (ABAC)