次の方法で共有

カスタム Webhook 認証を使用して MQTT ブローカーで認証する (プレビュー)

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

Webhook 認証を使用すると、外部 HTTP エンドポイント (webhook または関数) で MQTT 接続を動的に認証できます。 この方法では、Microsoft Entra ID JWT 検証を使用して、セキュリティで保護されたアクセスを確保します。

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

注

この機能は現在プレビュー段階です。

[前提条件]

名前空間にカスタム Webhook 認証を使用するには、次の前提条件が必要です。

  • システム割り当てマネージド ID またはユーザー割り当てマネージド ID を持つ Event Grid 名前空間。
  • 外部 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 とユーザー割り当て ID を構成する方法については、「 Event Grid 名前空間のマネージド ID を有効にする」を参照してください。

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

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

Azure 関数のカスタム認証を設定するには、次の手順に従います。

Microsoft Entra アプリを作成する

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

  2. アプリの概要ページで、 アプリケーション (クライアント) ID をメモします。

    アプリケーションまたはクライアント ID が強調表示されている Microsoft Entra ID アプリの [概要] ページを示すスクリーンショット。

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

  4. [アプリケーション ID URI の編集] ページでアプリケーション ID URI をメモし、[保存] を選択します。

    Microsoft Entra アプリのアプリケーション ID URI を示すスクリーンショット。

Azure 関数の認証を設定する

Azure portal から作成された基本的な Azure 関数がある場合は、次の手順に従って認証を設定し、マネージド ID を使用して作成された Microsoft Entra ID トークンを検証します。

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

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

    [認証] ページを示すスクリーンショット。

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

  4. アプリの 登録で、次の手順を実行します。

    1. [クライアント ID] に、先ほど説明した Microsoft Entra アプリのクライアント ID を入力します。

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

      Microsoft を ID プロバイダーとして追加するスクリーンショットを示します。

  5. [許可されたトークン対象ユーザー] に、先ほど説明した Microsoft Entra アプリのアプリケーション UD URI を追加します。

  6. [ 追加 チェック] セクションで、次の手順を実行します。

    1. クライアント アプリケーション開発の場合は、[特定のクライアント アプリケーションからの要求を許可する] を選択します。
    2. [ 許可されたクライアント アプリケーション ] ページで、トークンの生成に使用するシステム割り当てマネージド ID の クライアント ID を入力します。 この ID は、Microsoft Entra ID リソースの エンタープライズ アプリ で確認できます。

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

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

  1. アプリケーション ID URI をリソースとして持つマネージド 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 の場合は、認証された Webhook 配信のベアラー トークンの取得に使用する Microsoft Entra テナント ID の値を入力します。

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

      Event Grid 名前空間の webhook 認証の構成を示すスクリーンショット。

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 にプレースホルダーを入力します。 Azure Event Grid MQTT Broker の Webhook ベースの認証のパフォーマンスと信頼性を高めるために、Webhook エンドポイントの HTTP/2 サポートを有効にすることを強くお勧めします。

Webhook API の詳細

要求ヘッダー

  • 承認: ベアラー トークン
    • 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>"
}

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

フィールド 必須/任意 説明
クライアントID 必須 MQTT CONNECT パケットからのクライアント ID。
ユーザー名 オプション MQTT CONNECT パケットからのユーザー名。
パスワード オプション base64 エンコードでの MQTT CONNECT パケットからのパスワード。
認証方法 オプション MQTT CONNECT パケットからの認証方法 (MQTT5 のみ)。
認証データ オプション base64 エンコードでの MQTT CONNECT パケットからの認証データ (MQTT5 のみ)。
クライアント証明書 オプション PEM 形式のクライアント証明書。
クライアント証明書チェーン オプション クライアント証明書から CA 証明書へのチェーンを構築するために必要な、クライアントによって提供される追加の証明書。
ユーザープロパティ オプション 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>" 
}

応答フィールドの説明

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

サポートされている属性の種類の例:

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

すべての正しいデータ型 (int32 に適合する数値、文字列、文字列の配列) が属性として使用されます。 この例では、 num_attr_pos、 num_attr_neg、 str_attr、 str_list_attr 要求は正しいデータ型を持ち、属性として使用されます。

関連コンテンツ