MQTT ブローカー認可を構成する

[アーティクル]
11/21/2024

重要

このページには、プレビュー段階にある Kubernetes デプロイマニフェストを使用して Azure IoT Operations コンポーネントを管理する手順が含まれます。この機能はいくつかの制限を設けて提供されており、運用環境のワークロードには使用しないでください。

ベータ版、プレビュー版、または一般提供としてまだリリースされていない Azure の機能に適用される法律条項については、「Microsoft Azure プレビューの追加使用条件」を参照してください。

認可ポリシーは、クライアントがブローカーに対して実行できるアクション (トピックへの接続、パブリッシュ、サブスクライブなど) を決定します。 BrokerAuthorization リソースを使用して 1 つまたは複数の認可ポリシーを使用するように MQTT ブローカーを構成します。各 BrokerAuthorization リソースには、認可ポリシーのプリンシパルとリソースを指定する規則のリストが含まれています。

BrokerAuthorization を BrokerListener にリンクする

BrokerListener を BrokerAuthorization リソースにリンクするには、BrokerListener リソースの ports 設定で authorizationRef フィールドを指定します。 BrokerAuthentication と同様に、BrokerAuthorization リソースは複数の BrokerListener ポートにリンクできます。認可ポリシーは、リンクされているすべてのリスナーポートに適用されます。ただし、BrokerAuthentication と比べて 1 つの重要な違いがあります。

重要

BrokerAuthorization の構成をリスナーポートに適用するには、少なくとも 1 つの BrokerAuthentication がそのリスナーポートにリンクされている必要もあります。

BrokerListener について詳しくは、BrokerListener リソースに関する記事をご覧ください。

承認規則

認可を構成するには、Kubernetes クラスターに BrokerAuthorization リソースを作成します。以下のセクションでは、ユーザー名、属性、X.509 証明書、Kubernetes サービスアカウントトークン (SAT) を使用するクライアントの認可を構成する方法の例を示します。使用できる設定の一覧については、Broker Authorization API リファレンスを参照してください。

次の例では、ユーザー名と属性の両方を使って BrokerAuthorization リソースを作成する方法を示します。

Azure portal で、IoT Operations インスタンスに移動します。
[コンポーネント] で、[MQTT ブローカー] を選択します。
承認タブを選択します。
既存の認証ポリシーを選択するか、[Create authorization policy]$認証ポリシーの作成$ を選択して新しく作成します。

承認ポリシーを編集するには、次のコンテンツを含む 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

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 クラスターに適用します。

このブローカー認可を使用すると、クライアント ID が temperature-sensor または humidity-sensor のクライアント、あるいは値が contoso の属性 organization を持つ、および値が seattle の属性 city を持つクライアントが、次の操作を実行できます。

ブローカーに接続する。
クライアント ID と組織をスコープとした telemetry トピックにメッセージを発行する。例:
- 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 ユーザー名は、検証できる場合にのみブローカーの認可に使用します。

クライアント ID に基づいてアクセスをさらに制限する

principals フィールドは論理 OR であるため、clientIds フィールドを brokerResources フィールドに追加すると、クライアント ID に基づいてアクセスをさらに制限できます。たとえば、建物番号で始まるクライアント ID を持つクライアントが建物をスコープとするトピックに接続してテレメトリを発行できるようにするには、次の構成を使います。

承認ポリシーのブローカー認可規則では、次の構成を使用します。

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

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

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 メソッドで設定されなかった場合は、building 属性が building22 または building23 に設定されてさえいれば、どのようなクライアント ID を持つクライアントであっても接続できます。 clientIds フィールドを追加すると、クライアント ID が building22 または building23 で始まるクライアントのみが接続できます。これにより、クライアントが正しい属性を持つことだけでなく、クライアント ID が必要なパターンと一致することが保証されます。

X.509 認証を使用するクライアントを承認する

認証に X.509 証明書を使用するクライアントは、証明書に存在する X.509 プロパティまたはチェーン上の発行元証明書に基づいてリソースへのアクセスの承認を受けることができます。

属性の使用

クライアントの証明書、そのルート CA、または中間 CA のプロパティに基づいてルールを作成するには、BrokerAuthorization リソースで X.509 属性を定義します。詳細については、「証明書の属性」を参照してください。

クライアント証明書のサブジェクト共通名をユーザー名として使用

クライアント証明書のサブジェクト共通名 (CN) のみに基づいて認可ポリシーを作成するには、CN に基づいて規則を作成します。

たとえば、クライアントにサブジェクト CN = smart-lock を持つ証明書がある場合、そのユーザー名は smart-lock になります。その後、通常どおりに認可ポリシーを作成します。

Kubernetes サービスアカウントトークンを使用するクライアントを認可する

SAT の認可属性は、サービスアカウント注釈の一部として設定されます。たとえば、group という名前の認可属性を値 authz-sat で追加するには、次のコマンドを実行します。

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

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

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 で、承認ポリシーに 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'
    ]
  }
]

カスタムリソース定義で、承認ポリシーに 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 で指定されます。
アクセスレベルは必須です。
読み取りアクセスレベルは get と keynotify のアクションを意味します。
書き込みアクセスレベルは、set、del、および vdel のアクションを意味します。

keyType フィールドでは、キーマッチングの種類を指定します。

pattern: glob スタイルのパターンマッチングが使用されます
string: 完全一致が実行されます。パターンとして一致する可能性がある文字 (*、?、[0-9]) がキーに含まれている場合など
binary: バイナリキーに一致します

keys フィールドでは、一致させるキーを指定します。キーは、Glob スタイルパターン、トークン置換、または正確な文字列として指定できます。

Glob スタイルの例:
- colors/*: "colors/" プレフィックスの下にあるすべてのキー
- number[0-9]: "number0" から "number9" までの任意のキー
- char?: プレフィックス "char" と 1 桁のサフィックスを持つ任意のキー ("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"
        ]
      }
    ]
  }
]

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

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

認可を無効にする

Azure portal で、IoT Operations インスタンスに移動します。
[コンポーネント] で、[MQTT ブローカー] を選択します。
編集するブローカーリスナーを一覧から選択します。
承認を無効にするポートで、承認ドロップダウンの [なし] を選択します。

MQTT 3.1.1 での未承認の発行

MQTT 3.1.1 では、発行が拒否されると、このプロトコルバージョンではエラーコードを返すことがサポートされていないため、クライアントはエラーなしで PUBACK を受け取ります。 MQTTv5 では、発行が拒否されると理由コード 135 (未承認) で PUBACK が返されます。

次の方法で共有

MQTT ブローカー認可を構成する

BrokerAuthorization を BrokerListener にリンクする

承認規則

認可にユーザー名を使用する

クライアント ID に基づいてアクセスをさらに制限する

X.509 認証を使用するクライアントを承認する

属性の使用

クライアント証明書のサブジェクト共通名をユーザー名として使用

Kubernetes サービスアカウントトークンを使用するクライアントを認可する

状態ストア

状態ストアキー

認可を更新する

認可を無効にする

MQTT 3.1.1 での未承認の発行

フィードバック

その他のリソース

次の方法で共有

MQTT ブローカー認可を構成する

BrokerAuthorization を BrokerListener にリンクする

承認規則

認可にユーザー名を使用する

クライアント ID に基づいてアクセスをさらに制限する

X.509 認証を使用するクライアントを承認する

属性の使用

クライアント証明書のサブジェクト共通名をユーザー名として使用

Kubernetes サービス アカウント トークンを使用するクライアントを認可する

状態ストア

状態ストア キー

認可を更新する

認可を無効にする

MQTT 3.1.1 での未承認の発行

関連するコンテンツ

フィードバック

その他のリソース

Kubernetes サービスアカウントトークンを使用するクライアントを認可する

状態ストアキー