メッセージ拡張機能にサード パーティ認証を追加する

  • [アーティクル]

重要

このセクションのコード サンプルは、v4.6 以降のバージョンの Bot Framework SDK に基づいています。 以前のバージョンのドキュメントをお探しの場合は、ドキュメントの Resources フォルダーにある メッセージ拡張機能 - v3 SDK セクションを参照してください。

注:

メッセージ拡張機能に認証を追加した後、マニフェストの "validDomains" セクションに "token.botframework.com" を追加する必要があります。

ユーザーを識別する

サービスに対するすべての要求には、ユーザー ID、ユーザーの表示名、Microsoft Entra オブジェクト ID が含まれます。

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

id および aadObjectId の値は、認証された Teams ユーザーに対して保証されます。 これらは、サービス内の資格情報またはキャッシュされた状態を検索するためのキーとして使用されます。 さらに、各要求には、ユーザーのorganizationを識別するために使用されるMicrosoft Entra テナント ID が含まれています。 該当する場合、要求には、要求の送信元となるチーム ID とチャネル ID も含まれます。

認証

サービスでユーザー認証が必要な場合、ユーザーはメッセージ拡張機能を使用する前にサインインする必要があります。 認証手順は、ボットまたはタブの手順と似ています。シーケンスは次のとおりです。

  1. ユーザーがクエリを発行するか、既定のクエリがサービスに自動的に送信されます。
  2. サービスは、Teams ユーザー ID を調べることで、ユーザーが認証されているかどうかを確認します。
  3. ユーザーが認証されていない場合は、auth 応答をopenUrl 認証 URL を含む推奨アクションを返します。
  4. Microsoft Teams クライアントは、指定された認証 URL を使用して Web ページをホストするダイアログ ボックスを起動します。
  5. ユーザーがサインインしたら、ウィンドウを閉じて 認証コード を Teams クライアントに送信する必要があります。
  6. Teams クライアントは、手順 5 で渡された認証コードを含むクエリをサービスに再発行します。

サービスは、手順 6 で受け取った認証コードが手順 5 と一致するかどうかを確認する必要があります。 この手順により、悪意のあるユーザーがサインイン フローのなりすましや侵害を試みないようにします。 フローは、セキュリティで保護された認証シーケンスを完了するために、実質的に "ループを閉じます" 。

サインイン アクションで応答する

認証されていないユーザーに対してサインインを求めるメッセージを表示するには、認証 URL を含む型 openUrl の推奨アクションで応答します。

サインイン アクションの応答の例

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

注:

  • サインイン エクスペリエンスを Teams ポップアップ ウィンドウでホストするには、URL のドメイン部分がアプリの有効なドメインの一覧に含まれている必要があります。 詳細については、「マニフェスト スキーマのvalidDomains」 を参照してください。
  • 認証ポップアップのサイズは、幅と高さのクエリ文字列パラメーター Value = $"{_siteUrl}/searchSettings.html?height=600&width=600" を含めることによって定義できます。

サインイン フローを開始する

サインイン エクスペリエンスは応答性が高く、ポップアップ ウィンドウ内に収まる必要があります。 メッセージの受け渡しを使用する Microsoft Teams JavaScript クライアント ライブラリと統合する必要があります。

Microsoft Teams 内で実行される他の埋め込みエクスペリエンスと同様に、ウィンドウ内のコードは、最初に app.initialize() を呼び出す必要があります。 コードで OAuth フローを実行する場合は、Teams ユーザー ID をウィンドウに渡し、OAuth サインイン URL に渡すことができます。

サインイン フローを完了する

サインイン要求が完了し、ページにリダイレクトされたら、次の手順を実行する必要があります。

  1. セキュリティ コード (乱数) を生成します。 OAuth 2.0 トークンなど、サインイン フローから取得した資格情報を使用して、このコードをサービスにキャッシュする必要があります。
  2. authentication.notifySuccess を呼び出して、セキュリティ コードを渡します。

この時点でウィンドウが閉じ、コントロールが Teams クライアントに渡されます。 クライアントは、state プロパティのセキュリティ コードと共に、元のユーザー クエリを再発行します。 コードでは、セキュリティ コードを使用して、前に保存した資格情報を検索して認証シーケンスを完了し、ユーザー要求を完了できます。

再発行された要求の例

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "locale": "en-US",
        "country": "US",
        "platform": "Web",
        "type": "clientInfo"
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}

コード サンプル

サンプルの名前 説明 .NET Node.js マニフェスト
メッセージ拡張機能 - 認証と構成 構成ページがあり、検索要求を受け入れ、ユーザーがサインインした後に結果を返すメッセージ拡張機能。 表示 表示 表示

関連項目

ボットとメッセージ拡張機能アプリの SSO を有効にする