ボットに認証を追加する

[アーティクル]
12/26/2023

この記事の対象: SDK v4

Azure AI Bot Service v4 SDK を使用すると、ユーザー認証を必要とするオンラインリソースにアクセス可能なボットの開発が容易になります。 Azure が OAuth 2.0 を使用して各ユーザー資格情報に基づいてトークンを生成するため、ボットが認証トークンを管理する必要はありません。ボットでは、Azure によって生成されたトークンを使用して、それらのリソースにアクセスします。この方法では、ユーザーはセキュリティで保護されたリソースにアクセスするための ID とパスワードをボットに提供する必要はありません。信頼できる ID プロバイダーにのみ提供します。

Bot Framework でのこの種類の認証を処理する方法の概要については、「ユーザー認証」を参照してください。

この記事では、2 つのサンプルを参照します。 1 つは、認証トークンを取得する方法を示しています。もう 1 つはより複雑で、ユーザーに代わって Microsoft Graph にアクセスする方法を示しています。どちらの場合も、ID プロバイダーとして Azure AD v1 または v2 を使用して、ボットの OAuth トークンを取得できます。この記事では、次の方法について説明します。

Azure Bot リソースを作成する
Microsoft Entra ID ID プロバイダーを作成する
Microsoft Entra ID ID プロバイダーをボットに登録する
ボットコードを準備する

この記事を完了すると、いくつかの単純なタスクに応答できるボットが完成します。 Microsoft Graph の例では、メールの送信、自分の情報の表示、最新のメールの確認を行えます。 OAuth の機能をテストするためにボットを公開する必要はありませんが、ボットには有効な Azure アプリ ID とパスワードが必要になります。

Note

Bot Framework JavaScript SDK、C#、Python SDK は引き続きサポートされますが、Java SDK については、最終的な長期サポートは 2023 年 11 月に終了する予定です。このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットの構築については、Power Virtual Agents の使用を検討し、適切なチャットボットソリューションの選択についてお読みください。

詳細については、「The future of bot building」をご覧ください。

Web チャットと Direct Line に関する考慮事項

重要

Web チャットコントロールを使用してボットに接続するときのセキュリティリスクを軽減するには、強化された認証を有効にした Direct Line を使用する必要があります。詳細については、「Direct Line 拡張認証」を参照してください。

前提条件

ボットの基本、状態の管理、ダイアログライブラリ、連続して行われる会話フローを実装する方法、ダイアログを再利用する方法に関する知識。
Azure と OAuth 2.0 開発の知識。
.NET 用の Visual Studio 2017 以降。
Javascript 用の Node.js。
Python 用 Python 3.8 以降。

次に示すサンプルのいずれか。

サンプル	BotBuilder のバージョン	説明
C#、JavaScript、Java、Python での認証	v4	OAuthCard サポート
C#、JavaScript、Java、または Python での Microsoft Graph の認証	v4	OAuth 2.0 を使用した Microsoft Graph API サポート
C#、JavaScript、Java、または Python での Microsoft Teams の認証	v4	OAuth 2.0 を使用した Microsoft Graph API サポート

この記事で参照しているサンプルを実行するには、次のものが必要です。

Azure にボットリソースを登録するための Microsoft Entra ID アプリケーション。このアプリケーションを使用すると、ボットはMicrosoft Graph などのセキュリティで保護された外部リソースにアクセスできます。また、ユーザーは Web チャットなどの複数のチャネルを介してボットと通信できます。
ID プロバイダーとして機能する別の Microsoft Entra ID アプリケーション。このアプリケーションは、ボットとセキュリティで保護されたリソースの間で OAuth 接続を確立するために必要な資格情報を提供します。この記事では、ID プロバイダーとして Active Directory を使用することに注意してください。他にも多くのプロバイダーがサポートされています。

重要

Azure でボットを登録すると必ず、Microsoft Entra ID アプリケーションが割り当てられますが、このアプリケーションで保護されるのは、チャネルからボットへのアクセスです。ユーザーに代わってボットがアクセスする外部のセキュリティで保護されたリソースごとに、別の Microsoft Entra ID アプリケーションが必要です。

リソースを作成する

Azure Bot リソースを作成します。これにより、ボットを Azure AI Bot Service に登録できます。

ヒント

新しい Web アプリボット と ボットチャンネル登録リソースは作成できませんが、構成および配置された既存のリソースは引き続き機能します。 SDK バージョン 4.14.1.2 以降の VSIX または Yeoman テンプレートから作成されたボットには、Azure Bot リソースを生成する ARM テンプレートが含まれています。

Azure ポータルにアクセスします。
右側のウィンドウで、 [リソースの作成] を選びます。
検索ボックスに「bot」と入力し、Enter キーを押します。
Azure Bot カードを選択します。
［作成］ を選択します
必須フィールドに値を入力し、設定の確認と更新を行います。
1. [プロジェクトの詳細] に情報を入力します。ボットにグローバルデータ所在地とローカルデータ所在地のどちらを使用するかを選択します。現在、ローカルデータ所在地機能は、「westeurope」および「centralindia」リージョンのリソースで使用できます。詳細については、「Azure AI Bot Service での登録」を参照してください。
2. [Microsoft アプリ ID] に情報を入力します。 Azure でボット ID を管理する方法と、新しい ID を作成するか、既存の ID を使用するかを選択します。
[Review + create](レビュー + 作成) を選択します。
検証テストに合格したら、[作成] を選びます。
デプロイが完了したら、[リソースに移動] を選択します。選択したリソースグループにボットと関連リソースが一覧表示されます。
Bot Framework SDK をまだお持ちでない場合は、[GitHub からダウンロード] を選択して、優先する言語のパッケージを使用する方法を確認してください。

これで、Bot Framework SDK を使用してボットを構築する準備ができました。

ヒント

Azure が新しいアプリ ID を使用して、新しいシングルテナントまたはマルチテナントの Azure Bot リソースを作成すると、パスワードも生成されます。

ボット ID 情報

次の手順に従って、ボットの構成ファイルに ID 情報を追加します。ファイルは、ボットの作成に使用するプログラミング言語によって異なります。

重要

Java バージョンと Python バージョンの Bot Framework SDK では、マルチテナントボットのみがサポートされます。 C# バージョンと JavaScript バージョンでは、ボットの ID を管理するための 3 種類のアプリケーションがすべてサポートされています。

Language	ファイル名	メモ
C#	appsettings.json	ボットの ID を管理するための 3 種類のアプリケーションがすべてサポートされています。
JavaScript	.env	ボットの ID を管理するための 3 種類のアプリケーションがすべてサポートされています。
Java	アプリケーションプロパティ:	マルチテナントボットのみをサポートします。
Python	config.py	マルチテナントボットのみをサポートします。 `os.environ.get` メソッド呼び出しの引数として ID プロパティを提供します。

追加する必要がある ID 情報は、ボットのアプリケーションタイプによって異なります。構成ファイルで次の値を提供します。

Java と C# ボットでのみ使用できます。

プロパティ	値
`MicrosoftAppType`	`UserAssignedMSI`
`MicrosoftAppId`	ユーザー割り当てマネージド ID のクライアント ID
`MicrosoftAppPassword`	該当なし。ユーザー割り当てマネージド ID ボットの場合は、この値を空白のままにします。
`MicrosoftAppTenantId`	ユーザー割り当てマネージド ID のテナント ID。

Java と C# ボットでのみ使用できます。

プロパティ	値
`MicrosoftAppType`	`SingleTenant`
`MicrosoftAppId`	ボットのアプリ ID。
`MicrosoftAppPassword`	ボットのアプリパスワード。
`MicrosoftAppTenantId`	ボットのアプリテナント ID。

すべてのプログラミング言語 (C#、JavaScript、Java、Python) のボットで使用できます。

プロパティ	値
`MicrosoftAppType`	`MultiTenant`
`MicrosoftAppId`	ボットのアプリ ID。
`MicrosoftAppPassword`	ボットのアプリパスワード。
`MicrosoftAppTenantId`	該当なし。マルチテナントボットの場合は、この値を空白のままにします。

App Service を更新するには

ボットの既存の App Service リソース (Web アプリ) があり、ボットが ユーザー割り当てマネージド ID アプリケーションである場合は、ボットの App Service を更新する必要がある場合があります。

ボットの Web アプリの App Service ブレードに移動します。
[設定] にある [ID] を選択します。
[ID] ブレードで [ユーザー割り当て] タブを選択し、[追加] (+) を選択します。
ユーザー割り当てマネージド ID の追加 ブレード上:
1. サブスクリプションを選択します。
2. ユーザー割り当てマネージド ID の場合は、ボットのマネージド ID を選択します。マネージド ID が自動的に生成された場合は、ボットと同じ名前になります。
3. ボットにこの ID を使用するには、[追加] を選択します。

アプリまたはテナント ID を取得するには

ボットのアプリまたはテナント ID を取得するには:

ボットの [Azure Bot リソース] ブレードに移動します。
ボットの [構成] ブレードに移動します。このブレードから、ボットの Microsoft アプリ ID またはアプリテナント ID をコピーできます。

新しいパスワードを生成するには

シングルテナントボットとマルチテナントボットには、一部の操作に必要となるアプリシークレットまたはパスワードがあります。 Azure AI Bot Service では、ボットシークレットが非表示になります。ただし、ボットの App Service リソースの所有者は、新しいパスワードを生成できます。

ボットの [Azure Bot リソース] ブレードに移動します。
ボットの [構成] ブレードに移動します。
[Microsoft アプリ ID] の横にある [管理] を選択して、App Service の [証明書 + シークレット] ブレードに移動します。
ブレードの指示に従って新しいクライアントシークレットを作成し、安全な場所に値を記録します。

Microsoft Entra ID ID サービス

Microsoft Entra ID は、OAuth 2.0 などの業界標準プロトコルを使用して、ユーザーを安全にサインインさせるアプリケーションをビルドすることができるクラウド ID サービスです。

次の 2 つの ID サービスのいずれかを使用できます。

Microsoft Entra ID 開発者プラットフォーム (v1.0)。 Azure AD v1エンドポイントとも呼ばれ、Microsoft の職場または学校アカウントを使用してユーザーを安全にサインインさせるアプリを構築できます。詳細については、「開発者向け Microsoft Entra ID (v1.0)」を参照してください。
Microsoft ID プラットフォーム (v2.0)。 Microsoft Entra ID エンドポイントとも呼ばれる、Azure AD プラットフォーム (v1.0) の進化版です。これにより、すべての Microsoft ID プロバイダーにサインインして、Microsoft API (Microsoft Graph など) や開発者が構築した他の API を呼び出すためにトークンを取得するアプリケーションを構築できます。詳細については、「Microsoft ID プラットフォーム (v2.0) の概要」を参照してください。

v1 と v2 エンドポイントの違いについては、「Microsoft ID プラットフォーム (v2.0) に更新する理由」を参照してください。全情報については、「Microsoft ID プラットフォーム (旧「開発者向け Microsoft Entra ID」)」を参照してください。

Microsoft Entra ID ID プロバイダーを作成する

このセクションでは、OAuth 2.0 を使用してボットを認証する Microsoft Entra ID ID プロバイダーを作成する方法について説明します。 Azure AD v1 または Microsoft Entra ID エンドポイントを使用できます。

ヒント

アプリケーションによって要求されたアクセス許可を委任することに同意できる、テナントで Microsoft Entra ID アプリケーションを作成し、登録する必要があります。

Azure portal で Microsoft Entra ID パネルを開きます。適切なテナントにいない場合は、[ディレクトリの切り替え] を選択して適切なテナントに切り替えます。 (テナントを作成する方法については、「ポータルへのアクセスとテナントの作成」を参照してください。)
[アプリの登録] パネルを開きます。
[アプリの登録] パネルで、[新規登録] を選択します。
必須のフィールドに入力してアプリ登録を作成します。
1. アプリケーションに名前を付けます。
2. ご自分のアプリケーションについて、[サポートされているアカウントの種類] を選択します。 (このサンプルは、これらのオプションのどれを使用しても動作します。)
3. [リダイレクト URI] で [ウェブ] を選択し、サポートされている OAuth リダイレクト URL のいずれかに URL を設定します。
4. 登録を選択します。
  - アプリが作成された後、そのアプリの [概要] ページが Azure に表示されます。
  - [アプリケーション (クライアント) ID] の値を記録します。この値は、後で接続文字列を作成し、Microsoft Entra ID プロバイダーをボット登録に登録するときにクライアント ID として使用します。
  - [ディレクトリ (テナント) ID] の値を記録します。この値は、このアプリケーションを自分のボットに登録する際に使用します。
ナビゲーションウィンドウで [認定資格書とシークレット] を選択して、自分のアプリケーションのシークレットを作成します。
1. [クライアントシークレット] で、 [新しいクライアントシークレット] を選択します。
2. 説明を追加します (bot login など)。必要に応じてこのアプリのために作成する他のシークレットからこれを識別するためです。
3. [期限切れ] で、シークレットの有効期限が切れる期間を選択します。
4. [追加] を選択します。
5. [認定資格証とシークレット] を離れる前に、シークレットを記録します。この値は、後で Microsoft Entra ID アプリケーションをご自身のボットに登録するときに、"クライアントシークレット" として使用します。
ナビゲーションウィンドウで、[API のアクセス許可] を選択し、[API のアクセス許可] パネルを開きます。アプリの API アクセス許可を明示的に設定するのが成功事例です。
1. [アクセス許可の追加] を選択し、[API アクセス許可の要求] ウィンドウを表示します。
2. このサンプルでは、[Microsoft API] と [Microsoft Graph] を選択します。
3. [委任されたアクセス許可] を選択し、必要とするアクセス許可が選択されていることを確認します。このサンプルでは、これらのアクセス許可が必要です。
  
  Note
  
  [管理者の同意が必要] とマークされているアクセス許可は、ユーザーとテナント管理者の両方がログインすることを要求するため、ボットではこれらのアクセス許可を避けるのが一般的です。
  - openid
  - profile
  - Mail.Read
  - Mail.Send
  - User.Read
  - User.ReadBasic.All
4. アクセス許可の追加 を選択します。 (ユーザーは、ボットを通じてこのアプリに初めてアクセスする際に、同意を付与する必要があります。)

これで、Microsoft Entra ID アプリケーションが構成されました。

Note

接続文字列を作成し、ID プロバイダーをボット登録に登録するときに、アプリケーション (クライアント) ID とクライアントシークレットを割り当てます。次のセクションをご覧ください。

Microsoft Entra ID ID プロバイダーをボットに登録する

次の手順では、ID プロバイダーをボットに登録します。

Microsoft Entra ID
Azure AD v1

Azure Portal でボットの Azure ボットリソースページを開きます。
設定を選択します。
ページ下部付近にある [OAuth 接続設定] で、[設定の追加] を選択します。
次のようにフォームに入力します。
1. 名前。接続の名前を入力します。ボットのコードで使用します。
2. サービスプロバイダー。 Microsoft Entra ID を選択して、Microsoft Entra ID 固有のフィールドを表示します。
3. クライアント ID。Microsoft Entra ID ID プロバイダー用に記録したアプリケーション (クライアント) ID を入力します。
4. クライアントシークレット。 Microsoft Entra ID ID プロバイダー用に記録したシークレットを入力します。
  
  ヒント
  
  証明書を使用する場合は、証明書プロバイダーで AAD v2 を選択することができます。ボットサービストークンストア (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) に証明書を取得するアクセス許可を付与する必要があります。
5. トークン交換 URL。 Microsoft Entra ID の SSO にのみ使用されるため、空白のままにします。
6. テナント ID。 Azure AD アプリを作成したときに選択したサポートされるアカウントの種類に基づいて、Microsoft Entra ID アプリ用に前に記録した[ディレクトリ (テナント) ID] を入力するか、ディレクトリ (テナント) ID を入力するか、「common」と入力します。割り当てる値を決定するには、次の条件に従います。
  - Microsoft Entra ID アプリの作成時に、[(この組織ディレクトリ内のアカウントのみ (Microsoft のみ - シングルテナント))] を選択した場合、Microsoft Entra ID アプリ用に前に記録したテナント ID を入力します。
  - ただし、[任意の組織のディレクトリ内のアカウント (任意の Microsoft Entra ID ディレクトリ - マルチテナントと個人の Microsoft アカウント (Xbox、Outlook.com など)] または [任意の組織ディレクトリ内のアカウント (Microsoft Azure AD ディレクトリ - マルチテナント)] を選択した場合は、テナント ID の代わりに「common」と入力します。それ以外の場合、Microsoft Entra ID アプリは ID が選択されているテナントを通じて検証され、個人の Microsoft アカウントは除外されます。
  これは、認証可能なユーザーに関連付けられるテナントになります。詳細については、Microsoft Entra ID のテナントに関する説明を参照してください。
7. [スコープ] には、アプリケーションの登録から選択したアクセス許可の名前を入力します。テスト目的の場合は、「openid profile」とのみ入力します。
  
  Note
  
  Microsoft Entra ID の場合、[スコープ] フィールドはスペースで区切った値のリストであり、大文字と小文字が区別されます。
[保存] を選択します。

[Azure Portal] で、ボットのリソースページに移動します。
設定を選択します。
ページ下部付近にある [OAuth 接続設定] で、[設定の追加] を選択します。
次のようにフォームに入力します。
1. [名前] に、接続の名前を入力します。この名前はご自身のボットコードで使用します。
2. サービスプロバイダー: Microsoft Entra ID を選択します。これを選択すると、Microsoft Entra ID に固有のフィールドが表示されます。
3. [クライアント ID] に、Azure AD v1 アプリケーションの設定時に記録したアプリケーション (クライアント) ID を入力します。
4. [クライアントシークレット] に、作成したシークレットを入力して、Microsoft Entra ID アプリへのアクセスをボットに許可します。
5. [付与タイプ] に、authorization_code と入力します。
6. [ログイン URL] に、https://login.microsoftonline.com と入力します。
7. [テナント ID] には、Microsoft Entra ID アプリを作成したときに選択したサポートされるアカウントの種類に基づいて ディレクトリ (テナント) ID を入力するか、「common」と入力します。割り当てる値を決定するには、次の条件に従います。
  - Microsoft Entra ID アプリの作成時に、[(この組織ディレクトリ内のアカウントのみ (Microsoft のみ - シングルテナント))] を選択した場合、Microsoft Entra ID アプリ用に前に記録したテナント ID を入力します。
  - ただし、[任意の組織のディレクトリ内のアカウント (任意の Microsoft Entra ID ディレクトリ - マルチテナントと個人の Microsoft アカウント (Xbox、Outlook.com など)] または [任意の組織ディレクトリ内のアカウント (Microsoft Azure AD ディレクトリ - マルチテナント)] を選択した場合は、テナント ID の代わりに「common」と入力します。それ以外の場合、Microsoft Entra ID アプリは ID が選択されているテナントを通じて検証され、個人の MS アカウントは除外されます。
  これは、認証可能なユーザーに関連付けられるテナントになります。詳細については、Microsoft Entra ID のテナントに関する説明を参照してください。
8. リソース URL には、https://graph.microsoft.com/ と入力します。
9. [スコープ] は空白のままにします。
[保存] を選択します。

Note

これらの値によって、アプリケーションは Microsoft Graph API 経由で Office 365 データにアクセスできます。また、[トークン交換 URL] は、Microsoft Entra ID でのみ SSO に使用されるため、空白のままにしておく必要があります。

接続のテスト

接続入力を選択して、作成した接続を開きます。
[サービスプロバイダー接続設定] ウィンドウの上部にある [テスト接続] を選択します。
初回は新しいブラウザータブが開き、アプリが要求しているアクセス許可の一覧が表示され、承認を求められます。
承諾を選択します。
これにより、[<your-connection-name> への接続テストに成功しました] ページにリダイレクトされます。

ボットコードでこの接続名を使用してユーザートークンを取得できるようになりました。

ボットコードを準備する

このプロセスを完了するには、ボットのアプリ ID とパスワードが必要になります。

使用するサンプルのクローンを GitHub リポジトリから作成します:ボット認証またはMicrosoft Graph 用ボット認証.

appsettings.json を更新します。

ConnectionName を、お使いのボットに追加した OAuth 接続設定の名前に設定します。
MicrosoftAppId および MicrosoftAppPassword を、お使いのボットのアプリ ID とアプリシークレットに設定します。

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

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

パブリッククラウドのデータ所在地を持つボットで OAuth を使用するには、appsettings に次の構成を追加する必要があります

"OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

<Regional-OAuth-Url> は、次のいずれかの URI です。

URI	説明
`https://europe.api.botframework.com`	ヨーロッパにデータ所在地があるパブリッククラウドボットの場合。
`https://unitedstates.api.botframework.com`	米国にデータ所在地があるパブリッククラウドボットの場合。
`https://india.api.botframework.com`	インドにデータ所在地があるパブリッククラウドボットの場合。

Startup.cs の更新:

政府機関向けクラウドなど、パブリックではない Azure クラウドで OAuth を使用するには、Startup.cs ファイルに次のコードを追加する必要があります。

string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

ここでにある <uri-to-use> は次のいずれかの URI です。

URI	説明
`https://api.botframework.azure.us`	データ所在地のない米国政府機関向けクラウドボットの場合。
`https://api.botframework.com`	データ所在地のないパブリッククラウドボットの場合。これはデフォルト URI であり、Startup.cs を変更する必要はありません。

使用したい GitHub リポジトリからクローンします:ボット認証またはMicrosoft Graph 用ボット認証.
.env を更新します。
- connectionName を、お使いのボットに追加した OAuth 接続設定の名前に設定します。
- MicrosoftAppId および MicrosoftAppPassword の値を、お使いのボットのアプリ ID とアプリシークレットに設定します。
  
  お使いのボットシークレットに含まれる文字によっては、パスワードを XML でエスケープすることが必要な場合があります。たとえば、アンパサンド (&) は & のようにエンコードする必要があります。
```
MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
connectionName=
```

使用するサンプルのクローンを GitHub リポジトリから作成します:ボット認証またはMicrosoft Graph 用ボット認証.
application.properties の更新:
- ConnectionName を、お使いのボットに追加した OAuth 接続設定の名前に設定します。
- MicrosoftAppId および MicrosoftAppPassword を、お使いのボットのアプリ ID とアプリシークレットに設定します。
```
MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
ConnectionName=
```

使用するサンプルのクローンを GitHub リポジトリから作成します:ボット認証またはMicrosoft Graph 用ボット認証.
config.py を更新します。
- ConnectionName を、お使いのボットに追加した OAuth 接続設定の名前に設定します。
- MicrosoftAppId および MicrosoftAppPassword を、お使いのボットのアプリ ID とアプリシークレットに設定します。
  
  お使いのボットシークレットに含まれる文字によっては、パスワードを XML でエスケープすることが必要な場合があります。たとえば、アンパサンド (&) は & のようにエンコードする必要があります。
```
#!/usr/bin/env python3
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.

import os

""" Bot Configuration """


class DefaultConfig:
    """ Bot Configuration """

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

Microsoft アプリ ID と Microsoft アプリパスワードの値を取得するには、「登録パスワードの取得」を参照してください。

Note

ここで、このボットコードを Azure サブスクリプションに発行 (プロジェクトを右クリックして [発行] を選択) することもできますが、この記事では不要です。 Azure portal でボットを構成するときに使用したアプリケーションとホスティングプランを使用する発行構成を設定する必要があります。

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

Bot Framework Emulator をインストールします (まだインストールしていない場合)。「エミュレーターを使用したデバッグ」もご覧ください。

ボットサンプルログインを機能させるには、「認証用にエミュレーターを構成する」に示されているようにエミュレーターを構成する必要があります。

テスト

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

Note

ボットサンプルの実装方法により、”マジックコード" を入力するように求められる場合があります。このマジックコードは RFC # 7636 の一部であり、さらなるセキュリティ要素を追加するために用意されています。マジックコードを削除すると、セキュリティ上のリスクが高まります。これは、強化された認証が有効になっている Direct Line を使用することで軽減できます。詳細については、「Bot Framework の強化された認証」を参照してください。

お使いのマシン上でローカルでボットサンプルを実行します。
エミュレーターを起動します。
ボットに接続するときに、ボットのアプリ ID とパスワードを入力する必要があります。
- Azure アプリの登録からアプリ ID とパスワードを取得します。これらは、appsettings.json または .env ファイルでボットアプリに割り当てたものと同じ値です。エミュレーターで、これらの値を構成ファイルで、または初めてボットに接続するときに割り当てます。
- ボットコード内のパスワードを XML エスケープする必要がある場合は、ここでもそれを行う必要があります。
help と入力すると、ボットで使用できるコマンドの一覧が表示され、認証機能をテストします。
サインインした後は、サインアウトするまで、資格情報を再度入力する必要はありません。
サインアウトして認証をキャンセルするには、logout と入力します。

Note

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

認証の例

ボット認証サンプルでは、ダイアログは、ユーザーのログイン後、ユーザートークンを取得するように設計されています。

Sample conversation with the authentication sample bot.

Microsoft Graph 用認証の例

Microsoft Graph 用ボット認証サンプルでは、ダイアログは、ユーザーのログイン後、制限された一部のコマンドを受け取るように設計されています。

Sample conversation with the Microsoft Graph authentication sample bot.

追加情報

ユーザーがボットに何らかの処理を要求し、それによってボットでユーザーのログインが必要になった場合、ボットによって OAuthPrompt が使用され、特定の接続に必要なトークンの取得が開始されます。 OAuthPrompt では、以下で構成されるトークン取得フローが作成されます。

既に Azure AI Bot Service に現在のユーザーおよび接続用のトークンがあるかどうかを確認するためのチェック。トークンがある場合は、そのトークンが返されます。
キャッシュされたトークンが Azure AI Bot Service にない場合は、OAuthCard が作成されます。これは、ユーザーがクリックできるログインボタンです。
ユーザーが OAuthCard ログインボタンをクリックしたら、Azure AI Bot Service によって、ユーザーのトークンがボットに直接送信されます。または、チャットウィンドウに 6 桁の認証コードがユーザーに表示されます。
ユーザーに認証コードが表示される場合は、ボットによって、この認証コードがユーザーのトークンと交換されます。

次のセクションでは、一般的な認証タスクが、サンプルによってどのように実装されているかを説明します。

OAuth プロンプトを使用してユーザーをサインインさせて、トークンを取得する

Architecture diagram for the C# sample.

Dialogs\MainDialog.cs

OAuth プロンプトを、コンストラクター内の MainDialog に追加します。ここでは、接続名の値は appsettings.json ファイルから取得されました。

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

ダイアログステップ内で、BeginDialogAsync を使用して OAuth プロンプトを起動します。これによりユーザーのサインインが求められます。

ユーザーがサインイン済みの場合は、ユーザーに問い合わせることなく、トークン応答イベントが生成されます。
それ以外の場合は、ユーザーのサインインが求められます。ユーザーがログインを試みた後、Azure AI Bot Service からトークン応答イベントが送信されます。

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

次のダイアログステップ内で、前のステップの結果としてトークンが存在することを確認します。 null でない場合、ユーザーは正常にログインしています。

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

Architecture diagram for the JavaScript sample.

dialogs/mainDialog.js

OAuth プロンプトを、コンストラクター内の MainDialog に追加します。ここでは、接続名の値は .env ファイルから取得されました。

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

ダイアログステップ内で、beginDialog を使用して OAuth プロンプトを起動します。これによりユーザーのサインインが求められます。

ユーザーがサインイン済みの場合は、ユーザーに問い合わせることなく、トークン応答イベントが生成されます。
それ以外の場合は、ユーザーのサインインが求められます。ユーザーがログインを試みた後、Azure AI Bot Service からトークン応答イベントが送信されます。

const tokenResponse = stepContext.result;

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

Architecture diagram for the Java sample.

MainDialog.java

OAuth プロンプトを、コンストラクター内の MainDialog に追加します。ここでは、接続名の値は appsettings.json ファイルから取得されました。

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

ダイアログステップ内で、beginDialog を使用して OAuth プロンプトを起動します。これによりユーザーのサインインが求められます。

ユーザーがサインイン済みの場合は、ユーザーに問い合わせることなく、トークン応答イベントが生成されます。
それ以外の場合は、ユーザーのサインインが求められます。ユーザーがログインを試みた後、Azure AI Bot Service からトークン応答イベントが送信されます。

return stepContext.beginDialog("OAuthPrompt");

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

Architecture diagram for the Python sample.

dialogs/main_dialog.py

OAuth プロンプトを、コンストラクター内の MainDialog に追加します。ここでは、接続名の値は config.py ファイルから取得されました。

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

ダイアログステップ内で、begin_dialog を使用して OAuth プロンプトを起動します。これによりユーザーのサインインが求められます。

ユーザーがサインイン済みの場合は、ユーザーに問い合わせることなく、トークン応答イベントが生成されます。
それ以外の場合は、ユーザーのサインインが求められます。ユーザーがログインを試みた後、Azure AI Bot Service からトークン応答イベントが送信されます。

return await step_context.begin_dialog(OAuthPrompt.__name__)

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?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

TokenResponseEvent の待機

OAuth プロンプトを起動すると、そのプロンプトは、ユーザーのトークン取得元となるトークン応答イベントを待ちます。

Bots\AuthBot.cs

AuthBot は ActivityHandler から派生し、トークン応答イベントアクティビティを明示的に処理します。ここではアクティブなダイアログを続行します。これにより OAuth プロンプトでイベントを処理し、トークンを取得できます。

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

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

bots/authBot.js

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot は Dialog から派生し、トークン応答イベントアクティビティを明示的に処理します。ここではアクティブなダイアログを続行します。これにより OAuth プロンプトでイベントを処理し、トークンを取得できます。

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot は、トークン応答イベントアクティビティを明示的に処理します。ここではアクティブなダイアログを続行します。これにより OAuth プロンプトでイベントを処理し、トークンを取得できます。

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

ユーザーをログアウトする

接続のタイムアウトを使用するのではなく、ユーザーが明示的にログアウトできるようにすることをお勧めします。

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

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();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        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()

Teams 認証の追加

OAuth は、Teams では他のチャンネルとは異なる方法で処理されます。 Teams 認証ボットのサンプル (C#、JavaScript、Java、または Python) は、Teams の認証を適切に実装する方法を示しています。

参考資料

「Bot Framework のその他のリソース」に追加サポートのリンクがあります。
Bot Framework SDK のリポジトリでは、Bot Builder SDK に関連付けられているリポジトリ、サンプル、ツール、および仕様の詳細を確認できます。

ボットに認証を追加する

Web チャットと Direct Line に関する考慮事項

前提条件

リソースを作成する

ボット ID 情報

App Service を更新するには

アプリまたはテナント ID を取得するには

新しいパスワードを生成するには

Microsoft Entra ID ID サービス

Microsoft Entra ID ID プロバイダーを作成する

Microsoft Entra ID ID プロバイダーをボットに登録する

接続のテスト

ボット コードを準備する

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

テスト

認証の例

Microsoft Graph 用認証の例

追加情報

OAuth プロンプトを使用してユーザーをサインインさせて、トークンを取得する

TokenResponseEvent の待機

ユーザーをログアウトする

Teams 認証の追加

参考資料

その他のリソース

ボットコードを準備する