Configurare l'autorizzazione del broker MQTT

Importante

Questa pagina include istruzioni per la gestione dei componenti di Operazioni di Azure IoT usando i manifesti di distribuzione kubernetes, disponibile in anteprima. Questa funzionalità viene fornita con diverse limitazioni e non deve essere usata per 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à di sicurezza e le risorse per i criteri di autorizzazione.

Come vengono valutate le regole

• I criteri sono applicabili solo se consentiti. Se nessuna regola consente esplicitamente un'azione su una risorsa per un'entità, l'azione viene negata.
• Una regola è definita da tre fattori: entità (attore), azione (operazioni di connessione/pubblicazione/sottoscrizione/archivio stati) e risorsa (argomenti o chiavi).
• Le entità all'interno di una regola vengono associate con l'operatore logico OR. Ad esempio, qualsiasi nome utente, clientId o attributo elencato concede l'accesso alle risorse nella regola.

Sostituzione dei token e caratteri jolly

• Per argomenti e chiavi, è possibile usare la sostituzione dei token per compilare regole che si adattino a livello di client: {principal.username}, {principal.clientId} e {principal.attributes.<attributeName>}.
• I caratteri jolly dell'argomento MQTT + e # sono supportati in brokerResources.topics.
• Quando si usa la sostituzione dei token in un argomento, il token deve essere l'unico testo nel segmento di percorso. Ad esempio, clients/{principal.clientId}/# è valido, ma client-{principal.clientId}/# non lo è.
• Le azioni di connessione non devono includere argomenti.

Collegare BrokerAuthorization a BrokerListener

Per collegare una risorsa BrokerListener a una risorsa BrokerAuthorization, specificare il campo authorizationRef 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 listener collegate. Esiste una differenza fondamentale rispetto a BrokerAuthentication:

Importante

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

Per altre informazioni su BrokerListener, vedere Risorsa BrokerListener.

Regole di autorizzazione

Per configurare l'autorizzazione, creare una risorsa BrokerAuthorization nel cluster Kubernetes. Le sezioni seguenti forniscono esempi di come configurare l'autorizzazione per i client che usano nomi utente, attributi, certificati X.509 e token dell'account del servizio Kubernetes (SAT). 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. Nel portale di Azure passare all'istanza di Operazioni IoT.

2. In Componenti, selezionare Broker MQTT.

3. Selezionare la scheda Autorizzazione.

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

   

Interfaccia della riga di comando di Azure

Usare il comando az iot ops broker authz apply per creare o modificare un criterio di autorizzazione.

az iot ops broker authz apply --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker <BrokerName> --name <AuthenticationResourceName> --config-file <ConfigFilePathAndName>

In questo esempio si supponga che un file di configurazione denominato my-authz-policy.json con il contenuto seguente archiviato nella home directory dell'utente:

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

Un comando di esempio per creare un nuovo criterio di autorizzazione denominato my-authz-policy è:

az iot ops broker authz apply --resource-group myResourceGroupName --instance myAioInstanceName --broker default --name my-authz-policy --config-file ~/my-authz-policy.json

Bicipite

Per modificare un criterio di autorizzazione, creare un file .bicep con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad esempio <AIO_INSTANCE_NAME>, 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: [
                '/sensor/{principal.clientId}'
                '/sensor/{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:
              - "/sensor/{principal.clientId}"
              - "/sensor/{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 client temperature-sensor o humidity-sensor oppure i client con gli attributi organization, con i valori contoso e city, e con il valore seattle, di:

• Connettersi al broker.
• Pubblicare messaggi negli argomenti definiti con i loro ID client e organizzazione. Ad esempio:
  • temperature-sensor può pubblicare in /sensor/temperature-sensor e /sensor/contoso.
  • humidity-sensor può pubblicare in /sensor/humidity-sensor e /sensor/contoso.
  • some-other-username può pubblicare in /sensor/contoso.
• Eseguire la sottoscrizione ad argomenti /commands/ con ambito 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 array in principals.usernames. A seconda del metodo di autenticazione, il nome utente potrebbe non essere verificato:

• SAT Kubernetes: 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.

Suggerimento

Per richiedere che il nome utente MQTT corrisponda all'ID client, usare la sostituzione dei token:

principals:
  usernames:
    - "{principal.clientId}"

Limitare ulteriormente l'accesso in base all'ID client

Poiché il campo principals è un OR logico, è possibile limitare ulteriormente l'accesso in base agli ID client aggiungendo il campo clientIds al campo brokerResources. Ad esempio, per consentire ai client con ID client che iniziano con il numero dell'edificio di connettersi e pubblicare in argomenti con ambito edificio, 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}/sensor"
        ]
      }
    ],
    "principals": {
      "attributes": [
        {
          "building": "building22"
        },
        {
          "building": "building23"
        }
      ]
    }
  }
]

Interfaccia della riga di comando di Azure

Usare il comando az iot ops broker authz apply per creare o modificare un criterio di autorizzazione.

az iot ops broker authz apply --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker <BrokerName> --name <AuthenticationResourceName> --config-file <ConfigFilePathAndName>

Nelle regole di autorizzazione broker per i criteri di autorizzazione, creare un file di configurazione denominato client-id-policy.json con la configurazione seguente archiviata nella directory home dell'utente:

{
  "authorizationPolicies": {
    "cache": "Enabled",
    "rules": [
      {
        "brokerResources": [
          {
            "clientIds": [
              "{principal.attributes.building}*"
            ],
            "method": "Connect",
            "topics": []
          },
          {
            "clientIds": [],
            "method": "Publish",
            "topics": [
              "sensors/{principal.attributes.building}/{principal.clientId}/sensor"
            ]
          }
        ],
        "principals": {
          "attributes": [
            {
              "building": "building22"
            },
            {
              "building": "building23"
            }
          ]
        }
      }
    ]
  }
}

Un comando di esempio per creare un nuovo criterio di autorizzazione denominato client-id-authz-policy è:

az iot ops broker authz apply --resource-group myResourceGroupName --instance myAioInstanceName --broker default --name my-authz-policy --config-file ~/client-id-authz-policy.json

Bicipite

Per modificare un criterio di autorizzazione, creare un file .bicep con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad esempio <AIO_INSTANCE_NAME>, 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}/sensor'
              ]
            }
          ]
        }
      ]
    }
  }
}

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

In questo caso, se l'oggetto clientIds non è stato impostato nel metodo Connect, un client con qualsiasi ID client potrebbe connettersi purché l'attributo building sia impostato su building22 o building23. Quando si aggiunge il campo clientIds, 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 nei certificati rilasciati in alto nella catena.

Usare attributi

Per creare regole in base alle proprietà da un certificato client, CA radice o 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 CN dell'oggetto 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 account del servizio Kubernetes

Gli attributi di autorizzazione per SAT 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 valore clientId 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"
        }
      ]
    }
  }
]

Interfaccia della riga di comando di Azure

Usare il comando az iot ops broker authz apply per creare o modificare un criterio di autorizzazione.

az iot ops broker authz apply --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker <BrokerName> --name <AuthenticationResourceName> --config-file <ConfigFilePathAndName>

In questo esempio si supponga che un file di configurazione denominato my-authz-policy.json con il contenuto seguente archiviato nella home directory dell'utente:

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

Un comando di esempio per creare un nuovo criterio di autorizzazione denominato my-authz-policy è:

az iot ops broker authz apply --resource-group myResourceGroupName --instance myAioInstanceName --broker default --name my-authz-policy --config-file ~/my-authz-policy.json

Bicipite

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

Stato store

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, fornire le autorizzazioni per gli argomenti e le chiavi del protocollo:

• Pubblicare le richieste in: statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke.
• Sottoscrivere l'argomento di risposta impostato in caso di pubblicazione, in genere: clients/{principal.clientId}/services/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke/response/#.
• Concedere l'accesso alla chiave in stateStoreResources in base alle indicazioni seguenti.

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 sezione stateStoreResources della configurazione brokerResources del broker MQTT.

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

Portale

Includere la sezione stateStoreResources 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
    ]
  },
]

Interfaccia della riga di comando di Azure

Includere la sezione stateStoreResources 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
    ]
  },
]

Bicipite

In Bicep, includere la sezione stateStoreResources 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 sezione stateStoreResources 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 campo method 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, del e vdel.

Il campo keyType specifica il tipo di corrispondenza delle chiavi:

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

Il campo keys specifica le chiavi che devono corrispondere. È possibile specificare le chiavi come modelli 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}/*

Di seguito è riportato 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}/sensor/*"
        ]
      },
      {
        "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"
        ]
      }
    ]
  }
]

Interfaccia della riga di comando di Azure

In questo esempio si supponga che un file di configurazione denominato state-store-authz-policy.json nella home directory dell'utente. Nelle regole di autorizzazione broker per i criteri di autorizzazione, aggiungere una configurazione simile:

{
  "authorizationPolicies": {
    "cache": "Enabled",
    "rules": [
      {
        "brokerResources": [
          {
            "clientIds": [
              "{principal.attributes.building}*"
            ],
            "method": "Connect"
          },
          {
            "method": "Publish",
            "topics": [
              "sensors/{principal.attributes.building}/{principal.clientId}/sensor/*"
            ]
          },
          {
            "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"
            ]
          }
        ]
      }
    ]
  }
}

Un comando di esempio per creare un nuovo criterio di autorizzazione denominato state-store-authz-policy è:

az iot ops broker authz apply --resource-group myResourceGroupName --instance myAioInstanceName --broker default --name my-authz-policy --config-file ~/state-store-authz-policy.json

Bicipite

Per modificare un criterio di autorizzazione, creare un file .bicep con il contenuto seguente. Aggiornare le impostazioni in base alle esigenze e sostituire i valori segnaposto, ad esempio <AIO_INSTANCE_NAME>, 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: [
                '/sensor/{principal.username}'
                '/sensor/{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

Comportamento di memorizzazione nella cache

Per ridurre il sovraccarico di autorizzazione negli argomenti con velocità effettiva elevata, abilitare la memorizzazione nella cache in memoria con authorizationPolicies.cache: Enabled.

• Le decisioni vengono memorizzate nella cache per tupla di client, azione e risorsa. Le operazioni ripetute raggiungono la cache.
• Le risorse a variabile elevata (ad esempio, segmenti di argomenti univoci per messaggio) abbassano la frequenza di riscontri nella cache.
• La cache aumenta con il numero di tuple univoche. Monitorare la memoria per modelli di abbandono molto elevati.

Disabilitare l'autorizzazione

Portale

1. Nel portale di Azure passare all'istanza di Operazioni IoT.
2. In Componenti, selezionare Broker MQTT.
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 dell'autorizzazione.

Interfaccia della riga di comando di Azure

Usare il comando az iot ops broker listener port add per disabilitare l'autorizzazione per una porta. Per disabilitare l'autenticazione, non includere il --authz-ref parametro .

az iot ops broker listener port add --resource-group <ResourceGroupName> --instance <AioInstanceName> --broker default --listener <ListenerName> --port <ListenerServicePort>

Nell'esempio seguente viene disabilitata l'autorizzazione per la porta 8884 nel listener denominato aio-broker-loadbalancer:

az iot ops broker listener port add --resource-group myResourceGroupName --instance myAioInstanceName --broker default --listener aio-broker-loadbalancer --authn-ref default --port 8884

Bicipite

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.

Risoluzione dei problemi

Convalidare le regole

1. Esaminare BrokerAuthorization YAML/JSON per individuare i problemi di schema.
2. Controllare l'output quando si applica la configurazione; gli errori dello schema vengono segnalati dal server API.
3. Impostare i log dei pod front-end su debug o trace, riavviare i pod ed esaminare le voci contrassegnate con authz che mostrano regole analizzate ed efficaci.

Esempi di log integri (ridotti):

<7>2025-02-10T16:28:31.986Z aio-broker-frontend-0 [mq@311 tid="1" module="authz"] - adding broker config ... and store config ...
<6>2025-02-10T16:28:31.986Z aio-broker-frontend-0 [mq@311 tid="1"] - starting broker authorization engine with basic rules. Cache enabled: true
<7>2025-02-10T16:28:31.987Z aio-broker-frontend-0 [mq@311 tid="1" module="authz"] - set broker authorization engine data: {"rules":[{...}]}

Operazioni broker MQTT

Esempio di pubblicazione negato:

<7>2025-02-10T16:32:19.398Z aio-broker-frontend-0 [mq@311 tid="15" module="authz"] - checking authorization for {"action":"publish","clientId":"test-publisher","topic":"test"}
<7>2025-02-10T16:32:19.411Z aio-broker-frontend-0 [mq@311 tid="15" module="authz"] - publish from client 'test-publisher' was denied ... reason_code: NotAuthorized

Operazioni di archivio stati

Esempio di recupero negato:

<7>2025-02-10T16:41:31.314Z aio-broker-frontend-0 [mq@311 tid="8" module="authz"] - checking authorization for {"action":"get","clientId":"statestore-cli","key":"dGVzdA=="}
<7>2025-02-10T16:41:31.322Z aio-broker-frontend-0 [mq@311 tid="8" module="authz"] - cached new authorization result ...: Denied("no rule matched")

Passaggi successivi

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