Teams ボットに認証を追加する

メール サービスなど、ユーザーの代わりにリソースにアクセスするボットをMicrosoft Teamsに作成できます。 OAuth 2.0 に基づいて、Azure Bot Service v4 SDK 認証を使用できます。 この方法を使用すると、ユーザーの資格情報に基づいて認証トークンを使用できるボットを簡単に開発できます。 キーは、 ID プロバイダーの使用です。

OAuth 2.0 は、Microsoft Entra ID やその他の多くの ID プロバイダーによって使用される認証と承認のオープン標準です。 OAuth 2.0 の基本的な解釈は、Teams で認証を操作するための前提条件です。

基本的な理解については、OAuth 2 Simplifiedを参照してください。完全な仕様については、OAuth 2.0 を参照してください。

Azure Bot Service による認証の処理方法の詳細については、「会話内のユーザー認証」を参照してください。

この記事では、以下について説明します。

• 認証が有効なボットを作成する方法。 cs-auth-sample を使用して、ユーザーのサインイン資格情報と認証トークンの生成を処理します。
• ボットを Azure にデプロイして ID プロバイダーに関連付ける方法。 プロバイダーは、ユーザーのサインイン資格情報に基づいてトークンを発行します。 ボットはトークンを使用して、認証を必要とするメール サービスなどのリソースにアクセスできます。 詳細については、「 ボットの認証フローをMicrosoft Teamsする」を参照してください。
• Microsoft Teams 内でボットを統合する方法。 ボットが統合されたら、チャットでサインインしてメッセージを交換できます。

前提条件

• ボットの基礎、管理状態、ダイアログ ライブラリ、およびシーケンシャル会話フローを実装する方法について説明します。

• Azure と OAuth 2.0 の開発に関する知識。

• Microsoft Visual Studio と Git の最新バージョン。

• Azure アカウント。 必要に応じて、Azure 無料アカウントを作成できます。

• 次のサンプル:

  サンプル	BotBuilder のバージョン	デモ
  cs-auth-sample での ボット認証	v4_4	OAuthCard のサポート
  js-auth-sample での ボット認証	v4_4	OAuthCard のサポート
  py-auth-sample での ボット認証	v4_4	OAuthCard のサポート

リソース グループを作成する

リソース グループとサービス プランは厳密には必要ありませんが、作成したリソースを簡単に解放できます。 リソースを整理して管理できるようにしておくことをお勧めします。

リソース グループを使用して、Bot Framework の個々のリソースを作成します。 パフォーマンスを確保するために、これらのリソースが同じ Azure リージョンにあることを確認します。

1. ブラウザーで、Microsoft Azure portal にサインインします。
2. 左側のナビゲーション パネルで、リソース グループ を選択します。
3. 表示されるウィンドウの左上で、[追加] タブを選択して、新しいリソース グループを作成します。 次のユーザー詳細を入力します。
   1. サブスクリプション。 既存のサブスクリプションを使用します。
   2. リソース グループ。 リソース グループの名前を入力します。 たとえば、 TeamsResourceGroup です。 名前は一意である必要があることに注意してください。
   3. [ リージョン ] ドロップダウン メニューで、[ 米国西部] またはアプリケーションに近いリージョンを選択します。
   4. [確認して作成] ボタンを選択します。 "検証合格" バナーが表示されます。
   5. [作成] ボタンを選択します。 リソース グループの作成には数分かかる場合があります。

ヒント

このチュートリアルの後半で作成するリソースと同様に、簡単にアクセスできるようにこのリソース グループをダッシュボードにピン留めすることをお勧めします。 これを行う場合は、ダッシュボードの右上にある 📌 ピン アイコンを選択します。

サービス プランを作成する

1. Azure portal の左側のナビゲーション パネルで、[リソースの作成] を選択します。
2. 検索ボックスに、「App Service Plan」 と入力します。 検索結果から App Service Plan カードを選択します。
3. [作成] を選択します。
4. 以下の情報を指定します。
   1. サブスクリプション。 既存のサブスクリプションを使用できます。
   2. リソース グループ。 前に作成したグループを選択します。
   3. 名前。 サービス プランの名前を入力します。 たとえば、 TeamsServicePlan などです。 名前はグループ内で一意である必要があることに注意してください。
   4. オペレーティング システム。 Windows または該当する OS 選択します。
   5. リージョン。 [米国西部] またはアプリケーションに近いリージョンを選択します。
   6. 価格レベル。 既定値である [ Standard S1] を選択します。
   7. [確認して作成] ボタンを選択します。 "検証合格" バナーが表示されます。
   8. [作成] を選択します。 アプリ サービス プランの作成には数分かかる場合があります。 プランがリソース グループに一覧表示されます。

Azure Bot リソースの登録を作成する

Azure Bot リソース登録は、Web サービスをボットとして Bot Framework に登録します。これにより、Microsoft アプリ ID とアプリ パスワード (クライアント シークレット) が提供されます。

重要

ボットが Azure でホストされていない場合にのみ、ボットを登録する必要があります。 Azure portal を 使用してボットを作成した場合は、サービスに既に登録されています。 Bot Framework または開発者ポータルを通じてボットを作成した場合、ボットは Azure に登録されていません。

1. Azure porta にアクセスし、[リソースの作成] セクションで Azure Bot を検索します。

2. Azure Bot を開き [作成] を選択します。

3. [ボット ハンドル] フィールドでボット ハンドル名を入力します。

4. ドロップダウン リストから [サブスクリプション] を選択します。

5. ドロップダウン リストから [リソース グループ] を選択します。

6. Microsoft アプリ ID のマルチテナントとしてアプリ種類を選択します。

   

7. [確認 + 作成] を選びます。

   

8. 検証に合格した場合は、[作成] を選択します。

   Azure では、しばらくしてボットがプロビジョニングされます。

   

9. [リソースに移動] を選びます。 ボットと関連リソースがリソース グループに一覧表示されます。

   

   Azure ボットが作成されます。

   

クライアント シークレットを作成するには:

1. [構成設定] で、[追加] を選択します。 将来の参照のために、Microsoft アプリ ID (クライアント ID) を保存します。

   

2. [Microsoft アプリ ID] の横にある [管理] を選択します。

   

3. [クライアント シークレット] セクションで、[新しいクライアント シークレット]を選択します。[クライアント シークレットの追加] ウィンドウが表示されます。

   

4. [説明] を入力し、[追加] を選択します。

   

5. [値] の列で、[クリップボードにコピー] を選択し、将来参照できるようにクライアント シークレット ID を保存します。

   

Microsoft Teams チャネルに追加するには:

1. [ホーム] に移動します。

   

2. [ 最近使ったリソース ] セクションからボットを開きます。

3. 左側のウィンドウで [ チャネル ] を選択し、[ Microsoft Teams ] を選択します。

   

4. チェックボックスをオンにして利用規約に同意し、[同意する] を選択 します。
   

   

5. [保存] を選択します。

   

詳細については、「Microsoft Teams 用にボットを作成する」を参照してください。

ID プロバイダーの作成

認証には ID プロバイダーが必要です。 この手順では、Microsoft Entra プロバイダーを使用します。 または、サポートされている他の Microsoft Entra ID ID プロバイダーを使用することもできます。

1. Azure portal の左側のナビゲーション パネルで、[Microsoft Entra ID] を選択します。

   ヒント

   アプリケーションによって要求されたアクセス許可を委任することに同意できるテナントで、この Microsoft Entra リソースを作成して登録する必要があります。 テナントの作成手順については、「 ポータルにアクセスしてテナントを作成する」を参照してください。

2. 左側のパネルで、[アプリの登録] を選択します。

3. 右側のパネルで、左上の [新規登録] タブを選択します。

4. 以下の情報を指定します。

   1. 名前。 アプリケーションの名前を入力します。 例として BotTeamsIdentity があります。 名前は一意である必要があることに注意してください。
   2. アプリケーションにサポートされているアカウントの種類を選択します。 任意の組織ディレクトリ (任意の Microsoft Entra ID テナント - マルチテナント) と個人用 Microsoft アカウント (Skype、Xbox など) のアカウントを選択します。
   3. [リダイレクト URI] の場合:
      ✓ [Web] を選択します。
      ✓ URL を https://token.botframework.com/.auth/web/redirect に設定します。
   4. [登録] を選択します。

5. Azure によってアプリが作成されると、アプリの [概要 ] ページが表示されます。 次の情報をコピーしてファイルに保存します。

   1. アプリケーション (クライアント) ID の値。 この Azure ID アプリケーションをボットに登録するときは、後で クライアント ID としてこの値を使用します。
   2. [ディレクトリ (テナント) ID] をコピーします。 この Azure ID アプリケーションをボットに登録するときは、後で テナント ID としてこの値を使用します。

6. 左側のパネルで [証明書とシークレット] を選択して、アプリケーションのクライアント シークレットを作成します。

   1. [ クライアント シークレット] で、[ 新しいクライアント シークレット] を選択➕します。
   2. Teams のボット ID アプリなど、このアプリ用に作成する必要がある可能性がある他のユーザーからこのシークレットを識別する説明を追加します。
   3. [期限切れ] を選択に設定します。
   4. [追加] を選択します。
   5. このページを終了する前に、シークレットを記録します。 Microsoft Entra アプリケーションをボットに登録するときは、後でこの値を クライアント シークレット として使用します。

ID プロバイダー接続を構成し、ボットに登録する

注:

サービス プロバイダーには、Azure Active Directory v1 と Azure Active Directory v2 の 2 つのオプションがあります。 2 つのプロバイダー間の違いを ここでまとめますが、一般的に、v2 ではボットのアクセス許可の変更に関して柔軟性が高くなります。 Graph API アクセス許可がスコープ フィールドに一覧表示され、新しいアクセス許可が追加されると、ボットによって、ユーザーは次回のサインイン時に新しいアクセス許可に同意できるようになります。 v1 の場合、OAuth ダイアログで新しいアクセス許可を求めるメッセージが表示されるように、ボットの同意をユーザーが削除する必要があります。

Microsoft Azure Active Directory (Azure AD) v1

1. Azure portal で、ダッシュボードからリソース グループを選択します。

2. ボット登録リンクを選択します。

3. リソース ページを開き、[設定]の下にある [構成] を選択します。

4. [OAuth 接続設定の追加] を選択します。 次の図は、リソース ページの対応する選択を示しています。

   

5. フォームに次のように入力します。

   1. 名前。 接続の名前を入力します。 この名前は、 appsettings.json ファイル内のボットで使用します。 たとえば、 BotTeamsAuthADv1 です。

   2. サービス プロバイダー。 Azure Active Directory を選択します。 このオプションを選択すると、Azure Active Directory 固有のフィールドが表示されます。

   3. クライアント ID。Azure ID プロバイダー アプリ用に記録したアプリケーション (クライアント) ID を入力します。

   4. クライアント シークレット。 Azure ID プロバイダー アプリ用に記録したシークレットを入力します。

   5. 許可の種類。 authorization_code を入力します。

   6. ログイン URL。 https://login.microsoftonline.com を入力します。

   7. テナント ID、ID プロバイダー アプリの作成時に選択したサポートされているアカウントの種類に応じて、先ほど Azure ID アプリ用に記録した ディレクトリ (テナント) ID を入力するか、common を入力します。 割り当てる値を決定するには、次の条件に従います。

      • [この組織のディレクトリ内のアカウントのみ (Microsoft のみ - シングル テナント)] または任意の組織ディレクトリのアカウント (任意の Microsoft Entra ID テナント - マルチテナント) を選択した場合は、Microsoft Entra アプリ用に前に記録したテナント ID を入力します。 これは、認証できるユーザーに関連付けられているテナントになります。

      • 任意の組織ディレクトリ (任意の Microsoft Entra ID テナント - マルチテナント) と個人用 Microsoft アカウント (Skype、Xbox など) で [アカウント] を選択した場合は、テナント ID の代わりに共通の単語を入力します。 それ以外の場合、Microsoft Entra アプリは、ID が選択されたテナントを介して検証し、個人の Microsoft アカウントを除外します。

   h. リソース URL には、「https://graph.microsoft.com/」と入力します。 この URL は、コード サンプルでは使用されません。
   i. [Scopes] は空白のままにします。 次の図に例を示します。

   

6. [保存] を選択します。

Microsoft Azure Active Directory (Azure AD) v2

1. Azure portal で、ダッシュボードから Azure Bot を選択します。

2. リソース ページで、[設定] にある [構成] を選択します。

3. [OAuth 接続設定の追加] を選択します。
   次の図は、リソース ページの対応する選択を示しています。

   

4. フォームに次のように入力します。

   1. 名前。 接続の名前を入力します。 appsettings.json ファイル内のボットでこの名前を使用します。 たとえば、 BotTeamsAuthADv2 です。

   2. サービス プロバイダー。 [ Azure Active Directory v2] を選択します。 このオプションを選択すると、Azure AD v2 固有のフィールドが表示されます。

   3. クライアント ID。Azure ID プロバイダー アプリ用に記録したアプリケーション (クライアント) ID を入力します。

   4. クライアント シークレット。 Azure ID プロバイダー アプリ用に記録したシークレットを入力します。

   5. トークン交換 URL。 空白のままにします。

   6. テナント ID、ID プロバイダー アプリの作成時に選択したサポートされているアカウントの種類に応じて、先ほど Azure ID アプリ用に記録した ディレクトリ (テナント) ID を入力するか、common を入力します。 割り当てる値を決定するには、次の条件に従います。

      • [この組織のディレクトリ内のアカウントのみ (Microsoft のみ - シングル テナント)] または任意の組織ディレクトリのアカウント (任意の Microsoft Entra ID テナント - マルチテナント) を選択した場合は、Microsoft Entra アプリ用に前に記録したテナント ID を入力します。 これは、認証できるユーザーに関連付けられているテナントになります。

      • 任意の組織ディレクトリ (任意の Microsoft Entra ID テナント - マルチテナント) と個人用 Microsoft アカウント (Skype、Xbox など) で [アカウント] を選択した場合は、テナント ID の代わりに共通の単語を入力します。 それ以外の場合、Microsoft Entra アプリは、ID が選択されたテナントを介して検証し、個人の Microsoft アカウントを除外します。

   7. [スコープ] には、User.Read、User.ReadBasic.All、Mail.Read など、アプリケーションで必要なグラフのアクセス許可のスペース区切りの一覧を入力します。

5. [保存] を選択します。

接続をテストします。

1. 接続エントリを選択して、作成した接続を開きます。

2. [サービス プロバイダー接続設定] パネルの上部になる[テスト接続] を選択します。

3. 初めて、アカウントの選択を求める新しいブラウザー ウィンドウが開きます。 使用するものを選択します。

4. 次に、ID プロバイダーにデータ (資格情報) の使用を許可します。 次の図に例を示します。

   

5. [同意する] を選択します。

6. [test connection to <your-connection-name> Succeeded]\(成功しました\) ページが開きます。 エラーが発生した場合は、ページを更新します。 次の図に例を示します。

   

ボット コードでは、接続名を使用してユーザー認証トークンを取得します。

ボットのサンプル コードを準備する

準備の設定が完了したら、この記事で使用するボットの作成に焦点を当ててみましょう。

C#/.NET

1. cs-auth-sample を複製します。

2. Visual Studio を開きます。

3. ツール バーで、[ ファイル] > [プロジェクト/ソリューション > 開く ] を選択し、ボット プロジェクトを開きます。

4. C# では、次のように 更新appsettings.json 。

   • ConnectionName を、ボット登録に追加した ID プロバイダー接続の名前に設定します。 この例で使用した名前は、BotTeamsAuthADv1 です。
   • MicrosoftAppId をボット登録時に保存した ボット アプリ ID に設定します。
   • ボットの登録時に保存した カスタマー シークレット を MicrosoftAppPassword に設定します。

   ボット シークレットの文字によっては、パスワードを XML でエスケープすることが必要になる場合があります。 たとえば、アンパサンド (&) は &としてエンコードする必要があります。

   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "",
     "MicrosoftAppPassword": "",
     "ConnectionName": "",
   

5. ソリューション エクスプローラーで、TeamsAppManifest フォルダーに移動し、manifest.jsonを開き、idを設定し、ボットの登録時に保存したボットアプリ ID にbotIdします。 詳細については、「アプリ マニフェスト」を参照してください。

JavaScript

1. node-auth-sample を複製します。

2. コンソールで、プロジェクトに移動します。
   
   cd samples/bot-teams-authentication/nodejs

3. モジュールをインストールする
   
   npm install

4. 次のように .env 構成を更新します:

   • MicrosoftAppId をボット登録時に保存した ボット アプリ ID に設定します。
   • ボットの登録時に保存した カスタマー シークレット を MicrosoftAppPassword に設定します。
   • connectionName を ID プロバイダー接続の名前に設定します。 ボット シークレットの文字によっては、パスワードを XML でエスケープすることが必要になる場合があります。 たとえば、アンパサンド (&) は &としてエンコードする必要があります。

   MicrosoftAppId=
   MicrosoftAppPassword=
   connectionName=
   MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
   MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
   

5. teamsAppManifest フォルダーで、manifest.jsonを開き、idを Microsoft アプリ ID に設定し、ボットの登録時に保存したボットアプリ ID にbotIdします。

Python

1. GitHub リポジトリから py-auth-sample を複製します。

2. config.py を更新します:

   • ConnectionName を、ボットに追加した OAuth 接続設定の名前に設定します。

   • MicrosoftAppId と MicrosoftAppPassword をボットのアプリ ID とアプリ シークレットに設定します。

     ボット シークレットの文字によっては、パスワードを XML でエスケープすることが必要になる場合があります。 たとえば、アンパサンド (&) は &としてエンコードする必要があります。

     APP_ID = os.environ.get("MicrosoftAppId", "")
     APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
     CONNECTION_NAME = os.environ.get("ConnectionName", "")
     

ボットを Azure にデプロイする

ボットをデプロイするには、「 Azure にボットをデプロイする方法」の手順に従います。

または、Visual Studio の場合は、次の手順を実行できます:

1. Visual Studio ソリューション エクスプローラーで、プロジェクト名を長押し (または右クリック) します。

2. ドロップダウン メニューの [発行] を選択 します。

3. 表示されたウィンドウで、[新規] リンクを選択します。

4. ダイアログ ウィンドウで、[ App Service ] と [ 新規作成] を選択します。

5. [公開] ボタンをクリックします。

6. 次のダイアログ ウィンドウで、必要な情報を入力します。

   

7. [作成] を選択します。

8. デプロイが正常に完了すると、Visual Studio に反映されます。 既定のブラウザーでページが開き、[ ボットの準備ができました!] というメッセージが表示されます。 URL は https://botteamsauth.azurewebsites.net/に似ています。 ファイルに保存します。

9. ブラウザーで、 Azure portal に移動します。

10. リソース グループを確認すると、ボットが他のリソースと共に一覧表示されます。 次の図に例を示します。

    

11. リソース グループで、ボット登録名 (リンク) を選択します。

12. 左側のウィンドウで [設定] を選択します。

13. [ メッセージング エンドポイント ] ボックスに、取得した URL の後に api/messages を入力します。 たとえば、「 https://botteamsauth.azurewebsites.net/api/messages 」のように入力します。

    注:

    ボットに対して許可されるメッセージング エンドポイントは 1 つだけです。

14. 左上の [保存] ボタンを選択します。

エミュレーターを使用してボットをテストする

Microsoft Bot Framework Emulator をインストールします。 詳細については、「 エミュレーターを使用したテストとデバッグ」を参照してください。

ボットのサンプル サインインを機能させるには、エミュレーターを構成する必要があります。

認証用にエミュレーターを構成する

ボットで認証が必要な場合は、エミュレーターを構成する必要があります。 構成するには:

1. エミュレーターを起動します。
2. エミュレーターで、左下の歯車アイコン⚙、または右上の [ エミュレーターの設定] タブを選択します。
3. [バージョン 1.0 認証トークンを使用] のチェック ボックスをオンにします。
4. ngrok ツールへのローカル パスを入力します。 「Bot Framework Emulator/ngrok トンネリング統合」の Wiki を参照してください。 ツールの詳細については、ngrok を参照してください。
5. [エミュレーターの起動時に ngrok を実行] チェック ボックスをオンにします。
6. [保存] ボタンを選択します。

ボットにサインイン カードが表示され、ユーザーがサインイン ボタンを選択すると、エミュレーターによって、ユーザーが認証プロバイダーでサインインするために使用できるページが開きます。 ユーザーが個の操作を行うと、プロバイダーによってユーザー トークンが生成され、ボットに送信されます。 その後、ユーザーの代わりにボットが動作できるようになります。

ボットをローカルでテストする

認証メカニズムを構成したら、実際のボット テストを実行できます。

1. たとえば、Visual Studio を使用して、お使いのコンピューターでボット サンプルをローカルで実行します。

2. エミュレーターを起動します。

3. [ボットを開く] ボタンを選択します。

4. [ボットの URL] に、ボットのローカル URL を入力します。 通常は、http://localhost:3978/api/messages です。

5. [Microsoft アプリ ID] に、appsettings.jsonからボットのアプリ ID を入力します。

6. Microsoft App パスワードで、appsettings.jsonからボットのアプリ パスワードを入力します。

7. [接続] を選択します。

8. ボットが起動して実行されたら、任意のテキストを入力してサインイン カードを表示します。

9. [サインイン] ボタンを選択します。

10. ポップアップ ダイアログが [ 開いている URL の確認 ] に表示され、ボットのユーザーを認証します (ユーザー)。

11. [確認] を選択します。

12. メッセージが表示されたら、該当するユーザーのアカウントを選択します。

13. エミュレーターに使用した構成に応じて、次のいずれかのオプションが表示されます。

    1. サインイン確認コードの使用
       ✓ 検証コードを表示するウィンドウが開きます。
       ✓コピーし、サインインを完了するためにチャットボックスに検証コードを入力します。
    2. 認証トークンの使用。
       ✓ 資格情報に基づいてサインインしています。

    次の図は、サインイン後のボット UI の例です。

    

14. ボットで [トークンを表示しますか?] を求められたときに [はい] を選択すると、次の応答が返されます。

    

15. 入力チャット ボックスに 「ログアウト 」と入力してサインアウトします。ユーザー トークンが解放され、もう一度サインインするまでボットはユーザーに代わって行動できなくなります。

注:

ボット認証には、Bot Connector Service を使用する必要があります。 このサービスは、ボットのボット登録情報にアクセスします。

デプロイされたボットをテストする

1. ブラウザーで、 Azure portal に移動します。

2. リソース グループを見つけます。

3. リソース リンクを選択します。 リソース ページが表示されます。

4. リソース ページで、[Web チャットでテスト] を選択します。 ボットが起動し、事前定義された案内応答が表示されます。

5. チャット ボックスに何かを入力します。

6. [サインイン] ボックスを選択します。

7. ポップアップ ダイアログが [ 開いている URL の確認 ] に表示され、ボットのユーザーを認証します (ユーザー)。

8. [確認] を選択します。

9. メッセージが表示されたら、該当するユーザーのアカウントを選択します。 次の図は、サインイン後のボット UI の例です。

   

10. [はい] ボタンを選択して、認証トークンを表示します。 次の図に例を示します。

    

11. 入力チャット ボックスに 「ログアウト 」と入力してサインアウトします。

    

注:

サインインで問題が発生した場合は、前の手順で説明したように、接続を再度テストしてみてください。 これにより、認証トークンが再作成される可能性があります。 Azure の Bot Framework Web チャット クライアントでは、認証が正しく確立される前に、何度かサインインする必要がある場合があります。

Teams でボットをインストールしてテストする

1. ボット プロジェクトで、TeamsAppManifest フォルダーに manifest.json が、outline.png および color.png と共に含まれていることを確認します。

2. ソリューション エクスプローラーで、 TeamsAppManifest フォルダーに移動します。 次の値を割り当てて、manifest.json を編集します:

   1. ボットの登録時に受け取ったボット アプリ ID が id と botId に割り当てられていることを確認します。
   2. この値を割り当てます: validDomains: [ "token.botframework.com" ]。

3. manifest.json、outline.png、および color.png ファイルを選択して zip します。

4. Microsoft Teams を開きます。

5. 左側のパネルの下部で、Apps アイコン を選択します。

6. 右側のパネルの下部にある [カスタム アプリのアップロード] を選択します。

7. TeamsAppManifest フォルダーに移動し、zip 形式のマニフェストをアップロードします。 次のウィンドウが表示されます。

   

8. [チームに追加] ボタンを選択します。

9. 次のウィンドウで、ボットを使用するチームを選択します。

10. [ボットの設定] ボタンを選択します。

11. 左側のパネルで 3 つのドット (●●●) を選択します。 次に、[ 開発者ポータル ] アイコンを選択します。

12. [マニフェスト エディター] タブを選択します。アップロードしたボットのアイコンが表示されます。

13. また、ボットとメッセージを交換するために使用できるボットをチャットリストに連絡先として表示できます。

Teams でボットをローカルでテストする

Teams は完全にクラウドベースの製品です。 HTTPS エンドポイントを使用して、アクセスするすべてのサービスをクラウドから利用できるようにする必要があります。 そのため、ボット (サンプル) を Teams で動作させるには、任意のクラウドにコードを発行するか、トンネリング ツールを使用してローカルで実行されているインスタンスに外部からアクセスできるようにする必要があります。 コンピューターでローカルに開くポートの外部アドレス指定可能な URL を作成する ngrok をお勧めします。 Teams アプリをローカルで実行するための準備として ngrok を設定するには、次の手順に従います。

1. ターミナル ウィンドウで、ngrok.exe がインストールされているディレクトリに移動します。 環境変数 パスをポイントするように設定することをお勧めします。

2. たとえば、ngrok http 3978 --host-header=localhost:3978 を実行します。 必要に応じてポート番号を置き換えます。 指定したポートでリッスンするために ngrok が起動します。 その返しとして、ngrok が実行されている限り有効な外部アドレス指定可能な URL が提供されます。 次の図に例を示します。

   

3. 次のような転送 HTTPS アドレスをコピーします: https://dea822bf.ngrok.io/。

4. /api/messagesを追加してhttps://dea822bf.ngrok.io/api/messagesを取得します。これは、コンピューター上でローカルで実行され、Teams のチャットで Web 経由で到達できるボットのメッセージ エンドポイントです。

5. 実行する最後の手順の 1 つは、デプロイされたボットのメッセージ エンドポイントを更新することです。 この例では、ボットを Azure にデプロイしました。 それでは、次の手順を実行しましょう:

   1. ブラウザーで、 Azure portal に移動します。
   2. [ボットの登録] を選択します。
   3. 左側のウィンドウで [設定] を選択します。
   4. 右側のパネルの [メッセージング エンドポイント] ボックスに、ngrok URL を入力します(例: https://dea822bf.ngrok.io/api/messages)。

6. ボットをローカルで起動します (Visual Studioデバッグ モードなど)。

7. Bot Framework ポータルの [Web チャットのテスト] を使用して、ローカルでの実行中にボットをテストします。 エミュレーターと同様に、このテストでは Teams 固有の機能にアクセスすることはできません。

8. ngrok が実行されているターミナル ウィンドウでは、ボットと Web チャット クライアントの間の HTTP トラフィックを確認できます。 より詳細なビューが必要な場合は、ブラウザー ウィンドウで、前のターミナル ウィンドウから取得した http://127.0.0.1:4040 を入力します。 次の図に例を示します。

   

注:

ngrok を停止して再起動すると、URL が変更されます。 プロジェクトで ngrok を使用するには、また使用している機能に応じて、すべての URL 参照を更新する必要があります。

その他の情報

TeamsAppManifest/manifest.json

このマニフェストには、ボットに接続するために Teams で必要な情報が含まれています。

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

認証では、Teams は他のチャネルとは異なる動作をします。

呼び出しアクティビティの処理

呼び出しアクティビティは、ActivityHandler をサブクラス化することによって行われる他のチャネルで使用されるイベント アクティビティではなく、ボットに送信されます。

C#/.NET

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

OAuthPrompt を使用する場合は、呼び出しアクティビティをダイアログに転送する必要があります。

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs

protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

JavaScript

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

OAuthPrompt を使用する場合は、呼び出しアクティビティをダイアログに転送する必要があります。

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

dialogs/mainDialog.js

ダイアログ手順内で、beginDialog を使用して OAuth プロンプトを開始します。これにより、ユーザーにサインインを求められます。

• ユーザーが既にサインインしている場合は、ユーザーにメッセージを表示せずにトークン応答イベントが生成されます。
• それ以外の場合は、サインインするようにユーザーに求められます。 Azure Bot Service は、ユーザーがサインインを試みた後にトークン応答イベントを送信します。

async promptStep(stepContext) {
    try {

次のダイアログ ステップで、前の手順の結果にトークンが存在するかどうかを確認します。 null でない場合、ユーザーは正常にサインインしました。

async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

Python

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

OAuthPrompt を使用する場合は、呼び出しアクティビティをダイアログに転送する必要があります。

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

ダイアログ手順で、begin_dialog を使用して OAuth プロンプトを開始します。これにより、ユーザーにサインインを求められます。 ユーザーが既にサインインしている場合は、ユーザーにメッセージを表示せずにトークン応答イベントが生成されます。 それ以外の場合は、サインインするようにユーザーに求められます。 Azure Bot Service は、ユーザーがサインインを試みた後にトークン応答イベントを送信します。

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

次のダイアログ ステップで、前の手順の結果にトークンが存在するかどうかを確認します。 null でない場合、ユーザーは正常にサインインしました。

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # Get the token from the previous step. Note that we could also have gotten the
    # token directly from the prompt itself. There is an example of this in the next method.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

コード サンプル

このセクションでは、ボット認証 v3 SDK のサンプルを提供します。

サンプルの名前	説明	.NET	Node.js	Python	マニフェスト
ボット認証	このサンプルでは、Teams 用ボットで認証を開始する方法を示します。	表示	表示	表示	表示
タブ、ボット、メッセージ拡張機能 (ME) SSO	このサンプルでは、タブ、ボット、ME の Microsoft Entra SSO - 検索、アクション、リンク展開を示します。	表示	表示	該当なし	表示

関連項目

• Azure Bot Service を使用して認証を追加する
• ユーザーの代わりにアクセスを取得