カスタム 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 認証を使用するには、次の手順に従います。

1. 名前空間を作成し、そのサブリソースを構成します。
2. Event Grid 名前空間でマネージド ID を有効にします。
3. マネージド ID に Azure 関数または Webhook へのアクセス権を付与します。
4. Event Grid 名前空間でカスタム Webhook の設定を構成します。
5. クライアントを 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 ロジックをホストできます。 Event Grid 呼び出し元トークンを検証するには、webhook API のMicrosoft Entraアプリの登録が必要です。 アプリの登録には、トークン発行用のアプリケーション ID URI があります。 クライアント側 (Event Grid) には既にマネージド ID があります。

長所:

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

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

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

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

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

任意のランタイム (.NET、Node.js、Java、またはPython) を使用します。

主な要件:

• エンドポイントは HTTPS である必要があります。

• 呼び出し元 JWT を検証する必要があります。

• デバイス JWT を検証する必要があります。

• タイムアウト内に応答する必要があります (約 5 秒をお勧めします)。

  

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

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

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

Microsoft Entra アプリを作成する

1. Microsoft Entra ID で Microsoft Entra アプリを作成します。

2. アプリの [概要] ページで、[アプリケーション (クライアント) ID] の値を記録しておきます。

   

3. 左側のメニューで [API の公開] を選びます。 [アプリケーション ID URI] の横にある [追加] を選びます。

4. [アプリケーション ID の URI の編集] ペインで [アプリケーション ID の URI] の値を記録してから、[保存] を選びます。

   

Azure 関数の認証を設定する

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

1. Azure Functions アプリに移動します。

2. 左側のメニューで [ 認証] を選択し、[ ID プロバイダーの追加] を選択します。

   

3. [ID プロバイダーの追加] ページで、[ID プロバイダー] のドロップダウン リストから [Microsoft] を選びます。

4. [アプリの登録] セクションで、次のプロパティの値を指定します。

   1. [アプリケーション (クライアント) ID]: 前に記録した Microsoft Entra アプリのクライアント ID を入力します。

   2. [発行者 URL]: https://login.microsoftonline.com/<tenantid>/v2.0 の形式で発行者 URL を追加します。

      

5. [ Token allowed audiences]\(トークンの許可対象ユーザー \) セクションで、許可されたトークン対象ユーザーを入力します。 具体的には、前に説明した Microsoft Entra アプリのアプリケーション ID URI を入力します。 トークン対象ユーザーは、Event Grid からの受信トークンを検証するために使用されます。

6. [ 追加のチェック ] セクションで、次の手順に従います。

   1. [クライアント アプリケーションの要件] で、[特定のクライアント アプリケーションからの許可された要求] を選択し、前に説明したアプリケーション ID を入力します。

   2. [ID 要件] で、[任意の ID からの要求を許可する] を選択します。

      

7. App Service の認証設定セクションで、次の手順に従います。

   1. [アクセスの制限] で、[認証が必要] を選びます。

   2. 認証されていない要求の場合は、[HTTP 401 Unauthorized を返す] を選択します。

      

8. 特定の要件に基づいて他の設定を選択した後、[追加] を選びます。

Microsoft Entra ID トークンを生成して使用する

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

1. アプリケーション ID URI (api://<ClientID>) をリソースとして持つマネージド ID を使用して、Microsoft Entra ID トークンを生成します。
2. このトークンを使用して、要求ヘッダーに含めることで Azure 関数を呼び出します。

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

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

Azure portal を使用する

1. Azure portal で Event Grid 名前空間に移動します。

2. [Event Grid 名前空間] ページで、左側のメニューの [構成] を選択します。

3. [カスタム 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 の値を入力します。

4. を選択してを適用します。

   

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

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

応答ペイロード:

成功応答

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 OK 
Content-Type: application/json 

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

エラー コード:

応答フィールドの説明

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

"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 の各クレームは正しいデータ型であり、属性として使われます。

関連コンテンツ

• MQTT クライアント認証
• カスタム JWT を使用してクライアントを認証する