Configurer l’autorisation de l’agent MQTT

Important

Cette page inclut des instructions pour la gestion des composants Azure IoT Operations à l’aide des manifestes de déploiement Kubernetes, qui sont en version préliminaire. Cette fonctionnalité est fournie avec plusieurs limitations et ne doit pas être utilisée pour les charges de travail de production.

Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.

Les stratégies d’autorisation déterminent les actions que les clients peuvent effectuer sur le répartiteur, telles que la connexion, la publication ou l’abonnement aux rubriques. Configurer l’agent MQTT pour qu’il utilise une ou plusieurs stratégies d’autorisation à l’aide de la ressource BrokerAuthorization. Chaque ressource BrokerAuthorization contient une liste de règles qui spécifient les principaux et les ressources des stratégies d’autorisation.

Lier BrokerAuthorization à BrokerListener

Pour lier un BrokerListener à une ressource BrokerAuthorization, spécifiez le champ authorizationRef dans le paramètre ports de la ressource BrokerListener. Similaire à BrokerAuthentication, la ressource BrokerAuthorization peut être liée à plusieurs ports BrokerListener. Les stratégies d’autorisation s’appliquent à tous les ports d’écouteur liés. Toutefois, il existe une différence clé par rapport à BrokerAuthentication :

Important

Pour que la configuration BrokerAuthorization s’applique à un port d’écouteur, au moins une ressource BrokerAuthentication doit également être associée à ce port d’écouteur.

Pour en savoir plus sur BrokerListener, consultez la ressource BrokerListener.

Règles d’autorisation

Pour configurer l’autorisation, créez une ressource BrokerAuthorization dans votre cluster Kubernetes. Les sections suivantes fournissent des exemples de configuration d’autorisation pour les clients qui utilisent des noms d’utilisateur, des attributs, des certificats X.509 et des jetons de compte Kubernetes Service (SAP). Pour obtenir la liste des paramètres disponibles, consultez la référence de l’API d’autorisation Broker.

L’exemple suivant montre comment créer une ressource BrokerAuthorization à l’aide de noms d’utilisateur et d’attributs :

Portail

1. Dans le portail Azure, accédez à votre instance Opérations IoT.

2. Sous Composants, sélectionnez Agent MQTT.

3. Sélectionnez l’onglet Autorisation.

4. Choisissez une stratégie d’authentification existante ou créez-en une en sélectionnant Créer une stratégie d’autorisation.

   

Bicep

Pour modifier une stratégie d’autorisation, créez un fichier Bicep .bicep avec le contenu suivant. Mettez à jour les paramètres selon les besoins, puis remplacez les valeurs d’espace réservé telles que <AIO_INSTANCE_NAME> par les vôtres.

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

Déployez le fichier Bicep à l’aide d’Azure CLI.

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

Kubernetes (préversion)

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

Pour créer cette ressource BrokerAuthorization, appliquez le manifeste YAML à votre cluster Kubernetes.

Cette autorisation d’Agent permet aux clients ayant les ID client temperature-sensor ou humidity-sensor, ou ayant les attributs organization avec la valeur contoso et city avec la valeur seattle, de :

• se connecter au répartiteur ;
• Publier des messages dans des rubriques de télémétrie spécifiées par leurs ID client et leur organisation. Par exemple :
  • temperature-sensor peut publier sur /telemetry/temperature-sensor et /telemetry/contoso.
  • humidity-sensor peut publier sur /telemetry/humidity-sensor et /telemetry/contoso.
  • some-other-username peut publier sur /telemetry/contoso.
• Abonnez-vous aux rubriques de commandes délimitées par leur organisation. Par exemple :
  • temperature-sensor peut s’abonner à /commands/contoso.
  • some-other-username peut s’abonner à /commands/contoso.

Utilisation du nom d’utilisateur pour l’autorisation

Pour utiliser les noms d’utilisateur MQTT pour l’autorisation, spécifiez-les dans un tableau sous principals.usernames. Toutefois, selon la méthode d’authentification, le nom d’utilisateur peut ne pas être vérifié :

• Kubernetes SAT : le nom d’utilisateur ne doit pas être utilisé pour l’autorisation, car il n’est pas vérifié pour MQTTv5 avec une authentification renforcée.
• X.509 : le nom d’utilisateur correspond au CN du certificat et peut être utilisé pour les règles d’autorisation.
• Personnalisé : le nom d’utilisateur doit uniquement être utilisé pour les règles d’autorisation si l’authentification personnalisée valide le nom d’utilisateur.

Pour éviter les problèmes de sécurité, utilisez uniquement le nom d’utilisateur MQTT pour l’autorisation de l’Agent quand il peut être vérifié.

Limiter davantage l’accès en fonction de l’ID client

Étant donné que le champ principals est une or logique, vous pouvez restreindre davantage l’accès en fonction de l’ID client en ajoutant le champ clientIds au champ brokerResources. Par exemple, pour autoriser les clients avec des ID clients qui commencent par son numéro de construction pour connecter et publier des données de télémétrie dans des rubriques délimitées par leur génération, utilisez la configuration suivante :

Portail

Dans les règles d’autorisation d’Agent pour votre stratégie d’autorisation, utilisez la configuration suivante :

[
  {
    "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

Pour modifier une stratégie d’autorisation, créez un fichier Bicep .bicep avec le contenu suivant. Mettez à jour les paramètres selon les besoins, puis remplacez les valeurs d’espace réservé telles que <AIO_INSTANCE_NAME> par les vôtres.

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

Déployez le fichier Bicep à l’aide d’Azure CLI.

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

Kubernetes (préversion)

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"

Ici, si le clientIds n’était pas défini sous la méthode Connect, un client avec n’importe quel ID client pouvait se connecter tant qu’il avait l’attribut building défini sur building22 ou building23. En ajoutant le champ clientIds, seuls les clients disposant d’ID client qui commencent par building22 ou building23 peuvent se connecter. Cela garantit non seulement que le client a l’attribut correct, mais également que l’ID client correspond au modèle attendu.

Autoriser les clients qui utilisent l’authentification X.509

Les clients qui utilisent des certificats X.509 pour l’authentification peuvent être autorisés à accéder aux ressources basées sur les propriétés X.509 présentes sur leur certificat ou sur leurs certificats émetteurs dans la chaîne.

Utilisation d’attributs

Pour créer des règles basées sur les propriétés du certificat d’un client, de son autorité de certification racine ou intermédiaire, définissez les attributs X.509 dans la ressource BrokerAuthorization. Pour plus d’informations, consultez Attributs de certificat.

Avec le nom commun d’objet de certificat client comme nom d’utilisateur

Pour créer des stratégies d’autorisation basées uniquement sur le nom commun d’objet de certificat client, créez des règles basées sur le nom commun (CN).

Par exemple, si un client a un certificat avec l’objet CN = smart-lock, son nom d’utilisateur est smart-lock. À ce stade, créez des stratégies d’autorisation comme normale.

Autoriser les clients qui utilisent des jetons de comptes de service Kubernetes

Les attributs d’autorisation pour les SAT sont définis dans le cadre des annotations du compte de service. Par exemple, pour ajouter un attribut d’autorisation nommé group avec la valeur authz-sat, exécutez la commande :

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

Les annotations d’attributs doivent commencer par aio-broker-auth/ afin de se distinguer des autres annotations.

Comme l’application a un attribut d’autorisation appelé authz-sat, il n’est pas nécessaire de fournir clientId ni username. La ressource BrokerAuthorization correspondante utilise cet attribut comme principal, par exemple :

Portail

Dans les règles d’autorisation d’Agent pour votre stratégie d’autorisation, utilisez la configuration suivante :

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

Bicep

Pour modifier une stratégie d’autorisation, créez un fichier Bicep .bicep avec le contenu suivant. Mettez à jour les paramètres selon les besoins, puis remplacez les valeurs d’espace réservé telles que <AIO_INSTANCE_NAME> par les vôtres.

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

Déployez le fichier Bicep à l’aide d’Azure CLI.

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

Kubernetes (préversion)

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"

Pour en savoir plus avec un exemple, consultez Configurer la stratégie d’autorisation avec le client Dapr.

Magasin d’état

L’Agent MQTT fournit un magasin d’états que les clients peuvent utiliser pour stocker l’état. Le magasin d’états peut également être configuré pour la haute disponibilité.

Pour configurer l’autorisation pour les clients qui utilisent le magasin d’états distribué, fournissez les autorisations suivantes :

• Autorisation de publier sur la rubrique $services/statestore/_any_/command/invoke/request du magasin de valeurs de clé système
• Autorisation de s’abonner à la rubrique de réponse (définie lors de la publication initiale en tant que paramètre) <response_topic>/#

Clés de magasin d’états

Le magasin d’états est accessible via l’Agent MQTT sur la rubrique statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Comme les clients ont accès à la rubrique, vous pouvez spécifier des clés et des niveaux d’accès sous la section stateStoreResources de la configuration brokerResources de l’Agent MQTT.

Le format de section stateStoreResources se compose du niveau d’accès, d’un indicateur de modèle et du modèle.

Portail

Incluez la section stateStoreResources dans les règles de votre stratégie d’autorisation.

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

Bicep

Dans Bicep, incluez la section stateStoreResources dans votre stratégie d’autorisation.

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

Dans votre définition de ressource personnalisée, incluez la section stateStoreResources dans votre stratégie d’autorisation.

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

Le champ method spécifie le niveau d’accès.

• L’accès en lecture est spécifié avec read, l’accès en écriture avec writeet les deux avec readwrite.
• Le niveau d’accès est obligatoire.
• Le niveau d’accès en lecture implique les actions get et keynotify.
• Le niveau d’accès en écriture implique les actions set, del et vdel.

Le champ keyType spécifie le type de correspondance de clé.

• pattern pour utiliser les critères spéciaux de style glob
• string pour effectuer une correspondance exacte, par exemple, quand une clé contient des caractères qui peuvent être mis en correspondance en tant que modèle (*, ?, [0-9])
• binary pour correspondre à une clé binaire

Le champ keys spécifie les clés à mettre en correspondance. Les clés peuvent être spécifiées comme des modèles de style Glob, des substitutions de jeton ou des chaînes exactes.

• Exemples de style Glob :
  • colors/* : toutes les clés sous le préfixe « colors/ »
  • number[0-9] : n’importe quelle clé entre « number0 » et « number9 »
  • char? : n’importe quelle clé avec le préfixe « char » et un suffixe à un chiffre, comme « charA »
  • * : accès total à toutes les clés.
• Les clés de magasin d’états prennent également en charge la substitution de jeton quand le type de clé est pattern et que les accolades sont réservées à cet effet. Exemples de substitution de jeton :
  • clients/{principal.clientId}/*
  • usernames/{principal.username}/*
  • rooms/{principal.attributes.room}/*

Voici un exemple de création de vos ressources de magasin d’états :

Portail

Dans les règles d’autorisation d’Agent pour votre stratégie d’autorisation, ajoutez une configuration similaire :

[
  {
    "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

Pour modifier une stratégie d’autorisation, créez un fichier Bicep .bicep avec le contenu suivant. Mettez à jour les paramètres selon les besoins, puis remplacez les valeurs d’espace réservé telles que <AIO_INSTANCE_NAME> par les vôtres.

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

Déployez le fichier Bicep à l’aide d’Azure CLI.

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.

Mettre à jour une autorisation

Les ressources d’autorisation du répartiteur peuvent être mises à jour lors du runtime sans redémarrage. Tous les clients connectés au moment de la mise à jour de la stratégie sont déconnectés. La modification du type de stratégie est également prise en charge.

kubectl edit brokerauthorization my-authz-policies

Désactiver l’autorisation

Portail

1. Dans le portail Azure, accédez à votre instance Opérations IoT.
2. Sous Composants, sélectionnez Agent MQTT.
3. Sélectionnez l’écouteur d’agent que vous souhaitez modifier dans la liste.
4. Sur le port que vous souhaitez désactiver l’autorisation, sélectionnez Aucun dans la liste déroulante d’autorisation.

Bicep

Pour désactiver l’autorisation, omettez authorizationRef dans le paramètre ports d’une ressource BrokerListener.

Kubernetes (préversion)

Pour désactiver l’autorisation, omettez authorizationRef dans le paramètre ports d’une ressource BrokerListener.

Publication non autorisée dans MQTT 3.1.1

Avec MQTT 3.1.1, lorsqu’une publication est refusée, le client reçoit PUBACK sans erreur, car la version du protocole ne prend pas en charge le renvoi du code d’erreur. MQTTv5 retourne PUBACK avec le code de raison 135 (non autorisé) lorsque la publication est refusée.

Contenu connexe

• À propos de la ressource BrokerListener
• Configurer l’authentification pour un BrokerListener
• Tutoriel : TLS, authentification client X.509 et autorisation de contrôle d'accès basé sur les attributs (ABAC)