Mengonfigurasi otorisasi broker MQTT

Penting

Halaman ini mencakup instruksi pengelolaan komponen Azure IoT Operations menggunakan manifes penyebaran Kubernetes, yang sedang dalam pratinjau. Fitur ini disediakan dengan beberapa batasan, dan tidak boleh digunakan untuk beban kerja produksi.

Lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure untuk persyaratan hukum yang berlaku untuk fitur Azure yang dalam versi beta, pratinjau, atau belum dirilis ke ketersediaan umum.

Kebijakan otorisasi menentukan tindakan apa yang dapat dilakukan klien pada broker, seperti menyambungkan, menerbitkan, atau berlangganan topik. Konfigurasikan broker MQTT untuk menggunakan satu atau beberapa kebijakan otorisasi dengan sumber daya BrokerAuthorization. Setiap sumber daya BrokerAuthorization berisi daftar aturan yang menentukan prinsipal dan sumber daya untuk kebijakan otorisasi.

Bagaimana aturan dievaluasi

• Kebijakan hanya diizinkan. Jika tidak ada aturan yang secara eksplisit mengizinkan tindakan pada sumber daya untuk prinsipal, tindakan ditolak.
• Aturan didefinisikan oleh tiga faktor: prinsipal (aktor), tindakan (Sambungkan/Terbitkan/Berlangganan atau operasi penyimpanan status), dan sumber daya (topik atau kunci).
• Prinsipal dalam aturan dicocokkan dengan OR logis. Misalnya, kecocokan nama pengguna, clientId, atau atribut yang tercantum memberikan akses ke sumber daya dalam aturan.

Penggantian token dan kartubebas

• Untuk topik dan kunci, Anda dapat menggunakan substitusi token untuk membangun aturan yang beradaptasi per klien: {principal.username}, , {principal.clientId}dan {principal.attributes.<attributeName>}.
• Wildcard + topik MQTT dan # didukung di brokerResources.topics.
• Saat menggunakan substitusi token dalam topik, token harus menjadi satu-satunya teks di segmen jalurnya. Misalnya, clients/{principal.clientId}/# valid, tetapi client-{principal.clientId}/# tidak.
• Tindakan sambungkan tidak boleh menyertakan topik.

Tautkan BrokerAuthorization ke BrokerListener

Untuk menautkan sumber daya BrokerListener ke sumber daya BrokerAuthorization, tentukan authorizationRef bidang dalam ports pengaturan sumber daya BrokerListener. Mirip dengan BrokerAuthentication, sumber daya BrokerAuthorization dapat ditautkan ke beberapa port BrokerListener. Kebijakan otorisasi berlaku untuk semua port pendengar yang ditautkan. Ada satu perbedaan utama dibandingkan dengan BrokerAuthentication:

Penting

Agar konfigurasi BrokerAuthorization berlaku untuk port listener, setidaknya satu sumber daya BrokerAuthentication juga harus ditautkan ke port pendengar tersebut.

Untuk mempelajari selengkapnya tentang BrokerListener, lihat Sumber daya BrokerListener.

Aturan Otorisasi

Untuk mengonfigurasi otorisasi, buat sumber daya BrokerAuthorization di kluster Kubernetes Anda. Bagian berikut memberikan contoh cara mengonfigurasi otorisasi untuk klien yang menggunakan nama pengguna, atribut, sertifikat X.509, dan token akun layanan Kubernetes (SAT). Untuk daftar pengaturan yang tersedia, lihat referensi API Otorisasi Broker .

Contoh berikut menunjukkan cara membuat sumber daya BrokerAuthorization dengan menggunakan nama pengguna dan atribut.

Portal

1. Di portal Azure, buka instans Operasi IoT Anda.

2. Di bawah Komponen, pilih MQTT Broker.

3. Pilih tab Otorisasi .

4. Pilih kebijakan autentikasi yang sudah ada atau buat yang baru dengan memilih Buat kebijakan otorisasi.

   

Azure CLI

Gunakan perintah az iot ops broker authz apply untuk membuat atau mengubah kebijakan otorisasi.

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

Dalam contoh ini, asumsikan file konfigurasi bernama my-authz-policy.json dengan konten berikut yang disimpan di direktori beranda pengguna:

{
  "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": []
        }
      }
    ]
  }
}

Contoh perintah untuk membuat kebijakan otorisasi baru bernama 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

Bisep

Untuk mengedit kebijakan otorisasi, buat .bicep file dengan konten berikut. Perbarui pengaturan sesuai kebutuhan, dan ganti nilai tempat penampung seperti <AIO_INSTANCE_NAME> dengan nilai Anda sendiri.

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

Sebarkan file Bicep dengan menggunakan Azure CLI:

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

Kubernetes (pratinjau)

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

Untuk membuat sumber daya BrokerAuthorization ini, terapkan manifes YAML ke kluster Kubernetes Anda.

Otorisasi broker ini memungkinkan klien dengan ID temperature-sensor klien atau , atau humidity-sensorklien dengan atribut organization, dengan nilai contoso dan city, dan dengan nilai seattle, untuk:

• Sambungkan ke broker.
• Publikasikan pesan ke topik yang dibatasi oleh ID klien dan organisasi mereka. Misalnya:
  • temperature-sensor dapat menerbitkan ke /sensor/temperature-sensor dan /sensor/contoso.
  • humidity-sensor dapat menerbitkan ke /sensor/humidity-sensor dan /sensor/contoso.
  • some-other-username dapat menerbitkan ke /sensor/contoso.
• Berlangganan /commands/ topik yang dilingkup dengan organisasi mereka. Misalnya:
  • temperature-sensor dapat berlangganan ke /commands/contoso.
  • some-other-username dapat berlangganan ke /commands/contoso.

Menggunakan nama pengguna untuk otorisasi

Untuk menggunakan nama pengguna MQTT untuk otorisasi, tentukan sebagai array di bawah principals.usernames. Bergantung pada metode autentikasi, nama pengguna mungkin tidak diverifikasi:

• Kubernetes SAT: Nama pengguna tidak boleh digunakan untuk otorisasi karena tidak diverifikasi untuk MQTTv5 dengan autentikasi yang ditingkatkan.
• X.509: Nama pengguna cocok dengan nama umum (CN) dari sertifikat dan dapat digunakan untuk aturan otorisasi.
• Kustom: Nama pengguna hanya boleh digunakan untuk aturan otorisasi jika autentikasi kustom memvalidasi nama pengguna.

Untuk mencegah masalah keamanan, gunakan nama pengguna MQTT untuk otorisasi broker hanya ketika dapat diverifikasi.

Petunjuk / Saran

Untuk mengharuskan nama pengguna MQTT cocok dengan ID klien, gunakan substitusi token:

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

Membatasi akses lebih lanjut berdasarkan ID klien

principals Karena bidang adalah logis OR, Anda dapat membatasi akses lebih lanjut berdasarkan ID klien dengan menambahkan clientIds bidang ke brokerResources bidang . Misalnya, untuk memungkinkan klien dengan ID klien yang dimulai dengan nomor gedung mereka dapat terhubung dan menerbitkan ke topik dengan cakupan gedung mereka, gunakan konfigurasi berikut:

Portal

Dalam aturan otorisasi broker untuk kebijakan otorisasi Anda, gunakan konfigurasi berikut:

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

Azure CLI

Gunakan perintah az iot ops broker authz apply untuk membuat atau mengubah kebijakan otorisasi.

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

Dalam aturan otorisasi broker untuk kebijakan otorisasi Anda, buat file konfigurasi bernama client-id-policy.json dengan konfigurasi berikut yang disimpan di direktori beranda pengguna:

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

Contoh perintah untuk membuat kebijakan otorisasi baru bernama 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

Bisep

Untuk mengedit kebijakan otorisasi, buat .bicep file dengan konten berikut. Perbarui pengaturan sesuai kebutuhan, dan ganti nilai tempat penampung seperti <AIO_INSTANCE_NAME> dengan nilai Anda sendiri.

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

Sebarkan file Bicep dengan menggunakan Azure CLI:

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

Kubernetes (pratinjau)

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"

Di sini, jika clientIds tidak diatur di bawah Connect metode , klien dengan ID klien apa pun dapat terhubung selama atribut diatur building ke building22 atau building23. Saat Anda menambahkan clientIds bidang, hanya klien dengan ID klien yang dimulai dengan building22 atau building23 dapat tersambung. Penunjukan ini memastikan bahwa klien memiliki atribut yang benar dan BAHWA ID klien cocok dengan pola yang diharapkan.

Mengotorisasi klien yang menggunakan autentikasi X.509

Anda dapat mengotorisasi klien yang menggunakan sertifikat X.509 untuk autentikasi untuk mengakses sumber daya berdasarkan atribut X.509 yang ada pada sertifikat mereka atau sertifikat penerbit mereka hingga ke tingkat atas dalam rantai.

Atribut file

Untuk membuat aturan berdasarkan properti dari sertifikat klien, CA akarnya, atau CA menengah, tentukan atribut X.509 di sumber daya BrokerAuthorization. Untuk informasi selengkapnya, lihat Atribut sertifikat.

Dengan nama umum subjek sertifikat klien sebagai nama pengguna

Untuk membuat kebijakan otorisasi berdasarkan CN subjek sertifikat klien saja, buat aturan berdasarkan CN.

Misalnya, jika klien memiliki sertifikat dengan subjek CN = smart-lock, nama penggunanya adalah smart-lock. Setelah itu, buat kebijakan otorisasi seperti biasa.

Mengotorisasi klien yang menggunakan token akun layanan Kubernetes

Atribut otorisasi untuk SAT ditetapkan sebagai bagian dari anotasi akun layanan. Misalnya, untuk menambahkan atribut otorisasi bernama group dengan nilai authz-sat, jalankan perintah :

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

Anotasi atribut harus dimulai dengan aio-broker-auth/ untuk membedakannya dari anotasi lain.

Karena aplikasi memiliki atribut otorisasi yang disebut authz-sat, tidak perlu memberikan clientId nilai atau username . Sumber daya BrokerAuthorization yang sesuai menggunakan atribut ini sebagai prinsipal, misalnya:

Portal

Dalam aturan otorisasi broker untuk kebijakan otorisasi Anda, gunakan konfigurasi berikut:

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

Azure CLI

Gunakan perintah az iot ops broker authz apply untuk membuat atau mengubah kebijakan otorisasi.

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

Dalam contoh ini, asumsikan file konfigurasi bernama my-authz-policy.json dengan konten berikut yang disimpan di direktori beranda pengguna:

{
  "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": []
        }
      }
    ]
  }
}

Contoh perintah untuk membuat kebijakan otorisasi baru bernama 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

Bisep

Untuk mengedit kebijakan otorisasi, buat .bicep file dengan konten berikut. Perbarui pengaturan sesuai kebutuhan, dan ganti nilai tempat penampung seperti <AIO_INSTANCE_NAME> dengan nilai Anda sendiri.

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

Sebarkan file Bicep dengan menggunakan Azure CLI:

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

Kubernetes (pratinjau)

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"

Untuk mempelajari selengkapnya dengan contoh, lihat Menyiapkan Kebijakan Otorisasi dengan Klien Dapr.

Penyimpanan status

Broker MQTT menyediakan penyimpanan status yang dapat digunakan klien untuk menyimpan status. Anda juga dapat mengonfigurasi penyimpanan status agar sangat tersedia.

Untuk menyiapkan otorisasi untuk klien yang menggunakan penyimpanan status, berikan izin untuk topik protokol dan kunci:

• Terbitkan permintaan ke: statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke.
• Berlangganan topik respons yang Anda tetapkan di publikasikan, umumnya: clients/{principal.clientId}/services/statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke/response/#.
• Berikan akses stateStoreResources kunci sesuai panduan di bawah ini.

Kunci penyimpanan status

Penyimpanan status diakses melalui broker MQTT tentang topik statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke. Karena klien memiliki akses ke topik ini, Anda dapat menentukan kunci dan tingkat akses di bawah stateStoreResources bagian konfigurasi broker brokerResources MQTT.

stateStoreResources Format bagian terdiri dari tingkat akses, indikator pola, dan pola.

Portal

Sertakan bagian stateStoreResources dalam aturan untuk kebijakan otorisasi Anda.

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

Azure CLI

Sertakan bagian stateStoreResources dalam aturan untuk kebijakan otorisasi Anda.

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

Bisep

Di Bicep, sertakan bagian stateStoreResources dalam kebijakan otorisasi Anda.

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

Dalam definisi sumber daya kustom Anda, sertakan bagian stateStoreResources dalam kebijakan otorisasi Anda.

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

Bidang method menentukan tingkat akses:

• Akses baca ditentukan dengan read. Akses tulis ditentukan dengan write. Akses baca dan tulis ditentukan dengan readwrite.
• Tingkat akses diperlukan.
• Tingkat akses baca menyiratkan tindakan get dan keynotify.
• Tingkat akses tulis menyiratkan tindakan set, , deldan vdel.

Bidang keyType menentukan jenis pencocokan kunci:

• pattern: Digunakan untuk pencocokan pola gaya glob.
• string: Digunakan untuk melakukan kecocokan persis, misalnya, ketika kunci berisi karakter yang mungkin dicocokkan sebagai pola (*, ?, [0-9]).
• binary: Digunakan untuk mencocokkan kunci biner.

Bidang keys menentukan kunci yang cocok. Anda dapat menentukan kunci sebagai pola gaya glob, substitusi token, atau string yang tepat.

• Contoh gaya glob:

  • colors/*: Semua kunci di bawah awalan "warna/"
  • number[0-9]: Kunci apa pun dari "number0" hingga "number9"
  • char?: Kunci apa pun dengan awalan "char" dan akhiran satu digit, seperti "charA"
  • *: Akses penuh ke semua kunci

• Kunci penyimpanan status juga mendukung penggantian token ketika jenis kunci adalah pattern dan kurung kurawal dicadangkan untuk tujuan ini. Contoh penggantian token:

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

Berikut adalah contoh bagaimana Anda dapat menulis sumber daya penyimpanan status Anda.

Portal

Dalam aturan otorisasi broker untuk kebijakan otorisasi Anda, tambahkan konfigurasi serupa:

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

Azure CLI

Dalam contoh ini, asumsikan file konfigurasi bernama state-store-authz-policy.json di direktori beranda pengguna. Dalam aturan otorisasi broker untuk kebijakan otorisasi Anda, tambahkan konfigurasi serupa:

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

Contoh perintah untuk membuat kebijakan otorisasi baru bernama 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

Bisep

Untuk mengedit kebijakan otorisasi, buat .bicep file dengan konten berikut. Perbarui pengaturan sesuai kebutuhan, dan ganti nilai tempat penampung seperti <AIO_INSTANCE_NAME> dengan nilai Anda sendiri.

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

Sebarkan file Bicep dengan menggunakan 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.

Memperbarui otorisasi

Anda dapat memperbarui sumber daya otorisasi broker saat runtime tanpa menghidupkan ulang. Semua klien yang terhubung pada saat pembaruan kebijakan terputus. Mengubah jenis kebijakan juga didukung.

kubectl edit brokerauthorization my-authz-policies

Perilaku penembolokan

Untuk mengurangi overhead otorisasi pada topik throughput tinggi, aktifkan penembolokan dalam memori dengan authorizationPolicies.cache: Enabled.

• Keputusan di-cache per tuple klien, tindakan, dan sumber daya. Operasi berulang mencapai cache.
• Sumber daya yang sangat bervariasi (misalnya, segmen topik unik per pesan) tingkat hit cache yang lebih rendah.
• Cache tumbuh dengan jumlah tuple unik. Pantau memori untuk pola churn yang sangat tinggi.

Menonaktifkan otorisasi

Portal

1. Di portal Azure, buka instans Operasi IoT Anda.
2. Di bawah Komponen, pilih MQTT Broker.
3. Pilih pendengar broker yang ingin Anda edit dari daftar.
4. Pada port tempat Anda ingin menonaktifkan otorisasi, pilih Tidak Ada di menu dropdown otorisasi.

Azure CLI

Gunakan perintah az iot ops broker listener port add untuk menonaktifkan otorisasi untuk port. Untuk menonaktifkan autentikasi, jangan sertakan --authz-ref parameter .

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

Contoh berikut menonaktifkan otorisasi untuk port 8884 ke pendengar bernama 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

Bisep

Untuk menonaktifkan otorisasi, hilangkan authorizationRefports dalam pengaturan sumber daya BrokerListener Anda.

Kubernetes (pratinjau)

Untuk menonaktifkan otorisasi, hilangkan authorizationRefports dalam pengaturan sumber daya BrokerListener Anda.

Publikasi tidak sah di MQTT 3.1.1

Dengan MQTT 3.1.1, ketika penerbitan ditolak, klien menerima PUBACK tanpa kesalahan karena versi protokol tidak mendukung pengembalian kode kesalahan. MQTTv5 mengembalikan PUBACK dengan kode alasan 135 (Tidak diotorisasi) saat penerbitan ditolak.

Troubleshooting

Memvalidasi aturan

1. Tinjau BrokerAuthorization YAML/JSON Anda untuk masalah skema.
2. Periksa output saat menerapkan konfigurasi; kesalahan skema dilaporkan oleh server API.
3. Atur log pod frontend ke debug atau trace, hidupkan ulang pod, dan periksa entri yang ditandai dengan authz yang menunjukkan aturan yang diurai dan efektif.

Contoh log sehat (abridged):

<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":[{...}]}

Operasi broker MQTT

Contoh publikasi yang ditolak:

<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

Operasi penyimpanan status

Ditolak mendapatkan contoh:

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

Langkah selanjutnya

• Sumber daya BrokerListener
• Mengonfigurasi autentikasi untuk BrokerListener
• Tutorial: TLS, autentikasi klien X.509, dan otorisasi kontrol akses berbasis atribut (ABAC)