Configurare l'autorizzazione del broker MQTT

Importante

Questa pagina include istruzioni per la gestione dei componenti di Operazioni IoT di Azure usando i manifesti di distribuzione kubernetes, disponibile in anteprima. Questa funzionalità viene fornita con diverse limitazioni e non deve essere usata per i carichi di lavoro di produzione.

Vedere le condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per termini legali aggiuntivi che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello generale.

I criteri di autorizzazione determinano le azioni che i client possono eseguire sul broker, ad esempio connettersi, pubblicare o sottoscrivere argomenti. Configurare il broker MQTT per l'uso di uno o più criteri di autorizzazione con la risorsa BrokerAuthorization. Ogni risorsa BrokerAuthorization contiene un elenco di regole che specificano le entità e le risorse per i criteri di autorizzazione.

Collegare BrokerAuthorization a BrokerListener

Per collegare una risorsa BrokerListener a una risorsa BrokerAuthorization, specificare il authorizationRef campo nell'impostazione ports della risorsa BrokerListener. Analogamente a BrokerAuthentication, la risorsa BrokerAuthorization può essere collegata a più porte BrokerListener. I criteri di autorizzazione si applicano a tutte le porte del listener collegato. Esiste una differenza fondamentale rispetto a BrokerAuthentication:

Importante

Per fare in modo che la configurazione brokerAuthorization si applichi a una porta del listener, almeno una risorsa BrokerAuthentication deve essere collegata anche a tale porta del listener.

Per altre informazioni su BrokerListener, vedere La risorsa BrokerListener.

Regole di autorizzazione

Per configurare l'autorizzazione, creare una risorsa BrokerAuthorization nel cluster Kubernetes. Le sezioni seguenti illustrano come configurare l'autorizzazione per i client che usano nomi utente, attributi, certificati X.509 e token dell'account del servizio Kubernetes. Per un elenco delle impostazioni disponibili, vedere le informazioni di riferimento sull'API di autorizzazione broker.

L'esempio seguente illustra come creare una risorsa BrokerAuthorization usando sia nomi utente che attributi.

Portale

1. Nella portale di Azure passare all'istanza di Operazioni IoT.

2. In Componenti selezionare MqTT Broker.

3. Selezionare la scheda Autorizzazione.

4. Scegliere un criterio di autenticazione esistente o crearne uno nuovo selezionando Crea criteri di autorizzazione.

   

Bicep

Per modificare un criterio di autorizzazione, creare un .bicep file con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad <AIO_INSTANCE_NAME> esempio con i propri.

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

Distribuire il file Bicep usando l'interfaccia della riga di comando di Azure:

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

Kubernetes (anteprima)

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

Per creare questa risorsa BrokerAuthorization, applicare il manifesto YAML al cluster Kubernetes.

Questa autorizzazione broker consente ai client con gli ID temperature-sensor client o humidity-sensor, o i client con gli attributi organization, con i valori contoso e city, e con il valore seattle, a:

• Connettersi al broker.
• Pubblicare messaggi negli argomenti di telemetria con gli ID client e l'organizzazione. Ad esempio:
  • temperature-sensor può pubblicare in /telemetry/temperature-sensor e /telemetry/contoso.
  • humidity-sensor può pubblicare in /telemetry/humidity-sensor e /telemetry/contoso.
  • some-other-username può pubblicare in /telemetry/contoso.
• /commands/ Sottoscrivere gli argomenti con ambito dell'organizzazione. Ad esempio:
  • temperature-sensor può effettuare la sottoscrizione a /commands/contoso.
  • some-other-username può effettuare la sottoscrizione a /commands/contoso.

Usare un nome utente per l'autorizzazione

Per usare il nome utente MQTT per l'autorizzazione, specificarli come matrice in principals.usernames. A seconda del metodo di autenticazione, il nome utente potrebbe non essere verificato:

• KUBernetes SAT: il nome utente non deve essere usato per l'autorizzazione perché non è verificato per MQTTv5 con autenticazione avanzata.
• X.509: il nome utente corrisponde al nome comune (CN) di un certificato e può essere usato per le regole di autorizzazione.
• Personalizzato: il nome utente deve essere usato solo per le regole di autorizzazione se l'autenticazione personalizzata convalida il nome utente.

Per evitare problemi di sicurezza, usare il nome utente MQTT per l'autorizzazione broker solo quando può essere verificato.

Limitare ulteriormente l'accesso in base all'ID client

Poiché il principals campo è logico OR, è possibile limitare ulteriormente l'accesso in base agli ID client aggiungendo il clientIds campo al brokerResources campo. Ad esempio, per consentire ai client con ID client che iniziano con il numero di compilazione di connettersi e pubblicare dati di telemetria agli argomenti con ambito della compilazione, usare la configurazione seguente:

Portale

Nelle regole di autorizzazione broker per i criteri di autorizzazione usare la configurazione seguente:

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

Per modificare un criterio di autorizzazione, creare un .bicep file con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad <AIO_INSTANCE_NAME> esempio con i propri.

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

Distribuire il file Bicep usando l'interfaccia della riga di comando di Azure:

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

Kubernetes (anteprima)

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"

In questo caso, se l'oggetto clientIds non è stato impostato nel Connect metodo , un client con qualsiasi ID client può connettersi purché l'attributo building sia impostato su building22 o building23. Quando si aggiunge il clientIds campo, solo i client con ID client che iniziano con building22 o building23 possono connettersi. Questa designazione garantisce che il client abbia l'attributo corretto e che l'ID client corrisponda al modello previsto.

Autorizzare i client che usano l'autenticazione X.509

È possibile autorizzare i client che usano certificati X.509 per l'autenticazione per accedere alle risorse in base alle proprietà X.509 presenti nel certificato o ai certificati rilasciati fino alla catena.

Uso degli attributi

Per creare regole in base alle proprietà del certificato di un client, alla CA radice o all'autorità di certificazione intermedia, definire gli attributi X.509 nella risorsa BrokerAuthorization. Per altre informazioni, vedere Attributi certificato.

Con il nome comune dell'oggetto del certificato client come nome utente

Per creare criteri di autorizzazione basati solo sul soggetto del certificato client , creare regole basate sul cn.

Ad esempio, se un client ha un certificato con l'oggetto CN = smart-lock, il nome utente è smart-lock. Da qui creare i criteri di autorizzazione come di consueto.

Autorizzare i client che usano token dell'account del servizio Kubernetes

Gli attributi di autorizzazione per le licenze di sicurezza vengono impostati come parte delle annotazioni dell'account del servizio. Ad esempio, per aggiungere un attributo di autorizzazione denominato group con il valore authz-sat, eseguire il comando :

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

Le annotazioni degli attributi devono iniziare con aio-broker-auth/ per distinguerle da altre annotazioni.

Poiché l'applicazione ha un attributo di autorizzazione denominato authz-sat, non è necessario fornire un clientId valore o username . La risorsa BrokerAuthorization corrispondente usa questo attributo come entità di sicurezza, ad esempio:

Portale

Nelle regole di autorizzazione broker per i criteri di autorizzazione usare la configurazione seguente:

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

Bicep

Per modificare un criterio di autorizzazione, creare un .bicep file con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad <AIO_INSTANCE_NAME> esempio con i propri.

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

Distribuire il file Bicep usando l'interfaccia della riga di comando di Azure:

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

Kubernetes (anteprima)

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"

Per altre informazioni con un esempio, vedere Configurare i criteri di autorizzazione con Dapr Client.

Archivio stati

Il broker MQTT fornisce un archivio stati che i client possono usare per archiviare lo stato. È anche possibile configurare l'archivio stati in modo che sia a disponibilità elevata.

Per configurare l'autorizzazione per i client che usano l'archivio stati, specificare le autorizzazioni seguenti:

• Autorizzazione per la pubblicazione sull'argomento dell'archivio dei valori chiave del sistema $services/statestore/_any_/command/invoke/request
• Autorizzazione per sottoscrivere l'argomento di risposta (impostato durante la pubblicazione iniziale come parametro) <response_topic>/#

Chiavi dell'archivio stati

L'archivio stati è accessibile tramite il broker MQTT nell'argomento statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Poiché i client hanno accesso all'argomento, è possibile specificare chiavi e livelli di accesso nella stateStoreResources sezione della configurazione del broker brokerResources MQTT.

Il stateStoreResources formato di sezione è costituito dal livello di accesso, da un indicatore del modello e dal modello.

Portale

Includere la stateStoreResources sezione nelle regole per i criteri di autorizzazione.

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

Bicep

In Bicep includere la stateStoreResources sezione nei criteri di autorizzazione.

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

Nella definizione della risorsa personalizzata includere la stateStoreResources sezione nei criteri di autorizzazione.

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

Il method campo specifica il livello di accesso:

• L'accesso in lettura viene specificato con read. L'accesso in scrittura viene specificato con write. L'accesso in lettura e scrittura viene specificato con readwrite.
• Il livello di accesso è obbligatorio.
• Il livello di accesso in lettura implica le azioni di get e keynotify.
• Il livello di accesso in scrittura implica le azioni di set, dele vdel.

Il keyType campo specifica il tipo di corrispondenza delle chiavi:

• pattern: usato per la corrispondenza dei criteri di stile glob.
• string: usato per eseguire una corrispondenza esatta, ad esempio quando una chiave contiene caratteri che potrebbero essere altrimenti corrispondenti come criterio (*, ?, [0-9]).
• binary: usato per trovare la corrispondenza con una chiave binaria.

Il keys campo specifica le chiavi da trovare. È possibile specificare le chiavi come modelli di stile glob, sostituzioni di token o stringhe esatte.

• Esempi di stile Glob:

  • colors/*: tutte le chiavi con il prefisso "colors/"
  • number[0-9]: qualsiasi chiave da "number0" a "number9"
  • char?: qualsiasi chiave con il prefisso "char" e un suffisso a cifra singola, ad esempio "charA"
  • *: accesso completo a tutte le chiavi

• Le chiavi dell'archivio stati supportano anche la sostituzione dei token quando il tipo di chiave è pattern e le parentesi graffe sono riservate a questo scopo. Esempi di sostituzione dei token:

  • clients/{principal.clientId}/*
  • usernames/{principal.username}/*
  • rooms/{principal.attributes.room}/*

Ecco un esempio di come creare le risorse dell'archivio stati.

Portale

Nelle regole di autorizzazione broker per i criteri di autorizzazione aggiungere una configurazione simile:

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

Per modificare un criterio di autorizzazione, creare un .bicep file con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad <AIO_INSTANCE_NAME> esempio con i propri.

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

Distribuire il file Bicep usando l'interfaccia della riga di comando di 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.

Aggiornare l’autorizzazione

È possibile aggiornare le risorse di autorizzazione broker in fase di esecuzione senza riavviare. Tutti i client connessi al momento dell'aggiornamento dei criteri vengono disconnessi. È supportata anche la modifica del tipo di criterio.

kubectl edit brokerauthorization my-authz-policies

Disabilitare l'autorizzazione

Portale

1. Nella portale di Azure passare all'istanza di Operazioni IoT.
2. In Componenti selezionare MqTT Broker.
3. Selezionare il listener broker da modificare nell'elenco.
4. Nella porta in cui si vuole disabilitare l'autorizzazione selezionare Nessuno nell'elenco a discesa autorizzazione.

Bicep

Per disabilitare l'autorizzazione, omettere authorizationRef nell'impostazione ports della risorsa BrokerListener.

Kubernetes (anteprima)

Per disabilitare l'autorizzazione, omettere authorizationRef nell'impostazione ports della risorsa BrokerListener.

Pubblicazione non autorizzata in MQTT 3.1.1

Con MQTT 3.1.1, quando la pubblicazione viene negata, il client riceve PUBACK senza errori perché la versione del protocollo non supporta la restituzione del codice di errore. MQTTv5 restituisce PUBACK con codice motivo 135 (non autorizzato) quando la pubblicazione viene negata.

Contenuto correlato

• Risorsa BrokerListener
• Configurare l'autenticazione per un BrokerListener
• Esercitazione: Autenticazione client TLS, X.509 e autorizzazione di controllo degli accessi in base agli attributi