Configuración de la autorización del agente MQTT

Importante

En esta página se incluyen instrucciones para administrar componentes de Operaciones de IoT de Azure mediante manifiestos de implementación de Kubernetes, que se encuentra en versión preliminar. Esta característica se proporciona con varias limitacionesy no se debe usar para cargas de trabajo de producción.

Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Las directivas de autorización determinan qué acciones pueden realizar los clientes en el agente, como conectarse, publicar o suscribirse a temas. Configure el agente MQTT para usar una o varias directivas de autorización con el recurso de BrokerAuthorization. Cada recurso BrokerAuthorization contiene una lista de reglas que especifican las entidades de seguridad y los recursos de las directivas de autorización.

Vincular BrokerAuthorization a BrokerListener

Para vincular un BrokerListener a un recurso de BrokerAuthorization, especifique el campo authorizationRef en la configuración ports del recurso BrokerListener. De forma similar a BrokerAuthentication, el recurso BrokerAuthorization se puede vincular a varios puertos BrokerListener. Las directivas de autorización se aplican a todos los puertos de escucha vinculados. Sin embargo, hay una diferencia clave en comparación con BrokerAuthentication:

Importante

Para que la configuración de BrokerAuthorization se aplique a un puerto de escucha, al menos un BrokerAuthentication también debe estar vinculado a ese puerto de escucha.

Para obtener más información sobre BrokerListener, consulte el recurso BrokerListener.

Reglas de autorización

Para configurar la autorización, cree un recurso BrokerAuthorization en el clúster de Kubernetes. En las secciones siguientes se proporcionan ejemplos de cómo configurar la autorización para los clientes que usan nombres de usuario, atributos, certificados X.509 y Tokens de cuenta de servicio de Kubernetes (SAT). Para obtener una lista de las configuraciones disponibles, consulte la referencia de la API de autorización de broker.

En el ejemplo siguiente se muestra cómo crear un recurso de BrokerAuthorization mediante nombres de usuario y atributos:

Portal

1. En Azure Portal, vaya a su instancia de IoT Hub.

2. En Componentes, seleccione MQTT Broker.

3. Seleccione la pestaña Authorization (Autorización).

4. Elija una directiva de autenticación existente o cree una nueva seleccionando Crear directiva de autorización.

   

Bicep

Para editar una directiva de autorización, cree un archivo de Bicep .bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por los suyos propios.

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

Implemente el archivo de Bicep mediante la CLI de Azure.

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

Kubernetes (versión preliminar)

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 crear este recurso BrokerAuthorization, aplique el manifiesto de YAML al clúster de Kubernetes.

Esta autorización de agente permite a los clientes con id. de cliente temperature-sensor o humidity-sensor, o clientes con atributos organization con valor contoso y city con valor seattle, para:

• Conectarse al agente.
• Publique mensajes en temas de telemetría con su id. de usuario y organización. Por ejemplo:
  • temperature-sensor puede publicar en /telemetry/temperature-sensor y /telemetry/contoso.
  • humidity-sensor puede publicar en /telemetry/humidity-sensor y /telemetry/contoso.
  • some-other-username puede publicar en /telemetry/contoso.
• Suscríbase a temas de comandos en el ámbito de su organización. Por ejemplo:
  • temperature-sensor puede suscribirse a /commands/contoso.
  • some-other-username puede suscribirse a /commands/contoso.

Uso del nombre de usuario para la autorización

Para usar el nombre de usuario MQTT para la autorización, especifíquelos como una matriz en principals.usernames. Sin embargo, dependiendo del método de autenticación, es posible que el nombre de usuario no se compruebe:

• Kubernetes SAT: el nombre de usuario no debe usarse para la autorización porque no se comprueba para MQTTv5 con autenticación mejorada.
• X.509: el nombre de usuario coincide con el CN del certificado y se puede usar para las reglas de autorización.
• Personalizado: el nombre de usuario solo debe usarse para las reglas de autorización si la autenticación personalizada valida el nombre de usuario.

Para evitar problemas de seguridad, use solo el nombre de usuario MQTT para la autorización del agente cuando se pueda comprobar.

Limitar aún más el acceso en función del identificador de cliente

Dado que el campo principals es un OR lógico, puede restringir aún más el acceso en función del identificador de cliente agregando el campo clientIds al campo brokerResources. Por ejemplo, para permitir que los clientes con identificadores de cliente comiencen con su número de creación para conectarse y publicar datos de telemetría en temas con ámbito con su compilación, use la siguiente configuración:

Portal

En las reglas de autorización de agente para la directiva de autorización, use la siguiente configuración:

[
  {
    "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 una directiva de autorización, cree un archivo de Bicep .bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por los suyos propios.

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

Implementación de archivo Bicep mediante la CLI de Azure.

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

Kubernetes (versión preliminar)

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"

Aquí, si el clientIds no se estableció en el método Connect, un cliente con cualquier id. de cliente podría conectarse siempre que tuviera el atributo building establecido en building22 o building23. Al agregar el campo clientIds, solo los clientes con identificadores de cliente que comienzan por building22 o building23 pueden conectarse. Esto garantiza no solo que el cliente tenga el atributo correcto, sino también que el identificador de cliente coincida con el patrón esperado.

Autorización de clientes que usan la autenticación X.509

Los clientes que usan certificados X.509 para la autenticación se pueden autorizar para acceder a los recursos basados en las propiedades X.509 presentes en su certificado o en sus certificados emisores en la cadena.

Uso de atributos

Para crear reglas basadas en propiedades del certificado de un cliente, su CA raíz o CA intermedia, defina los atributos X.509 en el recurso BrokerAuthorization. Para obtener más información, vea Atributos de certificado.

Con el nombre común del firmante del certificado de cliente como nombre de usuario

Para crear directivas de autorización basadas solo en el nombre común del firmante del certificado de cliente (CN), cree reglas basadas en el CN.

Por ejemplo, si un cliente tiene un certificado con asunto CN = smart-lock, su nombre de usuario es smart-lock. Desde allí, cree directivas de autorización como normales.

Autorización de clientes que usan tokens de cuenta de Kubernetes Service

Los atributos de autorización para las SAT se establecen como parte de las anotaciones de la cuenta de servicio. Por ejemplo, para agregar un atributo de autorización denominado group con el valor authz-sat, ejecute el comando:

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

Las anotaciones de atributo deben comenzar con aio-broker-auth/ para distinguirlas de otras anotaciones.

Dado que la aplicación tiene un atributo de autorización denominado authz-sat, no es necesario proporcionar un clientId ni username. El recurso BrokerAuthorization correspondiente usa este atributo como entidad de seguridad, por ejemplo:

Portal

En las reglas de autorización de agente para la directiva de autorización, use la siguiente configuración:

[
  {
    "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 una directiva de autorización, cree un archivo de Bicep .bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por los suyos propios.

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

Implementación de archivo Bicep mediante la CLI de Azure.

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

Kubernetes (versión preliminar)

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 obtener más información con un ejemplo, consulte Configurar directiva de autorización con dapr Client.

Almacén de estado

El agente MQTT proporciona un almacén de estado que los clientes pueden usar para almacenar el estado. El almacén de estado también se puede configurar para que sea de alta disponibilidad.

Para configurar la autorización para los clientes que usan el almacén de estado, proporcione los permisos siguientes:

• Permiso para publicar en el tema del almacén de valores de clave del sistema $services/statestore/_any_/command/invoke/request
• Permiso para suscribirse al tema de respuesta (establecido durante la publicación inicial como parámetro) <response_topic>/#

Claves de almacén de estado

Se accede al almacén de estado a través del agente MQTT en el tema statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Dado que los clientes tienen acceso al tema, puede especificar claves y niveles de acceso en la sección stateStoreResources de la configuración del agente MQTT brokerResources.

El formato de sección stateStoreResources consta de nivel de acceso, un indicador de patrón y el patrón.

Portal

Incluya la sección stateStoreResources en las reglas de la directiva de autorización.

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

Bicep

En Bicep, incluya la sección stateStoreResources de la directiva de autorización.

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

En la definición de recursos personalizados, incluya la sección stateStoreResources de la directiva de autorización.

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

El campo method especifica el nivel de acceso.

• El acceso de lectura se especifica con read, acceso de escritura con write y ambos con readwrite.
• Se requiere el nivel de acceso.
• El nivel de acceso de lectura implica las acciones de get y keynotify.
• El nivel de acceso de escritura implica las acciones de set, del y vdel.

El campo keyType especifica el tipo de coincidencia de clave.

• pattern para usar la coincidencia de patrones de estilo glob
• string para hacer una coincidencia exacta, por ejemplo, cuando una clave contiene caracteres que podrían coincidir de otro modo como un patrón (*, ?, [0-9])
• binary para que coincida con una clave binaria

El campo keys especifica las claves que se van a hacer coincidir. Las claves se pueden especificar como patrones de estilo glob, sustituciones de tokens o cadenas exactas.

• Ejemplos de estilo glob:
  • colors/*: todas las claves bajo el prefijo "colors/"
  • number[0-9]: cualquier clave de "number0" a "number9"
  • char?: cualquier clave con el prefijo "char" y un sufijo de un solo dígito, como "charA"
  • *: acceso total a todas las claves.
• Las claves de almacén de estado también admiten la sustitución de tokens cuando el tipo de clave es pattern y las llaves están reservadas para este propósito. Ejemplos de sustitución de tokens:
  • clients/{principal.clientId}/*
  • usernames/{principal.username}/*
  • rooms/{principal.attributes.room}/*

Este es un ejemplo de cómo puede crear los recursos del almacén de estado:

Portal

En las reglas de autorización de Broker para la directiva de autorización, agregue una configuración similar:

[
  {
    "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 una directiva de autorización, cree un archivo de Bicep .bicep con el siguiente contenido. Actualice la configuración según sea necesario y reemplace los valores de marcador de posición como <AIO_INSTANCE_NAME> por los suyos propios.

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

Implementación de archivo Bicep mediante la CLI de 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.

Actualización de la autorización

Los recursos de autorización del agente se pueden actualizar en tiempo de ejecución sin reiniciar. Todos los clientes conectados en el momento de la actualización de la directiva se desconectan. También se admite el cambio del tipo de directiva.

kubectl edit brokerauthorization my-authz-policies

Deshabilitación de la autorización

Portal

1. En Azure Portal, vaya a su instancia de IoT Hub.
2. En Componentes, seleccione MQTT Broker.
3. Seleccione el cliente de escucha del corredor que desea editar en la lista.
4. En el puerto que desea deshabilitar la autorización, seleccione Ninguno en la lista desplegable de autorización.

Bicep

Para deshabilitar la autorización, omita authorizationRef en la configuración ports del recurso BrokerListener.

Kubernetes (versión preliminar)

Para deshabilitar la autorización, omita authorizationRef en la configuración ports del recurso BrokerListener.

Publicación no autorizada en MQTT 3.1.1

Con MQTT 3.1.1, cuando se deniega una publicación, el cliente recibe el PUBACK sin ningún error porque la versión del protocolo no admite la devolución de código de error. MQTTv5 devuelve PUBACK con el código de motivo 135 (no autorizado) cuando se deniega la publicación.

Contenido relacionado

• Acerca del recurso BrokerListener
• Configuración de la autenticación para un recurso BrokerListener
• Tutorial: TLS, autenticación de cliente X.509 y autorización de control de acceso basado en atributos (ABAC)