設定 MQTT 代理授權

重要

此頁面包含使用 Kubernetes 部署指令清單來管理 Azure IoT Operations 元件的指示，其處於預覽狀態。 這項功能隨附 數個限制，不應用於生產工作負載。

請參閱 Microsoft Azure 預覽版增補使用規定，以了解適用於 Azure 功能 (搶鮮版 (Beta)、預覽版，或尚未正式發行的版本) 的法律條款。

授權原則會決定用戶端可以在訊息代理程式上執行的動作，例如連線、發佈或訂閱主題。 將 MQTT 訊息代理程式設定為搭配 BrokerAuthorization 資源使用一或多個授權原則。 每個 BrokerAuthorization 資源都包含一份規則清單，這些規則會指定授權原則的主體和資源。

將 BrokerAuthorization 連結至 BrokerListener

若要將 BrokerListener 資源連結至 BrokerAuthorization 資源，請在 BrokerListener 資源的設定中ports指定 authorizationRef 字段。 類似於 BrokerAuthentication，BrokerAuthorization 資源可以連結至多個 BrokerListener 埠。 授權原則會套用至所有連結的接聽程式埠。 與 BrokerAuthentication 相比，有一個主要差異：

重要

若要將 BrokerAuthorization 設定套用至接聽程式埠，至少必須有一個 BrokerAuthentication 資源連結至該接聽程式埠。

若要深入瞭解 BrokerListener，請參閱 BrokerListener 資源。

授權規則

若要設定授權，請在 Kubernetes 叢集中建立 BrokerAuthorization 資源。 下列各節提供如何為使用使用者名稱、屬性、X.509 憑證和 Kubernetes 服務帳戶令牌 （SAT） 的用戶端設定授權的範例。 如需可用設定的清單，請參閱 Broker 授權 API 參考。

下列範例示範如何使用使用者名稱和屬性來建立 BrokerAuthorization 資源。

入口網站

1. 在 Azure 入口網站 中，移至您的 IoT 作業實例。

2. 在 [元件] 底下，選取 [MQTT Broker]。

3. 選取 [授權] 索引標籤。

4. 選取 [建立授權原則]，選擇現有的驗證原則或建立新的 驗證原則。

   

Bicep

若要編輯授權原則，請使用下列內容建立 .bicep 檔案。 視需要更新設定，並將佔位元值 <AIO_INSTANCE_NAME> 取代為您自己的值。

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

使用 Azure CLI 部署 Bicep 檔案：

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

Kubernetes （預覽）

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

若要建立此 BrokerAuthorization 資源，請將 YAML 資訊清單套用至 Kubernetes 叢集。

此訊息代理程式授權可讓用戶端使用用戶端 temperature-sensor 識別碼或 humidity-sensor，或具有 屬性 organization的用戶端，其值為 contoso 和 city，以及值 ，以執行下列動作 seattle：

• 連線到訊息代理程式。
• 將訊息發佈至以其用戶端標識碼和組織限定範圍的遙測主題。 例如：
  • temperature-sensor 可以發佈至 /telemetry/temperature-sensor 和 /telemetry/contoso。
  • humidity-sensor 可以發佈至 /telemetry/humidity-sensor 和 /telemetry/contoso。
  • some-other-username 可以發佈至 /telemetry/contoso。
• /commands/訂閱其組織範圍的主題。 例如：
  • temperature-sensor 可以訂閱 /commands/contoso。
  • some-other-username 可以訂閱 /commands/contoso。

使用使用者名稱進行授權

若要使用 MQTT 使用者名稱進行授權，請將它們指定為 下的 principals.usernames陣列。 根據驗證方法，使用者名稱可能無法驗證：

• Kubernetes SAT：使用者名稱不應該用於授權，因為它未針對具有增強式驗證的 MQTTv5 進行驗證。
• X.509：用戶名稱符合憑證中的一般名稱 （CN），並可用於授權規則。
• 自訂：只有在自定義驗證驗證驗證用戶名稱時，使用者名稱才應該用於授權規則。

若要防止安全性問題，請只在可以驗證時，才使用 MQTT 使用者名稱進行訊息代理程式授權。

根據客戶端識別元進一步限制存取

principals因為欄位是邏輯OR的 ，因此您可以藉由將欄位新增clientIds至 brokerResources 欄位，根據用戶端識別元進一步限制存取。 例如，若要允許具有以建置編號開頭的用戶端連線和發佈遙測至其建置範圍的主題，請使用下列組態：

入口網站

在授權原則的訊息代理程式授權規則中，使用下列設定：

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

若要編輯授權原則，請使用下列內容建立 .bicep 檔案。 視需要更新設定，並將佔位元值 <AIO_INSTANCE_NAME> 取代為您自己的值。

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

使用 Azure CLI 部署 Bicep 檔案：

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

Kubernetes （預覽）

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"

在此，如果未clientIds在 方法下Connect設定 ，只要用戶端標識元設定為 building22 或 building23屬性，任何用戶端標識符的用戶端就可以連線building。 當您新增 clientIds 欄位時，只有具有開頭 building22 為 或 building23 可以連線之用戶端標識碼的用戶端。 此指定可確保用戶端具有正確的屬性，且用戶端標識元符合預期的模式。

授權使用 X.509 驗證的用戶端

您可以授權使用 X.509 憑證進行驗證 的用戶端，以根據其憑證上存在的 X.509 屬性或鏈結上的發行憑證存取資源。

使用屬性

若要根據來自用戶端憑證、根 CA 或中繼 CA 的屬性來建立規則，請在 BrokerAuthorization 資源中定義 X.509 屬性。 如需詳細資訊，請參閱憑證屬性。

使用用戶端憑證主題一般名稱作為使用者名稱

若要根據 客戶端 憑證主體 CN 建立授權原則，請根據 CN 建立規則。

例如，如果用戶端具有具有主體 CN = smart-lock的憑證，則其使用者名稱為 smart-lock。 從該處，依正常方式建立授權原則。

授權使用 Kubernetes 服務帳戶令牌的用戶端

SAT 的授權屬性會設定為服務帳戶批注的一部分。 例如，若要使用 值authz-sat新增名為 group 的授權屬性，請執行 命令：

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

屬性註釋必須以 aio-broker-auth/ 開頭，才能區別於其他註釋。

由於應用程式具有稱為 authz-sat的授權屬性，因此不需要提供 clientId 或 username 值。 對應的 BrokerAuthorization 資源會使用此屬性作為主體，例如：

入口網站

在授權原則的訊息代理程式授權規則中，使用下列設定：

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

Bicep

若要編輯授權原則，請使用下列內容建立 .bicep 檔案。 視需要更新設定，並將佔位元值 <AIO_INSTANCE_NAME> 取代為您自己的值。

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

使用 Azure CLI 部署 Bicep 檔案：

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

Kubernetes （預覽）

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"

若要深入了解範例，請參閱 使用 Dapr 用戶端設定授權原則。

狀態存放區

MQTT 訊息代理程式提供 狀態存放區 ，用戶端可用來儲存狀態。 您也可以將狀態存放區設定為高可用性。

若要為使用狀態存放區的用戶端設定授權，請提供下列許可權：

• 發佈至系統金鑰值存放區 $services/statestore/_any_/command/invoke/request 主題的權限
• 訂閱回應主題的權限 (在初始發佈期間設定為參數) <response_topic>/#

狀態存放區金鑰

狀態存放區是透過主題 statestore/v1/FA9AE35F-2F64-47CD-9BFF-08E2B32A0FE8/command/invoke上的 MQTT 訊息代理程式存取。 由於用戶端可以存取主題，因此您可以在 MQTT 訊息代理程式brokerResources組態的 stateStoreResources 區段下指定金鑰和存取層級。

區 stateStoreResources 段格式包含存取層級、模式指標和模式。

入口網站

在授權原則的規則中包含 區 stateStoreResources 段。

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

Bicep

在 Bicep 中，在您的授權原則中包含 區 stateStoreResources 段。

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

在您的自定義資源定義中，在您的授權原則中包含 區 stateStoreResources 段。

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

欄位 method 會指定存取層級：

• 使用 指定 read讀取許可權。 使用 指定 write寫入存取權。 使用 指定 readwrite讀取和寫入存取權。
• 需要存取層級。
• 讀取存取層級表示 和keynotify的get動作。
• 寫入存取層級表示、 del和 vdel的set動作。

欄位 keyType 會指定索引鍵比對的類型：

• pattern：用於 glob 樣式模式比對。
• string：用來執行完全相符的動作，例如，當索引鍵包含可能以模式 （*、 、 ?[0-9]） 比對的字元時。
• binary：用來比對二進位索引鍵。

欄位 keys 會指定要比對的索引鍵。 您可以將索引鍵指定為 glob 樣式模式、令牌替代或確切字串。

• Glob 樣式範例：

  • colors/*：“colors/” 前置詞下的所有索引鍵
  • number[0-9]：任何從 “number0” 到 “number9” 的索引鍵
  • char?：前置詞 “char” 和單一數字後綴的任何索引鍵，例如 “charA”
  • *：所有金鑰的完整存取權

• 狀態存放區金鑰也支援金鑰類型為 pattern ，且大括號保留供此用途使用時，令牌替代。 權杖替代範例：

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

以下是如何撰寫狀態存放區資源的範例。

入口網站

在授權原則的訊息代理程式授權規則中，新增類似的設定：

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

若要編輯授權原則，請使用下列內容建立 .bicep 檔案。 視需要更新設定，並將佔位元值 <AIO_INSTANCE_NAME> 取代為您自己的值。

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

使用 Azure CLI 部署 Bicep 檔案：

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.

更新授權

您可以在運行時間更新訊息代理程式授權資源，而不需重新啟動。 在原則更新時連線的所有用戶端都會中斷連線。 變更原則類型也同樣支援。

kubectl edit brokerauthorization my-authz-policies

停用授權

入口網站

1. 在 Azure 入口網站 中，移至您的 IoT 作業實例。
2. 在 [元件] 底下，選取 [MQTT Broker]。
3. 從清單中選取您要編輯的訊息代理程式接聽程式。
4. 在您要停用授權的埠上，選取 [授權] 下拉式清單中的 [無 ]。

Bicep

若要停用授權，請在 BrokerListener 資源的設定中ports省略authorizationRef。

Kubernetes （預覽）

若要停用授權，請在 BrokerListener 資源的設定中ports省略authorizationRef。

MQTT 3.1.1 中未經授權的發佈

使用 MQTT 3.1.1 時，當發佈遭到拒絕時，用戶端會收到 PUBACK，沒有錯誤，因為通訊協定版本不支援傳回錯誤碼。 MQTTv5 會在發布遭到拒絕時傳回具有原因代碼 135（未授權）的 PUBACK。

相關內容

• BrokerListener 資源
• 設定 BrokerListener 的驗證
• 教學課程：TLS、X.509 用戶端驗證和屬性型訪問控制 （ABAC） 授權