Configurar a autorização do broker 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.

As políticas de autorização determinam quais ações os clientes podem executar no broker, como conectar, publicar ou assinar tópicos. Configure o broker 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 os principais e recursos para as políticas de autorização.

Link BrokerAuthorization para BrokerListener

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

Importante

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

Para saber mais sobre o BrokerListener, consulte 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 (Service Account Tokens) do Kubernetes. Para obter uma lista das configurações disponíveis, consulte a referência da API de autorização do broker.

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

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

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

Kubernetes (visualização)

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 de broker permite que clientes com IDs de temperature-sensor cliente ou humidity-sensor, ou clientes com atributos organization com valor contoso e city com valor seattle, possam:

• Conecte-se ao corretor.
• Publique 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.
• Inscreva-se em tópicos de comandos com escopo com sua organização. Por exemplo:
  • temperature-sensor pode subscrever o /commands/contoso.
  • some-other-username pode subscrever o /commands/contoso.

Usando nome de usuário para autorização

Para usar o nome de usuário MQTT para autorização, especifique-os 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 utilizador corresponde ao CN do certificado e pode ser utilizado 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, use apenas o nome de usuário MQTT para autorização do broker quando ele puder ser verificado.

Limite ainda mais o acesso com base no ID do cliente

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

Portal

Nas regras de autorização do broker para 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 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>'
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 a CLI do Azure.

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

Kubernetes (visualização)

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 sob o Connect método, um cliente com qualquer ID de cliente poderia se conectar, desde que tivesse o building atributo definido como building22 ou building23. Ao adicionar o clientIds campo, somente clientes com IDs de cliente que começam com building22 ou building23 podem se conectar. Isso garante não apenas que o cliente tenha o atributo correto, mas também que o ID do cliente corresponda ao padrão esperado.

Autorizar clientes que usam 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.

Usando atributos

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

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

Para criar políticas de autorização com base apenas no CN (nome comum) da entidade do certificado do cliente , crie regras baseadas no 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 atributos devem começar para aio-broker-auth/ distingui-las de outras anotações.

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

Portal

Nas regras de autorização do Broker para 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 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>'
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 a CLI do Azure.

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

Kubernetes (visualização)

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 Dapr Client.

Armazenamento de estado

O broker MQTT fornece um armazenamento de estado que os clientes podem usar para armazenar o estado. O armazenamento de estado também pode ser configurado para ser altamente disponível.

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

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

Chaves de armazenamento de estado

O armazenamento de estado é acessado através do broker 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 stateStoreResources seção da configuração do broker brokerResources MQTT.

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

Portal

Inclua a stateStoreResources seção nas regras da 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
    ]
  },
]

Bicep

No Bicep, inclua a stateStoreResources seção 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

Na sua definição de recurso personalizada, inclua a stateStoreResources secção na 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 method campo especifica o nível de acesso.

• O acesso de leitura é especificado com read, acesso de gravação com write, e ambos com readwrite.
• O nível de acesso é obrigató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, dele vdel.

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

• patternPara 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 poderiam ser correspondidos como um padrão (*, ?, [0-9])
• binary para corresponder a uma chave binária

O keys campo 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 teclas sob o prefixo "colors/"
  • number[0-9]: Qualquer chave de "número0" a "número9"
  • char?: Qualquer tecla com prefixo "char" e um sufixo de um único dígito, como "charA"
  • *: Acesso total a todas as chaves.
• As chaves de armazenamento de estado também suportam a substituição de token quando o tipo de chave é pattern e chaves são reservadas para essa finalidade. Exemplos de substituição de tokens:
  • clients/{principal.clientId}/*
  • usernames/{principal.username}/*
  • rooms/{principal.attributes.room}/*

Aqui está um exemplo de como você pode criar seus recursos de armazenamento de estado:

Portal

Nas regras de autorização do Broker para 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 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>'
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 a 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.

Autorização de atualização

Os recursos de autorização do broker podem ser atualizados em tempo de execução sem reinicialização. Todos os clientes conectados no momento da atualização da política são desconectados. A alteração do tipo de política também é suportada.

kubectl edit brokerauthorization my-authz-policies

Desativar autorizaçã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 autorização, selecione Nenhuma na lista suspensa de autorização.

Bicep

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

Kubernetes (visualização)

Para desativar a autorização, omita authorizationRef na configuração do ports 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 erro porque a versão do protocolo não suporta o código de erro de retorno. MQTTv5 retorna PUBACK com código de razão 135 (Não autorizado) quando a publicação é negada.

Conteúdos relacionados

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