次の方法で共有

クライアントのクライアント アクセス URL を生成する方法

  • [アーティクル]

クライアント (ブラウザー 💻、モバイル アプリ 📱、または IoT デバイス 💡) では、クライアント アクセス URL を使用してリソースに接続して認証します。

URL のパターンは次のとおりです。

  • MQTT クライアントの場合は、wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token> です。
  • 他のすべてのクライアントでは、wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> です。

この記事では、クライアント アクセス URL を取得するいくつかの方法について説明します。

Azure portal からコピーする

Azure portal の [キー] タブには、次の図に示すように、クライアント アクセス URL をすばやく生成するためのクライアント URL ジェネレーター ツールがあります。 ここで入力した値は保存されません。

MQTT クライアントの場合は、[クライアント アクセス URL] テキスト ボックスの前にあるドロップダウン メニューで [MQTT クライアント] を選ぶ必要があることに注意してください。

Web PubSub クライアント URL ジェネレーターのスクリーンショット。

サービス SDK から生成する

Web PubSub サーバー SDK を使用して、同じクライアント アクセス URL を生成できます。

  1. サーバー SDK の概要に関する記事に従って、WebPubSubServiceClient オブジェクト service を作成します

  2. WebPubSubServiceClient.getClientAccessToken を呼び出して、クライアント アクセス URL を生成します。

    • クライアント アクセス トークンを生成する

      // for web pubsub native clients
let token = await serviceClient.getClientAccessToken();

// for mqtt clients
let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });

    • ユーザー ID を構成する

      let token = await serviceClient.getClientAccessToken({ userId: "user1" });

    • トークンの有効期間を構成する

      let token = await serviceClient.getClientAccessToken({
  expirationTimeInMinutes: 5,
});

    • このクライアント アクセス URL を使用して接続するときに、グループ group1 に直接参加できるロールを構成する

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.joinLeaveGroup.group1"],
});

    • このクライアント アクセス URL を使用して接続するときに、クライアントからグループ group1 にメッセージを直接送信できるロールを構成する

      let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.sendToGroup.group1"],
});

    • このクライアント アクセス URL を使用して接続した後に、クライアントが参加するグループ group1 を構成する

      let token = await serviceClient.getClientAccessToken({
  groups: ["group1"],
});

実際のコードでは、通常、クライアント アクセス URL を生成するロジックをホストするサーバー側があります。 クライアント要求が入ると、サーバー側では、一般的な認証/認可ワークフローを使用してクライアント要求を検証できます。 クライアント アクセス URL を返すことができるのは、有効なクライアント要求だけです。

REST API :generateToken から生成する

Microsoft Entra ID を使用し、Generate Client Token REST API を呼び出してトークンを生成することもできます。

Note

Web PubSub では、Microsoft Entra ID サービス プリンシパル用の Microsoft Entra ID トークンを手動で作成することはお勧めしません。 これは、各 Microsoft Entra ID トークンは有効期間が短く、通常は 1 時間以内に期限切れになるためです。 この時間が経過したら、代わりの Microsoft Entra ID トークンを手動で生成する必要があります。 代わりに、期限切れの Microsoft Entra ID トークンを自動的に生成して置き換える Microsoft の SDK を使用してください。

  1. アプリケーションからの認可に関する記事に従って、Microsoft Entra ID を有効にします。

  2. Microsoft Entra トークンを取得します。

  3. Microsoft Entra トークンを使用して :generateToken を呼び出します。

  4. 次の情報を集めます。

    値の名前 値を取得する方法
    TenantId TenantId は、登録したアプリケーションの [概要] ペインにある [ディレクトリ (テナント) ID] の値です。
    ClientId ClientId は、登録したアプリケーションの [概要] ペインにある [アプリケーション (クライアント) ID] の値です。
    ClientSecret ClientSecret は、手順 1 で追加したクライアント シークレットの値です

  5. Microsoft ID プラットフォームから Microsoft Entra ID トークンを取得する

    CURL ツールを使用して、REST API を呼び出す方法を示します。 このツールは Windows 10/11 にバンドルされており、CURL のインストールに関する記事に従ってツールをインストールできます。

    # set necessary values, replace the placeholders with your actual values
export TenantId=<your_tenant_id>
export ClientId=<your_client_id>
export ClientSecret=<your_client_secret>

curl -X POST "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$ClientId" \
--data-urlencode "client_secret=$ClientSecret" \
--data-urlencode "scope=https://webpubsub.azure.com/.default"

    上記の curl コマンドを使用すると、Microsoft ID エンドポイントに POST 要求を送信して、Microsoft Entra ID トークンを取得することができます。 応答の access_token フィールドで Microsoft Entra ID トークンを確認できます。 後で使用するので、それをコピーして保存します。

  6. Microsoft Entra ID トークンを使用して :generateToken を呼び出します

    # Replace the values in {} with your actual values.
export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    MQTT クライアントのトークンを生成する必要がある場合は、URL に clientType=mqtt パラメーターを追加します。

    export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01&clientType=mqtt" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

    cURL コマンドを実行すると、次のような応答が返されます。

    {
  "token": "ABCDEFG.ABC.ABC"
}