Konfigurieren der MQTT-Brokerautorisierung

Wichtig

Die von Azure Arc unterstützte Vorschauversion von „Azure IoT Einsatz“ befindet sich derzeit in der Vorschauphase. Sie sollten diese Vorschausoftware nicht in Produktionsumgebungen verwenden.

Sie müssen eine neue Installation von Azure IoT Einsatz bereitstellen, sobald eine allgemein verfügbare Version verfügbar ist. Sie werden kein Upgrade für eine Preview-Installation durchführen können.

Die zusätzlichen Nutzungsbestimmungen für Microsoft Azure-Vorschauen enthalten rechtliche Bedingungen. Sie gelten für diejenigen Azure-Features, die sich in der Beta- oder Vorschauversion befinden oder aber anderweitig noch nicht zur allgemeinen Verfügbarkeit freigegeben sind.

Mithilfe von Autorisierungsrichtlinien wird bestimmt, welche Aktionen die Clients mit dem Broker ausführen können, wie etwa Verbinden, Veröffentlichen oder Abonnieren von Themen. Konfigurieren Sie MQTT-Broker mithilfe der BrokerAuthorization-Ressource für die Verwendung einer oder mehrerer Autorisierungsrichtlinien. Jede BrokerAuthorization-Ressource enthält eine Liste von Regeln, die die Prinzipale und Ressourcen für die Autorisierungsrichtlinien angeben.

Verknüpfen von BrokerAuthorization mit BrokerListener

Um eine BrokerListener- mit einer BrokerAuthorization-Ressource zu verknüpfen, geben Sie das Feld authenticationRef in der Einstellung ports der BrokerListener-Ressource an. Ähnlich wie bei BrokerAuthentication kann die BrokerAuthorization-Ressource mit mehreren BrokerListener-Ports verknüpft werden. Die Autorisierungsrichtlinien gelten für alle verknüpften Listenerports. Es gibt jedoch einen wichtigen Unterschied im Vergleich zu BrokerAuthentication:

Wichtig

Damit die BrokerAuthorization-Konfiguration auf einen Listenerport angewendet werden kann, muss mindestens eine BrokerAuthentication ebenfalls mit dem betreffenden Listenerport verknüpft sein.

Weitere Informationen zu BrokerListener finden Sie unter BrokerListener-Ressource.

Autorisierungsregeln

Um die Autorisierung zu konfigurieren, erstellen Sie zuerst eine BrokerAuthorization-Ressource in Ihrem Kubernetes-Cluster. Die folgenden Abschnitte enthalten Beispiele zum Konfigurieren der Autorisierung für Clients, die Benutzernamen, Attribute, X.509-Zertifikate und Kubernetes-Dienstkontotoken (SATs) verwenden. Eine Liste der verfügbaren Einstellungen finden Sie in der API-Referenz zur Broker-Autorisierung.

Das folgende Beispiel zeigt, wie Sie eine BrokerAuthorization-Ressource mithilfe von Benutzernamen und Attributen erstellen:

Portal

1. Navigieren Sie im Azure-Portal zu Ihrer IoT Einsatz-Instanz.

2. Wählen Sie unter Azure IoT Einsatz-Ressourcen die Option MQTT-Broker aus.

3. Wählen Sie die Registerkarte Autorisierung.

4. Wählen Sie eine vorhandene Authentifizierungsrichtlinie aus, oder erstellen Sie eine neue, indem Sie Autorisierungsrichtlinie erstellen auswählen.

   

Bicep

Erstellen Sie zum Bearbeiten des Standardendpunkts eine Bicep-Datei (.bicep) mit folgendem Inhalt. Aktualisieren Sie die Einstellungen nach Bedarf, und ersetzen Sie die Platzhalterwerte wie <AIO_INSTANCE_NAME> durch Ihre eigenen Werte.

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {
  parent: aioInstance
  name: 'default'
}

resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {
  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}'
              ]
            }
          ]
        }
      ]
    }
  }
}

Stellen Sie die Bicep-Datei mithilfe der Azure CLI bereit.

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

Kubernetes

apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
kind: BrokerAuthorization
metadata:
  name: "my-authz-policies"
  namespace: azure-iot-operations
spec:
  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}"

Zum Erstellen dieser BrokerAuthorization-Ressource wenden Sie das YAML-Manifest auf Ihren Kubernetes-Cluster an.

Diese Brokerautorisierung ermöglicht Clients mit Benutzernamen temperature-sensor oder humidity-sensor bzw. Clients mit Attributen organization mit Wert contoso und city mit Wert seattle Folgendes:

• Herstellen einer Verbindung mit dem Broker.
• Veröffentlichen von Nachrichten in Telemetriethemen, für die ihre Benutzernamen und ihre Organisation als Geltungsbereich festgelegt sind. Beispiel:
  • temperature-sensor kann auf /telemetry/temperature-sensor und /telemetry/contoso veröffentlichen.
  • humidity-sensor kann auf /telemetry/humidity-sensor und /telemetry/contoso veröffentlichen.
  • some-other-username kann auf /telemetry/contoso veröffentlichen.
• Abonnieren von Befehlsthemen mit dem Geltungsbereich ihrer Organisation. Beispiel:
  • temperature-sensor kann /commands/contoso abonnieren.
  • some-other-username kann /commands/contoso abonnieren.

Weiteres Einschränken des Zugriffs basierend auf der Client-ID

Da das Feld principals ein logisches OR ist, können Sie den Zugriff basierend auf der Client-ID weiter einschränken, indem Sie das Feld clientIds zum Feld brokerResources hinzufügen. Um beispielsweise Kunden mit Kunden-IDs, die mit der Gebäudenummer beginnen, die Verbindung und Veröffentlichung von Telemetriedaten zu Themen zu ermöglichen, die sich auf ihr Gebäude beziehen, verwenden Sie die folgende Konfiguration:

Portal

Verwenden Sie in den Brokerautorisierungsdetails für Ihre Autorisierungsrichtlinie die folgende Konfiguration:

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

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {
  parent: aioInstance
  name: 'default'
}

resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {
  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'
              ]
            }
          ]
        }
      ]
    }
  }
}

Stellen Sie die Bicep-Datei mithilfe der Azure CLI bereit.

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

Kubernetes

apiVersion: mqttbroker.iotoperations.azure.com/v1beta1
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"

Wenn clientIds nicht unter der Connect-Methode festgelegt wurde, kann ein Client mit einer beliebigen Client-ID eine Verbindung herstellen, solange das Attribut building auf building22 oder building23 festgelegt ist. Durch Hinzufügen des Felds clientIds können nur Clients mit Client-IDs, die mit building22 oder building23 beginnen, eine Verbindung herstellen. Dadurch wird nicht nur sichergestellt, dass der Client über das richtige Attribut verfügt, sondern auch, dass die Client-ID dem erwarteten Muster entspricht.

Autorisieren von Clients, die X.509-Authentifizierung verwenden

Clients, die X.509-Zertifikate für die Authentifizierung verwenden, können für den Zugriff auf Ressourcen auf der Grundlage von X.509-Eigenschaften autorisiert werden, die in ihrem Zertifikat oder deren ausstellenden Zertifikaten weiter oben in der Kette vorhanden sind.

Attribute verwenden

Um Regeln basierend auf Eigenschaften aus dem Zertifikat eines Clients, seiner Stammzertifizierungsstelle oder Zwischenstellen zu erstellen, definieren Sie die X.509-Attribute in der BrokerAuthorization-Ressource. Weitere Informationen finden Sie unter Zertifikatattribute.

Mit allgemeinem Clientzertifikat-Antragstellernamen als Benutzername

Zum Erstellen von Autorisierungsrichtlinien, die ausschließlich auf dem allgemeinen Client-Zertifikat-Antragstellernamen (CN) beruhen, erstellen Sie Regeln im Ausgang vom CN.

Wenn ein Client beispielsweise über ein Zertifikat mit Antragsteller CN = smart-lock verfügt, lautet sein Benutzername smart-lock. Erstellen Sie von dort aus Autorisierungsrichtlinien wie gewohnt.

Autorisieren von Clients, die Kubernetes-Dienstkontotoken verwenden

Autorisierungsattribute für SATs werden als Teil der Dienstkontoanmerkungen festgelegt. Um beispielsweise ein Autorisierungsattribut namens group mit dem Wert authz-sat hinzuzufügen, führen Sie diesen Befehl aus:

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

Attributanmerkungen müssen mit aio-broker-auth/ beginnen, um sie von anderen Anmerkungen zu unterscheiden.

Da die Anwendung über ein Autorisierungsattribut mit dem Namen authz-sat verfügt, muss kein clientId oder username angegeben werden. Die entsprechende BrokerAuthorization-Ressource verwendet dieses Attribut als Prinzipal. Beispiel:

Portal

Verwenden Sie in den Brokerautorisierungsdetails für Ihre Autorisierungsrichtlinie die folgende Konfiguration:

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

Bicep

param aioInstanceName string = '<AIO_INSTANCE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'
param policyName string = '<POLICY_NAME>'

resource aioInstance 'Microsoft.IoTOperations/instances@2024-09-15-preview' existing = {
  name: aioInstanceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource defaultBroker 'Microsoft.IoTOperations/instances/brokers@2024-09-15-preview' existing = {
  parent: aioInstance
  name: 'default'
}

resource brokerAuthorization 'Microsoft.IoTOperations/instances/brokers/authorizations@2024-09-15-preview' = {
  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'
              ]
            }
          ]
        }
      ]
    }
  }
}

Stellen Sie die Bicep-Datei mithilfe der Azure CLI bereit.

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

Kubernetes

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

Weitere Informationen und ein Beispiel finden Sie unter Set up Authorization Policy with Dapr Client (Einrichten einer Autorisierungsrichtlinie mit dem Dapr-Client).

Verteilter Zustandsspeicher

Der MQTT-Broker stellt einen verteilten Zustandsspeicher (Distributed State Store, DSS) bereit, den Clients zum Speichern des Zustands verwenden können. Der DSS kann auch so konfiguriert werden, dass er hoch verfügbar ist.

Um die Autorisierung für Clients einzurichten, die den DSS verwenden, geben Sie die folgenden Berechtigungen an:

• Berechtigung zum Veröffentlichen im Thema $services/statestore/_any_/command/invoke/request des Systemschlüsselwertspeichers
• Berechtigung zum Abonnieren des Antwortthemas <response_topic>/# (während der ersten Veröffentlichung als Parameter festgelegt)

Weitere Informationen zur DSS-Autorisierung finden Sie unter Zustandsspeicherschlüssel.

Aktualisieren der Autorisierung

Brokerautorisierungsressourcen können zur Laufzeit ohne Neustart aktualisiert werden. Alle Clients, die zum Zeitpunkt der Aktualisierung der Richtlinie verbunden sind, werden getrennt. Das Ändern des Richtlinientyps wird ebenfalls unterstützt.

kubectl edit brokerauthorization my-authz-policies

Deaktivieren der Autorisierung

Portal

1. Navigieren Sie im Azure-Portal zu Ihrer IoT Einsatz-Instanz.
2. Wählen Sie unter Azure IoT Einsatz-Ressourcen die Option MQTT-Broker aus.
3. Wählen Sie in der Liste den Brokerlistener aus, den Sie bearbeiten möchten.
4. Wählen Sie für den Port, an dem Sie die Autorisierung deaktivieren möchten, in der Dropdownliste für die Aktualisierung die Option Keine aus.

Bicep

Zum Deaktivieren der Autorisierung lassen Sie authorizationRef in der ports-Einstellung Ihrer BrokerListener-Ressource aus.

Kubernetes

Zum Deaktivieren der Autorisierung lassen Sie authorizationRef in der ports-Einstellung Ihrer BrokerListener-Ressource aus.

Nicht autorisiertes Veröffentlichen in MQTT 3.1.1

Wenn bei MQTT 3.1.1 eine Veröffentlichung abgelehnt wird, empfängt der Client einen PUBACK ohne Fehler, da die Protokollversion die Rückgabe von Fehlercodes nicht unterstützt. MQTTv5 gibt PUBACK mit Ursachencode 135 (Nicht autorisiert) zurück, wenn eine Veröffentlichung abgelehnt wird.

Zugehöriger Inhalt

• Informationen zur BrokerListener-Ressource
• Konfigurieren der Authentifizierung für einen BrokerListener