カスタム 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 の有効化」をご覧ください。

実装

オプション 1: Azure Functions を使用した Webhook の実装 (Microsoft Entra アプリ)

Azure Functions では、 Microsoft.Identity.Web を使用してトークンを自動的に検証する Webhook ロジックをホストできます。トークン発行用のアプリケーション ID URI を持つ Event Grid 呼び出し元トークンを検証するには、Webhook API の Microsoft Entra アプリ登録が必要です。クライアント側 (Event Grid) には既にマネージド ID があります。

長所:

管理するインフラストラクチャがない
組み込みの認証ヘルパー (Microsoft.Identity.Web)
耐久性、拡張性、コスト効率に優れた

関数は、次の操作を実行する必要があります。

Event Grid マネージド ID からの呼び出し元トークンを検証する
クライアント Json Web トークンの検証 (JWT)
許可または拒否 JSON を返す

オプション 2: 外部 HTTPS エンドポイントの実装

この実装には、Microsoft Entra ID JWT 検証と Microsoft.IdentityModel ライブラリを使用して、任意の外部 HTTPS エンドポイント (任意のクラウド、任意のバックエンド) を指定できます。

任意のランタイムを使用します:.NET/Node/Java/Python。

主な要件:

HTTPS である必要があります
呼び出し元 JWT を検証する必要があります
デバイス JWT を検証する必要があります
タイムアウト以内に応答する必要があります (最大 5 秒を推奨)

マネージド 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 の詳細

要求ヘッダー

Azure Event Grid は、要求内の次のヘッダーを webhook に送信します。

**Authorization**: Bearer token

トークンは、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`	オプション	クライアント証明書から証明機関証明書へのチェーンを構築するために必要な、クライアントによって提供された他の証明書。

応答ペイロード:

成功応答

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 200 Bad Request 
Content-Type: application/json 

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

エラーコード:

認証の結果	関数の応答	Event Grid MQTT 理由コード
明示的な承認拒否	`"decision": "deny"`	承認されていません
無効なトークンまたは期限切れのトークン	`"decision": "deny"`	承認されていません
関数のタイムアウト	N/A	サーバーを使用できない
関数の例外/クラッシュ	N/A	サーバーを使用できない
一時的なプラットフォームの障害	N/A	サーバーを使用できない
内部ブローカー処理エラー	N/A	サーバーを使用できない

応答フィールドの説明

フィールド	説明
`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 2026-03-24