カスタム Webhook 認証を使用して MQTT ブローカーで認証を行う

この記事では、Webhook または Azure 関数を使って Azure Event Grid 名前空間で認証を行う方法について説明します。

Webhook 認証を使うと、外部 HTTP エンドポイント (Webhook または関数) でメッセージキューテレメトリ転送 (MQTT) 接続の認証を動的に行うことができます。この方法では、Microsoft Entra ID の JSON Web Token 検証を使って安全なアクセスを実現します。

クライアントが接続を試みると、ブローカーは、Shared Access Signature トークン、ユーザー名、パスワードなどの資格情報を検証したり、証明書失効リストのチェックを実行したりする、ユーザー定義の HTTP エンドポイントを呼び出します。 Webhook は要求を評価し、接続を許可または拒否する決定と、きめ細かな承認のためのオプションのメタデータを返します。このアプローチでは、さまざまなデバイスフリートとユースケースにわたって、柔軟で一元的な認証ポリシーがサポートされます。

[前提条件]

Event Grid 名前空間と、システム割り当てまたはユーザー割り当てのマネージド ID。
外部の Webhook または Azure 関数。
Event Grid 名前空間のマネージド ID に付与された、Azure 関数または Webhook へのアクセス権。

高レベルの手順

名前空間にカスタム Webhook 認証を使用するには、次の手順に従います。

名前空間を作成し、そのサブリソースを構成します。
Event Grid 名前空間でマネージド ID を有効にします。
マネージド ID に Azure 関数または Webhook へのアクセス権を付与します。
Event Grid 名前空間でカスタム Webhook の設定を構成します。
クライアントを Event Grid 名前空間に接続し、webhook または関数を介して認証を受けます。

名前空間を作成し、そのサブリソースを構成する

名前空間を作成してそのサブリソースを構成するには、「クイックスタート: Azure portal を使用して Event Grid 名前空間で MQTT メッセージを発行してサブスクライブする」で説明されている手順のようにします。クライアント ID は提供されたトークンのものを使うので、証明書とクライアントを作成する手順はスキップします。クライアント属性は、クライアントトークンのカスタム要求に基づいています。クライアント属性は、クライアントグループクエリ、トピックテンプレート変数、およびルーティングエンリッチメント構成で使用されます。

Event Grid 名前空間でマネージド ID を有効にする

Event Grid 名前空間でシステム割り当てマネージド ID を有効にするには、次のコマンドを使います。

az eventgrid namespace update --resource-group <resource group name> --name <namespace name> --identity "{type:systemassigned}"

Azure portal を使ってシステムおよびユーザー割り当ての ID を構成する方法については、「Event Grid 名前空間のマネージド ID の有効化」をご覧ください。

マネージド ID に関数または Webhook への適切なアクセス権を付与する

Event Grid 名前空間のマネージド ID に、ターゲットの Azure 関数または webhook への適切なアクセス権を付与します。

Azure 関数用のカスタム認証の設定は、次の手順に従って行います。

Microsoft Entra アプリを作成する

Microsoft Entra ID で Microsoft Entra アプリを作成します。
アプリの [概要] ページで、[アプリケーション (クライアント) ID] の値を記録しておきます。
左側のメニューで [API の公開] を選びます。 [アプリケーション ID URI] の横にある [追加] を選びます。
[アプリケーション ID の URI の編集] ペインで [アプリケーション ID の URI] の値を記録してから、[保存] を選びます。

Azure 関数の認証を設定する

Azure portal から作成された Basic Azure 関数がある場合は、認証を設定し、マネージド ID を使って作成された Microsoft Entra ID トークンを検証します。

Azure Functions アプリに移動します。
左側のメニューで [ 認証] を選択し、[ ID プロバイダーの追加] を選択します。
[ID プロバイダーの追加] ページで、[ID プロバイダー] のドロップダウンリストから [Microsoft] を選びます。
[アプリの登録] セクションで、次のプロパティの値を指定します。
1. [アプリケーション (クライアント) ID]: 前に記録した Microsoft Entra アプリのクライアント ID を入力します。
2. [発行者 URL]: https://login.microsoftonline.com/<tenantid>/v2.0 の形式で発行者 URL を追加します。
[許可されるトークン対象ユーザー] に、前に記録した Microsoft Entra アプリのアプリケーション ID の URI の値を追加します。
[追加のチェック] セクションの [クライアントアプリケーション開発] で、[特定のクライアントアプリケーションからの要求を許可する] を選びます。
[許可されたクライアントアプリケーション] ペインで、トークンの生成に使われるシステム割り当てマネージド ID のクライアント ID を入力します。この ID は、Microsoft Entra ID リソースのエンタープライズアプリで確認できます。
特定の要件に基づいて他の設定を選択した後、[追加] を選びます。

次に、Microsoft Entra ID トークンを生成して使用します。

マネージド ID と、リソースとしてアプリケーション ID の URI を使って、Microsoft Entra ID トークンを生成します。
このトークンを使用して、要求ヘッダーに含めることで Azure 関数を呼び出します。

Event Grid 名前空間でカスタム webhook 認証設定を構成する

Azure portal と Azure CLI を使って、Event Grid 名前空間でカスタム Webhook 認証の設定を構成します。最初に名前空間を作成してから、それを更新します。

Azure portal を使用する

Azure portal で Event Grid 名前空間に移動します。
[Event Grid 名前空間] ページで、左側のメニューの [構成] を選択します。
[カスタム Webhook 認証] セクションで、次のプロパティの値を指定します。
1. [マネージド ID の種類]: [ユーザー割り当て] を選びます。
2. [Webhook URL]: Event Grid サービスが指定されたマネージド ID を使って認証された Webhook 要求を送信する URL エンドポイントの値を入力します。
3. [トークン対象ユーザー URI]: 配信要求にベアラートークンとして含めるアクセストークンを取得するための Microsoft Entra アプリケーション ID または URI の値を入力します。
4. [Microsoft Entra ID テナント ID]: 認証された Webhook 配信のベアラートークンを取得するために使われる Microsoft Entra テナント ID の値を入力します。
を選択してを適用します。

Azure CLI の使用

カスタム Webhook 認証の構成で名前空間を更新するには、次のコマンドを使います。

az eventgrid namespace update \ 
    --resource-group <resource-group-name> \ 
    --name <namespace-name> \ 
    --api-version 2025-04-01-preview \ 
    --identity-type UserAssigned \ 
    --identity-user-assigned-identities "/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX={}" \ 
    --set properties.isZoneRedundant=true \ 
        properties.topicSpacesConfiguration.state=Enabled \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.type=UserAssigned \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.identity.userAssignedIdentity="/subscriptions/XXXXXXXXXXX/resourcegroups/XXXXXXXXXXX/providers/Microsoft.ManagedIdentity/userAssignedIdentities/XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.endpointUrl="https://XXXXXXXXXXX" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryApplicationIdOrUri="api://XXXXXXXXXXX/.default" \ 
        properties.topicSpacesConfiguration.clientAuthentication.webHookAuthentication.azureActiveDirectoryTenantId="XXXXXXXXXXX"

<NAMESPACE_NAME> と <RESOURCE_GROUP_NAME> は、実際の値に置き換えます。サブスクリプション、リソースグループ、ID、アプリ ID、URL、テナント ID のプレースホルダーに入力します。 Event Grid MQTT ブローカーに対する Webhook ベースの認証のパフォーマンスと信頼性を高めるため、Webhook エンドポイントで HTTP/2 のサポートを有効にすることを強くお勧めします。

Webhook API の詳細

要求ヘッダー

Authorization: ベアラートークン

トークンは、Webhook を呼び出すために構成されたマネージド ID の Microsoft Entra トークンです。

要求ペイロード

{
    "clientId": "<string>",
    "userName": "<string>",
    "password": "<base64 encoded bytes>",
    "authenticationMethod": "<string>",
    "authenticationData": "<base64 encoded bytes>",
    "clientCertificate": "<certificate in PEM format>",
    "clientCertificateChain": "<certificates from chain in PEM format>"
}

ペイロードフィールドの説明

フィールド	必須/任意	説明
`clientId`	必須	MQTT CONNECT パケットからのクライアント ID。
`userName`	オプション	MQTT CONNECT パケットからのユーザー名。
`password`	オプション	Base64 でエンコードされた MQTT CONNECT パケットからのパスワード。
`authenticationMethod`	オプション	MQTT CONNECT パケットからの認証方法 (MQTT5 のみ)。
`authenticationData`	オプション	Base64 でエンコードされた MQTT CONNECT パケットからの認証データ (MQTT5 のみ)。
`clientCertificate`	オプション	PEM 形式のクライアント証明書。
`clientCertificateChain`	オプション	クライアント証明書から証明機関証明書へのチェーンを構築するために必要な、クライアントによって提供された他の証明書。
`userProperties`	オプション	CONNECT パケットからのユーザープロパティ (MQTT5 のみ)。

応答ペイロード:

成功応答

HTTP/1.1 200 OK 
Content-Type: application/json 

{ 
    "decision": "allow", 
    "clientAuthenticationName": "<string>", 
    "attributes": { 
        "attr": "<int/string/array_of_strings>", 
        ... 
    }, 
    "expiration": "<unix time format>" 
}

拒否された応答

HTTP/1.1 400 Bad Request 
Content-Type: application/json 

{ 
    "decision": "deny", 
    "errorReason": "<string>" 
}

応答フィールドの説明

フィールド	説明
`decision` (必須)	認証の決定は `allow` または `deny` です。
`clientAuthenticationName`	クライアント認証名 (ID 名)。 (`decision` が `allow` に設定されている場合は必須。)
`attributes`	属性を持つディクショナリ。キーは属性名で、値は int/string/array です。 (`decision` が `allow` に設定されている場合は省略可能。)
`expiration`	Unix 時刻形式の有効期限。 (`decision` が `allow` に設定されている場合は省略可能。)
`errorReason`	`decision` が `deny` に設定されている場合はエラーメッセージ。このエラーはログに記録されます。 (`decision` が `deny` に設定されている場合は省略可能。)

サポートされている属性の型の例

"num_attr_pos": 1, 
"num_attr_neg": -1, 
"str_attr": "str_value", 
"str_list_attr": [ 
    "str_value_1", 
    "str_value_2" 
]

すべての正しいデータ型 (<int32/string/array_of_strings> に適合する数値) が属性として使われます。この例では、num_attr_pos、num_attr_neg、str_attr、str_list_attr の各クレームは正しいデータ型であり、属性として使われます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-04