Configurar a autorização do agente do MQTT

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.

As políticas de autorização determinam quais ações os clientes podem executar no agente, como conectar, publicar ou assinar tópicos. Configure o agente MQTT para usar uma ou várias políticas de autorização com o recurso BrokerAuthorization. Cada recurso BrokerAuthorization contém uma lista de regras que especificam as entidades de segurança e os recursos para as políticas de autorização.

Vincular BrokerAuthorization a BrokerListener

Para vincular um BrokerListener a um recurso BrokerAuthorization, especifique o campo authorizationRef na configuração ports do recurso BrokerListener. Semelhante a BrokerAuthentication, o recurso BrokerAuthorization pode ser vinculado a várias portas BrokerListener. As políticas de autorização se aplicam a todas as portas de ouvinte vinculadas. No entanto, há uma diferença importante em comparação com BrokerAuthentication:

Importante

Para que a configuração do BrokerAuthorization se aplique a uma porta de ouvinte, pelo menos um BrokerAuthentication também precisa estar vinculado a essa porta de ouvinte.

Para saber mais sobre BrokerListener, confira o recurso BrokerListener.

Regras de autorização

Para configurar a autorização, crie um recurso BrokerAuthorization no cluster do Kubernetes. As seções a seguir fornecem exemplos de como configurar a autorização para clientes que usam nomes de usuário, atributos, certificados X.509 e SATs (Tokens de Conta de Serviço) do Kubernetes. Para uma lista das configurações disponíveis, confira a Referência de API de Autorização do Broker.

O seguinte exemplo mostra como criar um recurso BrokerAuthorization usando nomes de usuário e atributos:

Portal

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

2. Em Componentes, selecione Agente MQTT.

3. Selecione a guia Autorização.

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

   

Bicep

Para editar uma política de autorizaçã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>'
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 brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authorizationPolicies: {
      cache: 'Enabled'
      rules: [
        {
          principals: {
            clientIds: [
              'temperature-sensor'
              'humidity-sensor'
            ]
            attributes: [
              {
                city: 'seattle'
                organization: 'contoso'
              }
            ]
          }
          brokerResources: [
            {
              method: 'Connect'
            }
            {
              method: 'Publish'
              topics: [
                '/telemetry/{principal.clientId}'
                '/telemetry/{principal.attributes.organization}'
              ]
            }
            {
              method: 'Subscribe'
              topics: [
                '/commands/{principal.attributes.organization}'
              ]
            }
          ]
        }
      ]
    }
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

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

Kubernetes (versão prévia)

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthorization
metadata:
  name: "my-authz-policies"
  namespace: azure-iot-operations
spec:
  authorizationPolicies:
    cache: Enabled
    rules:
      - principals:
          clientIds:
            - "temperature-sensor"
            - "humidity-sensor"
          attributes:
            - city: "seattle"
              organization: "contoso"
        brokerResources:
          - method: Connect
          - method: Publish
            topics:
              - "/telemetry/{principal.clientId}"
              - "/telemetry/{principal.attributes.organization}"
          - method: Subscribe
            topics:
              - "/commands/{principal.attributes.organization}"

Para criar esse recurso BrokerAuthorization, aplique o manifesto YAML ao cluster do Kubernetes.

Esta autorização do agente permite que clientes com IDs de cliente temperature-sensor e humidity-sensor, ou clientes com atributos organization com valor contoso e city com valor seattle:

• Conectar-se ao agente.
• Publiquem mensagens em tópicos de telemetria com escopo com suas IDs de cliente e organização. Por exemplo:
  • temperature-sensor pode publicar em /telemetry/temperature-sensor e /telemetry/contoso.
  • humidity-sensor pode publicar em /telemetry/humidity-sensor e /telemetry/contoso.
  • some-other-username pode publicar em /telemetry/contoso.
• Assinar os tópicos de comandos com escopo com sua organização. Por exemplo:
  • temperature-sensor pode assinar /commands/contoso.
  • some-other-username pode assinar /commands/contoso.

Uso do nome de usuário para autorização

Para usar o nome de usuário do MQTT para autorização, especifique-o como uma matriz em principals.usernames. No entanto, dependendo do método de autenticação, o nome de usuário pode não ser verificado:

• Kubernetes SAT – O nome de usuário não deve ser usado para autorização porque não é verificado para MQTTv5 com autenticação aprimorada.
• X.509 – o nome de usuário corresponde ao CN do certificado e pode ser usado para regras de autorização.
• Personalizado – o nome de usuário só deve ser usado para regras de autorização se a autenticação personalizada validar o nome de usuário.

Para evitar problemas de segurança, somente use o nome de usuário MQTT para autorização do agente quando ele puder ser verificado.

Limitar ainda mais o acesso com base na ID do cliente

Como o campo principals é um OU lógico, você pode restringir ainda mais o acesso com base no ID do cliente adicionando o campo clientIds ao campo brokerResources. Por exemplo, para permitir que clientes com IDs de cliente que começam com o número da compilação deles se conectem e publiquem telemetria em tópicos com escopo com sua compilação, use a seguinte configuração:

Portal

Nas regras de autorização do agente para a sua política de autorização, use a seguinte configuração:

[
  {
    "brokerResources": [
      {
        "clientIds": [
          "{principal.attributes.building}*"
        ],
        "method": "Connect",
        "topics": []
      },
      {
        "clientIds": [],
        "method": "Publish",
        "topics": [
          "sensors/{principal.attributes.building}/{principal.clientId}/telemetry"
        ]
      }
    ],
    "principals": {
      "attributes": [
        {
          "building": "building22"
        },
        {
          "building": "building23"
        }
      ]
    }
  }
]

Bicep

Para editar uma política de autorizaçã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>'
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 brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authorizationPolicies: {
      cache: 'Enabled'
      rules: [
        {
          principals: {
            attributes: [
              {
                building: 'building22'
              }
              {
                building: 'building23'
              }
            ]
          }
          brokerResources: [
            {
              method: 'Connect'
              clientIds: [
                '{principal.attributes.building}*' // client IDs must start with building22
              ]
            }
            {
              method: 'Publish'
              topics: [
                'sensors/{principal.attributes.building}/{principal.clientId}/telemetry'
              ]
            }
          ]
        }
      ]
    }
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

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

Kubernetes (versão prévia)

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthorization
metadata:
  name: "my-authz-policies"
  namespace: azure-iot-operations
spec:
  authorizationPolicies:
    cache: Enabled
    rules:
    - principals:
        attributes:
          - building: "building22"
          - building: "building23"
      brokerResources:
      - method: Connect
        clientIds:
          - "{principal.attributes.building}*" # client IDs must start with building22
      - method: Publish
        topics:
          - "sensors/{principal.attributes.building}/{principal.clientId}/telemetry"

Aqui, se o clientIds não fosse definido no método Connect, um cliente com qualquer ID de cliente poderia se conectar, desde que tivesse o atributo building definido como building22 ou building23. Ao adicionar o campo clientIds, somente os clientes com IDs do cliente que começam building22 ou building23 podem se conectar. Isso garante não apenas que o cliente tenha o atributo correto, mas também que a ID do cliente corresponda ao padrão esperado.

Autorizar clientes que usam a autenticação X.509

Os clientes que usam certificados X.509 para autenticação podem ser autorizados a acessar recursos com base nas propriedades X.509 presentes em seu certificado ou em seus certificados emissores na cadeia.

Usar atributos

Para criar regras com base em propriedades do certificado de um cliente, sua AC raiz ou AC intermediária, defina os atributos X.509 no recurso BrokerAuthorization. Para obter mais informações, consulte Atributos de certificado.

Com o nome comum da entidade de certificado do cliente como nome de usuário

Para criar políticas de autorização com base apenas no CN (nome comum) da entidade de certificado do cliente, crie regras com base na CN.

Por exemplo, se um cliente tiver um certificado com assunto CN = smart-lock, seu nome de usuário será smart-lock. A partir daí, crie políticas de autorização normalmente.

Autorizar clientes que usam tokens de conta de serviço do Kubernetes

Os atributos de autorização para SATs são definidos como parte das Anotações da Conta de Serviço. Por exemplo, para adicionar um atributo de autorização nomeado group com valor authz-sat, execute o comando:

kubectl annotate serviceaccount mqtt-client aio-broker-auth/group=authz-sat

As anotações de atributo devem começar com aio-broker-auth/ para distingui-las de outras anotações.

Como o aplicativo tem um atributo de autorização chamado authz-sat, não é necessário fornecer um clientId ou username. O recurso BrokerAuthorization correspondente usa esse atributo como entidade de segurança, por exemplo:

Portal

Nas regras de autorização do Agente para a sua política de autorização, use a seguinte configuração:

[
  {
    "brokerResources": [
      {
        "clientIds": [],
        "method": "Connect",
        "topics": []
      },
      {
        "clientIds": [],
        "method": "Publish",
        "topics": [
          "odd-numbered-orders"
        ]
      },
      {
        "clientIds": [],
        "method": "Subscribe",
        "topics": [
          "orders"
        ]
      }
    ],
    "principals": {
      "attributes": [
        {
          "group": "authz-sat"
        }
      ]
    }
  }
]

Bicep

Para editar uma política de autorizaçã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>'
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 brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authorizationPolicies: {
      rules: [
        {
          principals: {
            attributes: [
              {
                group: 'authz-sat'
              }
            ]
          }
          brokerResources: [
            {
              method: 'Connect'
            }
            {
              method: 'Publish'
              topics: [
                'odd-numbered-orders'
              ]
            }
            {
              method: 'Subscribe'
              topics: [
                'orders'
              ]
            }
          ]
        }
      ]
    }
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

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

Kubernetes (versão prévia)

apiVersion: mqttbroker.iotoperations.azure.com/v1
kind: BrokerAuthorization
metadata:
  name: "my-authz-policies"
  namespace: azure-iot-operations
spec:
  authorizationPolicies:
    cache: Enabled
    rules:
      - principals:
          attributes:
            - group: "authz-sat"
        brokerResources:
          - method: Connect
          - method: Publish
            topics:
              - "odd-numbered-orders"
          - method: Subscribe
            topics:
              - "orders"

Para saber mais com um exemplo, consulte Configurar a Política de Autorização com o Cliente Dapr.

Armazenamento de estado

O Agente MQTT fornece um repositório de estado que os clientes podem usar para armazenar o estado. O repositório de estado também pode ser configurado para estar altamente disponível.

Para configurar a autorização para clientes que usam o repositório de estado, forneça as seguintes permissões:

• Permissão para publicar no armazenamento de valores-chave do sistema do tópico $services/statestore/_any_/command/invoke/request
• Permissão para assinar o tópico de resposta (definido durante a publicação inicial como um parâmetro) <response_topic>/#

Chaves do repositório de estado

O repositório de estado é acessado pelo agente MQTT no tópico statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Como os clientes têm acesso ao tópico, você pode especificar chaves e níveis de acesso na seção stateStoreResources da configuração brokerResources do agente MQTT.

O formato de seção stateStoreResources consiste em nível de acesso, um indicador de padrão e o padrão.

Portal

Inclua a seção stateStoreResources nas regras da política de autorização.

"stateStoreResources": [
  {
    "method": "", // Values: read, write, readwrite 
    "keyType": "", //Values: string, pattern, binary. Default is pattern
    "keys": [
      // List of patterns to match
    ]
  },
]

Bicep

No Bicep, inclua a seção stateStoreResources em sua política de autorização.

stateStoreResources: [
  {
    method: '' // Values: read, write, readwrite 
    keyType: '' //Values: string, pattern, binary. Default is pattern
    keys: [
      // List of patterns to match
    ]
  }
  {
    method: 'ReadWrite'
    keyType: 'Binary'
    keys: [
      'xxxxxxxxxxxxxxxxxxxx'
    ]
  }
]

Kubernetes

Em sua definição de recurso personalizada, inclua a seção stateStoreResources em sua política de autorização.

stateStoreResources:
  - method:  # Values: read, write, readwrite 
    keyType: # Values: string, pattern, binary. Default is pattern
    keys:
      - # List of patterns to match

O campo method especifica o nível de acesso.

• O acesso de leitura é especificado com read, o acesso de gravação com write e ambos com readwrite.
• O nível de acesso é necessário.
• O nível de acesso de leitura implica as ações de get e keynotify.
• O nível de acesso de gravação implica as ações de set, del e vdel.

O campo keyType especifica o tipo de correspondência de chave.

• pattern para usar a correspondência de padrões de estilo glob
• string para fazer a correspondência exata, por exemplo, quando uma chave contém caracteres que podem ser correspondidos como um padrão (*, ?, [0-9])
• binary para corresponder a uma chave binária

O campo keys especifica as chaves a serem correspondidas. As chaves podem ser especificadas como padrões de estilo Glob, substituições de token ou cadeias de caracteres exatas.

• Exemplos de estilo Glob:
  • colors/*: todas as chaves sob o prefixo "colors/"
  • number[0-9]: qualquer chave de "number0" a "number9"
  • char?: qualquer chave com o prefixo "char" e um sufixo de dígito único, como "charA"
  • *: acesso total a todas as chaves.
• As chaves do repositório de estado também dão suporte à substituição de token quando o tipo de chave é pattern e as chaves são reservadas para esta finalidade. Exemplos de substituição de token:
  • clients/{principal.clientId}/*
  • usernames/{principal.username}/*
  • rooms/{principal.attributes.room}/*

Aqui está um exemplo de como você pode criar os seus recursos do repositório de estado:

Portal

Nas regras de autorização do Agente para a sua política de autorização, adicione uma configuração semelhante:

[
  {
    "brokerResources": [
      {
        "clientIds": [
          "{principal.attributes.building}*"
        ],
        "method": "Connect"
      },
      {
        "method": "Publish",
        "topics": [
          "sensors/{principal.attributes.building}/{principal.clientId}/telemetry/*"
        ]
      },
      {
        "method": "Subscribe",
        "topics": [
          "commands/{principal.attributes.organization}"
        ]
      }
    ],
    "principals": {
      "attributes": [
        {
          "building": "17",
          "organization": "contoso"
        }
      ],
      "usernames": [
        "temperature-sensor",
        "humidity-sensor"
      ]
    },
    "stateStoreResources": [
      {
        "method": "Read",
        "keyType": "Pattern",
        "keys": [
          "myreadkey",
          "myotherkey?",
          "mynumerickeysuffix[0-9]",
          "clients/{principal.clientId}/*"
        ]
      },
      {
        "method": "ReadWrite",
        "keyType": "Binary",
        "keys": [
          "xxxxxxxxxxxxxxxxxxxx"
        ]
      }
    ]
  }
]

Bicep

Para editar uma política de autorizaçã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>'
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 brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-11-01' = {
  parent: defaultBroker
  name: policyName
  extendedLocation: {
    name: customLocation.id
    type: 'CustomLocation'
  }
  properties: {
    authorizationPolicies: {
      cache: 'Enabled'
      rules: [
        {
          principals: {
            usernames: [
              'temperature-sensor'
              'humidity-sensor'
            ]
            attributes: [
              {
                city: 'seattle'
                organization: 'contoso'
              }
            ]
          }
          brokerResources: [
            {
              method: 'Connect'
            }
            {
              method: 'Publish'
              topics: [
                '/telemetry/{principal.username}'
                '/telemetry/{principal.attributes.organization}'
              ]
            }
            {
              method: 'Subscribe'
              topics: [
                '/commands/{principal.attributes.organization}'
              ]
            }
          ]
          stateStoreResources: [
            {
              method: 'Read'
              keyType: 'Pattern'
              keys: [
                'myreadkey'
                'myotherkey?'
                'mynumerickeysuffix[0-9]'
                'clients/{principal.clientId}/*'
              ]
            }
            {
              method: 'ReadWrite'
              keyType: 'Binary'
              keys: [
                'xxxxxxxxxxxxxxxxxxxx'
              ]
            }
          ]
        }
      ]
    }
  }
}

Implante o arquivo Bicep usando o CLI do Azure.

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

Kubernetes

stateStoreResources:
  - method: Read # Read includes Get, Notify
    keyType: "pattern" # string, pattern, binary
    keys:
      - "myreadkey" # explicit read access on key: myreadkey
      - "myotherkey?" # single digit wildcard
      - "mynumerickeysuffix[0-9]" # single digit number range
      - "clients/{principal.clientId}/*" # use token substitution and a wildcard for per-client sandboxing
  - method: ReadWrite  # ReadWrite access includes Get, Notify, Set, Del
    keyType: "binary" # binary keys have exact match, no patterns
    keys:
      - "xxxxxxxxxxxxxxxxxxxx"  # base-64 encoded binary key.

Atualizar autorização

Os recursos de autorização do agente podem ser atualizados em runtime sem reinicialização. Todos os clientes conectados no momento da atualização da política são desconectados. Também há suporte para alterar o tipo de política.

kubectl edit brokerauthorization my-authz-policies

Desabilitar autorização

Portal

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

Bicep

Para desabilitar a autorização, omita authorizationRef na configuração ports do seu recurso BrokerListener.

Kubernetes (versão prévia)

Para desabilitar a autorização, omita authorizationRef na configuração ports do seu recurso BrokerListener.

Publicação não autorizada no MQTT 3.1.1

Com o MQTT 3.1.1, quando uma publicação é negada, o cliente recebe o PUBACK sem nenhum erro porque a versão do protocolo não dá suporte ao retorno do código de erro. O MQTTv5 retorna PUBACK com o código de motivo 135 (não autorizado) quando a publicação é negada.

Conteúdo relacionado

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