ボットに認証を追加するAdd authentication to a bot

適用対象: SDK v4APPLIES TO: SDK v4

Azure Bot Service v4 SDK を使用すると、ユーザー認証を必要とするオンライン リソースにアクセスできるボットの開発が容易になります。The Azure Bot Service v4 SDK facilitates the development of bots that can access online resources that require user authentication. Azure では OAuth 2.0 を使用して、各ユーザーの資格情報に基づいてトークンを生成するために認証トークンが自動的に実行されるので、ボットで認証トークンを管理する必要はない。Your bot does not need to manage authentication tokens because Azure does it for you using OAuth 2.0 to generate a token based on each user's credentials. ボットでは、Azure によって生成されたトークンを使用して、それらのリソースにアクセスします。Your bot uses the token generated by Azure to access those resources. この方法では、ユーザーはセキュリティで保護されたリソースにアクセスするための ID とパスワードをボットに提供する必要はありません。信頼できる ID プロバイダーにのみ提供します。In this way, the user does not have to provide ID and password to the bot to access a secured resource but only to a trusted identity provider.

この種の認証をBot Framework方法の概要については、「ユーザー認証」を 参照してくださいFor an overview of how the Bot Framework handles this kind of authentication, see User authentication.

注意

認証は、BotBuilder v3 でも機能します。Authentication also works with BotBuilder v3. ただし、この記事では v4 サンプル コードのみを扱います。However, this article covers just the v4 sample code.

この記事では、2 つのサンプルを参照します。This article references two samples. 1 つは、認証トークンを取得する方法を示しています。One shows how to obtain an authentication token. もう 1 つの方が複雑で、ユーザーに代わって Microsoft Graphアクセスする 方法を示しています。The other is more complex and shows how to access Microsoft Graph on behalf of the user. どちらの場合も、ID プロバイダーとして Azure Active Directory (AD) v1 または Azure AD v2 を使用して、ボットの OAuth トークンを取得できます。In both cases you can use Azure Active Directory (AD) v1 or Azure AD v2 as an identity provider to obtain an OAuth token for the bot. この記事では、次の方法について説明します。This article covers how to:

この記事を完了すると、いくつかの単純なタスクに応答できるボットが完成します。Once you finish this article, you will have a bot that can respond to a few simple tasks. Microsoft Graph の例の場合は、メールの送信、自分の情報の表示、最新のメールの確認を行えます。In the case of the Microsoft Graph example, you can send an email, display who you are, and check recent emails. OAuth の機能をテストするためにボットを公開する必要はありませんが、ボットには有効な Azure アプリ ID とパスワードが必要になります。You do not need to publish the bot to test the OAuth features; however, the bot will need valid Azure app ID and password.

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

重要

セキュリティコントロールを使用してボットDirect Line接続するときにセキュリティ 上のリスクを軽減するには、強化された認証を有効にしたWeb チャットがあります。You need to use Direct Line with enhanced authentication enabled to mitigate security risks when connecting to a bot using the Web Chat control. 詳細については、「拡張認証のDirect Line を参照してくださいFor more information, see Direct Line enhanced authentication.

前提条件Prerequisites

サンプルSample BotBuilder のバージョンBotBuilder version 対象Demonstrates
C# または JavaScript または Javaまたは Python での認証Authentication in C# or JavaScript or Java or Python v4v4 OAuthCard サポートOAuthCard support
C#または JavaScriptまたは Java または Python での認証 MSGraphAuthentication MSGraph in C# or JavaScript or Java or Python v4v4 OAuth 2 を使用した Microsoft Graph API サポートMicrosoft Graph API support with OAuth 2

サンプルについてAbout the samples

この記事で参照しているサンプルを実行するには、次のものが必要です。To run the samples referenced in this article, you need the following:

  1. Azure でボット リソースを登録するための Azure Active Directory (AD) アプリケーション。An Azure Active Directory (AD) application to register a bot resource in Azure. このアプリケーションを使用すると、ボットはMicrosoft Graph などのセキュリティで保護された外部リソースにアクセスできます。This application allows the bot to access an external secured resource, such as Microsoft Graph. また、ユーザーは Web チャットなどの複数のチャネルを介してボットと通信できます。It also allows the user to communicate with the bot via several channels such as Web Chat.
  2. ID プロバイダーとして機能する個別の Azure AD アプリケーション。A separate Azure AD application that functions as the identity provider. このアプリケーションは、ボットとセキュリティで保護されたリソースの間で OAuth 接続を確立するために必要な資格情報を提供します。This application provides the credentials needed to establish an OAuth connection between the bot and the secured resource. この記事では、ID プロバイダーとして Active Directory を使用することに注意してください。Notice that this article uses Active Directory as an identity provider. 他にも多くのプロバイダーがサポートされています。Many other providers are also supported.

重要

Azure でボットを登録すると必ず、Azure AD アプリケーションが割り当てられますが、Whenever you register a bot in Azure, it gets assigned an Azure AD application. このアプリケーションで保護されるのは、チャネルからボットへのアクセスです。However, this application secures channel-to-bot access. ユーザーに代わってボットがアクセスする外部のセキュリティで保護されたリソースごとに、追加の Azure AD アプリケーションが必要です。You need an additional Azure AD application for each external secured resource you want the bot to access on behalf of the user.

Azure Bot リソースを作成するCreate an Azure Bot resource

Azure Bot リソースを使用すると、Bot Framework Composerまたは SDK ボットを Azure Bot Service。The Azure Bot resource enables you to register your Bot Framework Composer or SDK bot in Azure Bot Service. ボットを構築、接続、管理して、アプリや Web サイトから Teams、Messenger、その他多くのチャネルまで、どこにいてもユーザーと対話できます。You can build, connect, and manage bots to interact with your users wherever they are, from your app or website to Teams, Messenger and many other channels.

警告

Web アプリボットボットチャネルの登録 は非推奨とされますが、既存のリソースは引き続き機能します。Web App Bot and Bot Channels Registration will be deprecated but existing resources will continue to work. 代わりに、 Azure Bot を使用する必要があります。You should use Azure Bot, instead.

  1. Azure ポータルにアクセスします。Go to the Azure portal.

  2. 右側のウィンドウで、[リソースの作成 ] を選択しますIn the right pane, select Create a resource.

  3. 検索ボックスに「bot」と 入力し、Enter キーを 押しますIn the search box enter bot, then press Enter.

  4. Azure Bot カードを選択 します。Select the Azure Bot card.

    Azure ボット リソースを選択する

  5. [作成] を選択しますSelect Create.

    Azure ボット リソースを作成する

  6. 必要な値を入力します。Enter the required values. 次の図は、[ 新しい Microsoft アプリ ID の作成] が選択されている のを示しています。The following figure shows Create new Microsoft App ID selected.

    Azure ボット リソースの値を作成する

    [既存のアプリの 登録を使用する] を選択し 、既存のアプリ ID と パスワードを 入力 することもできますYou can also select Use existing app registration and enter your existing app Id and password.

    Azure ボット リソースの既存の値を作成する

  7. [Review + create](レビュー + 作成) を選択します。Select Review + create.

  8. 検証に合格した場合は、 [作成] を 選択しますIf the validation passes, select Create.

  9. [リソース グループに移動] を選択します。Select Go to resource group. 選択したリソース グループに、ボット と関連Azure Key Vault リソースが一覧表示されます。You should see the bot and the related Azure Key Vault resources listed in the resource group you selected.

    ヒント

    アプリ シークレット (パスワード) はキー コンテナーに格納され、リソース グループごとに 1 つのキー コンテナーがあります。The app secret (password) is stored in the the key vault and there is one key vault per resource group. 機密データをコピーして格納する代わりに、キー コンテナーの使用をお勧めします。Using key vault is recommended instead of copying and storing sensitive data.

  10. [Composer で開く] を選択しますSelect Open in Composer. これは、ボット開発を初め、または新しいボットを構築する場合に推奨されるパスです。This is the recommended path, if you are new to bot development or if you are building a brand new bot. Composer でのボットの作成に関 する記事で説明されている手順に従 います。Follow the steps described in the Create a bot in Composer article.

    Composer で bot を作成する

    必要に応じて、[ Github から SDK を取得 する] を選択して BOT Framework sdk を使用して bot をビルドします。これは、小さなチャットボットから世界クラスのエンタープライズソリューションまで、あらゆるものを作成するのに役立ちます。Optionally, select Get the SDK from Github to build your bot with the Bot Framework SDK that helps you create everything from a modest chatbot to world class, enterprise solutions.

    SDK でボットを作成する

Azure Key Vault についてAbout Azure Key Vault

Azure Key Vault は、アクセス ポリシーと監査履歴を完全制御する、一元化されたシークレット管理を提供するサービスです。Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history. 詳細については、「App Service と Azure Functions の Key Vault 参照を使用する」を参照してください。For more information, see Use Key Vault references for App Service and Azure Functions. サービスの使用については、わずかな料金が請求されます。詳細については、「 Key Vault の価格」を参照してください。Note that you will be charged a small fee for using the service, For more information, see Key Vault pricing.

アプリ ID とパスワードApp Id and password

デプロイ用にボットを構成 するには、Azure ボット リソース アプリ ID とパスワードが必要です。 You need the Azure bot resource app Id and password to configure your bot for deployment. 関連する変数 (およびボット プロジェクト構成ファイルに含まれている) にそれらの値 MicrosoftAppId MicrosoftAppPassword を割り当てる必要があります。You will assign their values to the related variables: MicrosoftAppId and MicrosoftAppPassword contained in your bot project configuration file. ファイルは、次の表に示すように、ボットの作成に使用するプログラミング言語によって異なります。The file differs depending on the programming language you use to create the bot, as shown in the table below.

言語Language ファイル名File Name
CsharpCsharp appsettings.json
JavaScriptJavaScript .env
PythonPython config.py
JavaJava application.properties

Azure ボット リソース アプリ ID を取得するGet Azure bot resource app Id

  1. Azure ポータルにアクセスします。Go to the Azure portal.
  2. Azure ボット リソースを選択して、そのアプリ ID を取得します。Select the Azure bot resource to obtain its app Id.
  3. 左側のウィンドウの [設定] セクション で、[ 構成] を 選択しますIn the left pane, in the Settings section, select Configuration.
  4. [Microsoft アプリ ID] ボックスに含まれている値 をコピーして保存 します。Copy and save the value contained in the Microsoft App ID box.

Azure Key Vault から Azure ボット リソースのパスワードを取得するGet Azure bot resource password from the Azure key vault

リソースに アクセスしてAzure Key Vault パスワードを取得できます。You can access the Azure Key Vault to obtain your resource stored password. Azure Key Vault は、アクセス ポリシーと監査履歴を完全制御する、一元化されたシークレット管理を提供するサービスです。Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history. Fpr の詳細については、「Key Vaultの参照App Service使用Azure Functions。Fpr more information, see Use Key Vault references for App Service and Azure Functions.

関連情報Additional information

Azure AD ID サービスAzure AD identity service

Azure Active Directory (Azure AD) は、OAuth 2.0 などの業界標準プロトコルを使用して、ユーザーを安全にサインインさせるアプリケーションを構築できるクラウド ID サービスです。The Azure Active Directory (Azure AD) is a cloud identity service that allows you to build applications that securely sign in users using industry standard protocols like OAuth2.0.

次の 2 つの ID サービスのいずれかを使用できます。You can use one of these two identity services:

  1. Azure AD 開発者プラットフォーム (v1.0)。Azure AD developer platform (v1.0). Azure AD v1 エンドポイントとも呼ばれ、Microsoft の職場または学校アカウントを使用してユーザーを安全にサインインさせるアプリを構築できます。Also known as the Azure AD v1 endpoint, which allows you to build apps that securely sign in users with a Microsoft work or school account. 詳細については、「開発者向け Azure Active Directory (v1.0) の概要」を参照してください。For more information, see the Azure Active Directory for developers (v1.0) overview.
  2. Microsoft ID プラットフォーム (v2.0)。Microsoft identity platform (v2.0). Azure AD v2 エンドポイントとも呼ばれ、Azure AD プラットフォーム (v1.0) の進化版です。Also known as the Azure AD v2 endpoint, which is an evolution of the Azure AD platform (v1.0). これにより、すべての Microsoft ID プロバイダーにサインインして、Microsoft API (Microsoft Graph など) や開発者が構築した他の API を呼び出すためにトークンを取得するアプリケーションを構築できます。It allows you to build applications that sign in to all Microsoft identity providers and get tokens to call Microsoft APIs, such as Microsoft Graph, or other APIs that developers have built. 詳細については、「Microsoft ID プラットフォーム (v2.0) の概要」を参照してください。For more information, see the Microsoft identity platform (v2.0) overview,

v1 と v2 エンドポイントの違いについては、「Microsoft ID プラットフォーム (v2.0) に更新する理由」を参照してください。For information about the differences between the v1 and v2 endpoints, see Why update to Microsoft identity platform (v2.0)?. 完全な情報については、Microsoft ID プラットフォーム (旧称: 開発者向け Azure Active Directory) に関する記事を参照してください。For complete information, see Microsoft identity platform (formerly Azure Active Directory for developers).

ID プロバイダー Azure AD作成するCreate the Azure AD identity provider

このセクションでは、OAuth2 を使用してボットAzure AD ID プロバイダーを作成する方法について説明します。This section shows how to create an Azure AD identity provider that uses OAuth2 to authenticate the bot. Azure AD v1 または Azure AD v2 エンドポイントを使用できます。You can use Azure AD v1 or Azure AD v2 endpoints.

ヒント

アプリケーションによって要求されたアクセス許可を委任することに同意できる、テナントで Azure AD プリケーションを作成し、登録する必要があります。You will need to create and register the Azure AD application in a tenant in which you can consent to delegate permissions requested by an application.

  1. Azure portal で [Azure Active Directory] パネルを開きます。Open the Azure Active Directory panel in the Azure portal. 適切なテナントにいない場合は、 [ディレクトリの切り替え] をクリックして適切なテナントに切り替えますIf you are not in the correct tenant, click Switch directory to switch to the correct tenant. (テナントを作成する方法については、ポータルへのアクセスとテナントの作成に関するページをご覧ください)。(For instruction on creating a tenant, see Access the portal and create a tenant.)

  2. [アプリの登録] パネルを開きます。Open the App registrations panel.

  3. [アプリの登録] パネルで、 [新規登録] をクリックします。In the App registrations panel, click New registration.

  4. 必須のフィールドに入力してアプリ登録を作成します。Fill in the required fields and create the app registration.

    1. アプリケーションに名前を付けます。Name your application.

    2. ご自分のアプリケーションについて、 [サポートされているアカウントの種類] を選択します。Select the Supported account types for your application. (このサンプルは、これらのオプションのどれを使用しても動作します。)(Any of these options will work with this sample.)

    3. [リダイレクト URI]For the Redirect URI

      1. [Web] を選択します。Select Web.
      2. URL を https://token.botframework.com/.auth/web/redirect に設定します。Set the URL to https://token.botframework.com/.auth/web/redirect.
    4. [登録] をクリックします。Click Register.

      • アプリが作成された後、その [概要] ページが Azure によって表示されます。Once it is created, Azure displays the Overview page for the app.
      • [アプリケーション (クライアント) ID] の値を記録します。Record the Application (client) ID value. この値は、後で接続文字列を作成し、ボット登録に Azure ADプロバイダーを登録するときにクライアント ID として使用します。You will use this value later as the Client id when you create the connection string and register the Azure AD provider with the bot registration.
      • さらに、 [ディレクトリ (テナント) ID] の値を記録します。Also record the Directory (tenant) ID value. また、これを使用して、このプロバイダー アプリケーションをボットに登録します。You will also use this to register this provider application with your bot.
  5. ナビゲーション ウィンドウで [証明書とシークレット] をクリックして、自分のアプリケーションのシークレットを作成します。In the navigation pane, click Certificates & secrets to create a secret for your application.

    1. [クライアント シークレット] で、 [新しいクライアント シークレット] をクリックします。Under Client secrets, click New client secret.
    2. 説明を追加します (bot login など)。必要に応じてこのアプリのために作成する他のシークレットからこれを識別するためです。Add a description to identify this secret from others you might need to create for this app, such as bot login.
    3. [期限][無期限] に設定します。Set Expires to Never.
    4. [追加] をクリックします。Click Add.
    5. このページを離れる前に、シークレットを記録してください。Before leaving this page, record the secret. この値は、後で Azure AD アプリケーションをご自身のボットに登録するときに、"クライアント シークレット" として使用します。You will use this value later as the Client secret when you register your Azure AD application with your bot.
  6. ナビゲーション ウィンドウで、 [API のアクセス許可] をクリックし、 [API のアクセス許可] パネルを開きます。In the navigation pane, click API permissions to open the API permissions panel. アプリの API アクセス許可を明示的に設定するのがベスト プラクティスです。It is a best practice to explicitly set the API permissions for the app.

    1. [アクセス許可の追加] をクリックし、 [API アクセス許可の要求] ウィンドウを表示します。Click Add a permission to show the Request API permissions pane.

    2. このサンプルでは、 [Microsoft API][Microsoft Graph] を選択します。For this sample, select Microsoft APIs and Microsoft Graph.

    3. [委任されたアクセス許可] を選択し、必要とするアクセス許可が選択されていることを確認します。Choose Delegated permissions and make sure the permissions you need are selected. このサンプルでは、これらのアクセス許可が必要です。This sample requires theses permissions.

      注意

      [管理者の同意が必要] とマークされているアクセス許可は、ユーザーとテナント管理者の両方がログインすることを要求するため、ボットではこれらのアクセス許可を避けるのが一般的です。Any permission marked as ADMIN CONSENT REQUIRED will require both a user and a tenant admin to login, so for your bot tend to stay away from these.

      • openidopenid
      • profileprofile
      • Mail.ReadMail.Read
      • Mail.SendMail.Send
      • User.ReadUser.Read
      • User.ReadBasic.AllUser.ReadBasic.All
    4. [アクセス許可の追加] をクリックします。Click Add permissions. (ユーザーは、ボットを通じてこのアプリに初めてアクセスする際に、同意を付与する必要があります。)(The first time a user accesses this app through the bot, they will need to grant consent.)

これで、Azure AD アプリケーションが構成されました。You now have an Azure AD application configured.

注意

接続文字列を作成 し、ID プロバイダー をボット登録に登録するときに、アプリケーション (クライアント) ID とクライアント シークレット を割り当てる必要があります。You will assign the Application (client) ID and the Client secret, when you create the connection string and register the identity provider with the bot registration. 次のセクションをご覧ください。See next section.

ボットにAzure AD ID プロバイダーを登録するRegister the Azure AD identity provider with the bot

次のステップでは、作成した Azure AD アプリケーションをボットに登録します。The next step is to register the Azure AD application that you just created with the bot.

Azure AD v2Azure AD v2

  1. Azure Portal で、ボットの [Bot Channels Registration](ボット チャネル登録) ページに移動します。Navigate to your bot's Bot Channels Registration page on the Azure Portal.

  2. [設定] をクリックします。Click Settings.

  3. ページ下部付近の [OAuth Connection Settings](OAuth 接続設定) で、 [設定の追加] をクリックします。Under OAuth Connection Settings near the bottom of the page, click Add Setting.

  4. 次のようにフォームに入力します。Fill in the form as follows:

    1. 名前Name. 接続の名前を入力します。Enter a name for your connection. ボットのコードで使用します。You'll use it in your bot code.

    2. サービス プロバイダーService Provider. v2 Azure Active Directoryを選択しますSelect Azure Active Directory v2. これを選択すると、Azure AD に固有のフィールドが表示されます。Once you select this, the Azure AD-specific fields will be displayed.

    3. クライアント ID。v2 ID プロバイダーに対して記録したアプリケーション (クライアント) ID Azure AD入力します。Client id. Enter the application (client) ID you recorded for your Azure AD v2 identity provider.

    4. クライアント シークレットClient secret. v2 ID プロバイダーに対して記録Azure ADを入力します。Enter the secret you recorded for your Azure AD v2 identity provider.

    5. トークン交換 URLToken Exchange URL. v2 の SSO にのみ使用されるので、Azure ADしておきます。Leave it blank because it is used for SSO in Azure AD v2 only.

    6. テナント IDTenant ID. Azure DD アプリの 作成時に選択したサポートされているアカウントの種類に応じて、前に AAD アプリ用に記録したディレクトリ (テナント) ID を入力するか、共通の ID を入力します。Enter the directory (tenant) ID that your recorded earlier for your AAD app or common depending on the supported account types selected when you created the Azure DD app. 割り当てる値を決定するには、次の条件に従います。To decide which value to assign follow these criteria:

      • Azure AD アプリの作成時に、 [Accounts in this organizational directory only (Microsoft only - Single tenant)](この組織ディレクトリ内のアカウントのみ (Microsoft のみ - シングル テナント)) を選択した場合、AAD アプリ用に前に記録した テナント ID を入力します。When creating the Azure AD app if you selected Accounts in this organizational directory only (Microsoft only - Single tenant) enter the tenant ID you recorded earlier for the AAD app.
      • ただし、 [Accounts in any organizational directory (Any AAD directory - Multi tenant and personal Microsoft accounts e.g. Xbox, Outlook.com)](任意の組織のディレクトリ内のアカウント (任意の AAD ディレクトリ - マルチテナントと個人の Microsoft アカウント (Xbox、Outlook.com など))) または [Accounts in any organizational directory(Microsoft Azure AD directory - Multi tenant)](任意の組織ディレクトリ内のアカウント (Microsoft Azure AD ディレクトリ - マルチテナント)) を選択した場合、テナント ID の代わりに「common」という語を入力します。However, if you selected Accounts in any organizational directory (Any AAD directory - Multi tenant and personal Microsoft accounts e.g. Xbox, Outlook.com) or Accounts in any organizational directory(Microsoft Azure AD directory - Multi tenant) enter the word common instead of a tenant ID. それ以外の場合、AAD アプリは ID が選択されているテナントを通じて検証され、個人の MS アカウントは除外されます。Otherwise, the AAD app will verify through the tenant whose ID was selected and exclude personal MS accounts.

      これは、認証可能なユーザーに関連付けられるテナントになります。This will be the tenant associated with the users who can be authenticated. 詳細については、「Azure Active Directory のテナント」をご覧ください。For more information, see Tenancy in Azure Active Directory.

    7. [ スコープ] には、アプリケーション登録から選択したアクセス許可の名前を入力します。For Scopes, enter the names of the permission you chose from the application registration. テスト目的の場合は、「 」と入力します openid profileFor testing purposes, you can just enter: openid profile.

      注意

      Azure AD v2 の場合、 [スコープ] フィールドはスペースで区切った値のリストであり、大文字と小文字が区別されます。For Azure AD v2, Scopes field takes a case-sensitive, space-separated list of values.

  5. [保存] をクリックします。Click Save.

注意

これらの値によって、アプリケーションは Microsoft Graph API 経由で Office 365 データにアクセスできます。These values enable your application to access Office 365 data via the Microsoft Graph API. また、 [Token Exchange URL](トークン交換 URL) は、Azure AD v2 でのみ SSO に使用されるため、空白のままにしておく必要があります。Also, the Token Exchange URL should be left blank because it is used for SSO in Azure AD v2 only.

接続をテストするTest your connection

  1. 接続エントリをクリックして、作成した接続を開きます。Click on the connection entry to open the connection you just created.
  2. [Service Provider Connection Setting](サービス プロバイダー接続設定) ウィンドウの上部にある [Test Connection](接続のテスト) をクリックします。Click Test Connection at the top of the Service Provider Connection Setting pane.
  3. 初回は新しいブラウザー タブが開き、アプリが要求しているアクセス許可の一覧が表示され、承認を求められます。The first time, this should open a new browser tab listing the permissions your app is requesting and prompt you to accept.
  4. [Accept](受け入れる) をクリックします。Click Accept.
  5. [<your-connection-name> への接続テストに成功しました] ページにリダイレクトされます。This should then redirect you to a Test Connection to <your-connection-name> Succeeded page.

ボット コードでこの接続名を使用してユーザー トークンを取得できるようになりました。You can now use this connection name in your bot code to retrieve user tokens.

ボット コードを準備するPrepare the bot code

このプロセスを完了するには、ボットのアプリ ID とパスワードが必要になります。You will need your bot's app ID and password to complete this process.

  1. GitHub リポジトリから、使用したいサンプルを複製します: ボット認証または ボット認証 MSGraph を複製します。Clone from the github repository the sample you want to work with: Bot authentication or Bot authentication MSGraph.

  2. appsettings.json を更新します。Update appsettings.json:

    • ConnectionName を、お使いのボットに追加した OAuth 接続設定の名前に設定します。Set ConnectionName to the name of the OAuth connection setting you added to your bot.

    • MicrosoftAppId および MicrosoftAppPassword を、お使いのボットのアプリ ID とアプリ シークレットに設定します。Set MicrosoftAppId and MicrosoftAppPassword to your bot's app ID and app secret.

      お使いのボット シークレットに含まれる文字によっては、パスワードを XML でエスケープすることが必要な場合があります。Depending on the characters in your bot secret, you may need to XML escape the password. たとえば、アンパサンド (&) は &amp; のようにエンコードする必要があります。For example, any ampersands (&) will need to be encoded as &amp;.

    {
      "MicrosoftAppId": "",
      "MicrosoftAppPassword": "",
      "ConnectionName": ""
    }
    
  3. startup.cs を更新しますUpdate startup.cs:

    パブリックでない Azure クラウド (政府機関クラウドなど) で OAuth を使用するには、 ファイルに次のコードを追加する必要 startup.cs があります。To use OAuth in non-public Azure clouds, like government cloud, you must add the following code in the startup.cs file:

    string uri = "https://api.botframework.azure.us";
    MicrosoftAppCredentials.TrustServiceUrl(uri);
    OAuthClientConfig.OAuthEndpoint = uri;
    

Microsoft アプリ ID と Microsoft アプリ パスワードの値を取得するには、「 登録 パスワードを取得 する」を参照してくださいTo obtain the Microsoft app ID and Microsoft app password values, see Get registration password.

注意

ここで、このボット コードを Azure サブスクリプションに発行 (プロジェクトを右クリックして [発行] を選択) することもできますが、この記事では不要です。You could now publish this bot code to your Azure subscription (right-click on the project and choose Publish), but it is not necessary for this article. Azure portal でボットを構成するときに使用したアプリケーションとホスティング プランを使用する発行構成を設定する必要があります。You would need to set up a publishing configuration that uses the application and hosting plan that you used when configuration the bot in the Azure portal.

エミュレーターを使用してボットをテストするTest the bot using the Emulator

Bot Framework Emulator をインストールします (まだインストールしていない場合)。If you have not done so already, install the Bot Framework Emulator. 「エミュレーターを 使用したデバッグ」も参照してくださいSee also Debug with the Emulator.

ボットのサンプル ログインを機能するには、「認証用にエミュレーターを構成する」に示すようにエミュレーター を構成する必要がありますIn order for the bot sample login to work you must configure the Emulator as shown in Configure the Emulator for authentication.

テストTesting

認証メカニズムを構成したら、実際のボット サンプル テストを実行できます。After you have configured the authentication mechanism, you can perform the actual bot sample testing.

注意

ボット サンプルの実装方法により、”マジック コード" を入力するように求められる場合があります。You may be asked to enter a magic code, because the way the bot sample is implemented. このマジック コードは RFC # 7636 の一部であり、さらなるセキュリティ要素を追加するために用意されています。This magic code is part of the RFC#7636 and is there to add an extra security element. マジック コードを削除すると、セキュリティ上のリスクが高まります。By removing the magic code, there is an increased security risk. これは、拡張認証が有効になっているDirect Lineを使用して軽減できます。This can be mitigated using Direct Line with enhanced authentication enabled. 詳細については、「拡張認証のBot Framework を参照してくださいFor more information, see Bot Framework enhanced authentication.

  1. お使いのマシン上でローカルでボット サンプルを実行します。Run the bot sample locally on your machine.
  2. エミュレーターを起動します。Start the Emulator.
  3. ボットに接続するときに、ボットのアプリ ID とパスワードを入力する必要があります。You will need to provide your bot's app ID and password when you connect to the bot.
    • Azure アプリの登録からアプリ ID とパスワードを取得します。You get the app ID and the password from the Azure app registration. これらは、appsettings.json または .env ファイルでボット アプリに割り当てたものと同じ値です。These are the same values you assigned to the bot app in the appsettings.json or .env file. エミュレーターでは、構成ファイルまたはボットに初めて接続する場合に、これらの値を割り当てる必要があります。In the Emulator, you assign these values in the configuration file or the first time you connect to the bot.
    • ボット コード内のパスワードを XML エスケープする必要がある場合は、ここでもそれを行う必要があります。If you needed to XML-escape the password in your bot code, you also need to do so here.
  4. help と入力すると、ボットで使用できるコマンドの一覧が表示され、認証機能をテストします。Type help to see a list of available commands for the bot, and test the authentication features.
  5. サインインした後は、サインアウトするまで、資格情報を再度入力する必要はありません。Once you've signed in, you don't need to provide your credentials again until you sign out.
  6. サインアウトして認証をキャンセルするには、logout と入力します。To sign out, and cancel your authentication, type logout.

注意

ボット認証では Bot Connector Service を使用する必要があります。Bot authentication requires use of the Bot Connector Service. このサービスは、お使いのボットのボット チャネル登録情報にアクセスします。The service accesses the bot channels registration information for your bot.

認証の例Authentication example

ボット認証 サンプルでは、ダイアログは、ユーザーのログイン後、ユーザー トークンを取得するように設計されています。In the Bot authentication sample, the dialog is designed to retrieve the user token after the user is logged in.

認証ボットのテスト イメージ

認証 MSGraph の例Authentication MSGraph example

ボット認証 MSGraph サンプルでは、ダイアログは、ユーザーのログイン後、制限された一部のコマンドを受け取るように設計されています。In the Bot authentication MSGraph sample, the dialog is designed to accept a limited set of commands after the user is logged in.

msgraph ボットのテストイメージ


関連情報Additional information

ユーザーがボットに何らかの処理を要求し、それによってボットでユーザーのログインが必要になった場合、ボットによって OAuthPrompt が使用され、特定の接続に必要なトークンの取得が開始されます。When a user asks the bot to do something that requires the bot to have the user logged in, the bot can use an OAuthPrompt to initiate retrieving a token for a given connection. OAuthPrompt では、以下で構成されるトークン取得フローが作成されます。The OAuthPrompt creates a token retrieval flow that consists of:

  1. 既に Azure Bot Service に現在のユーザーおよび接続用のトークンがあるかどうかを確認するためのチェック。Checking to see if the Azure Bot Service already has a token for the current user and connection. トークンがある場合は、そのトークンが返されます。If there is a token, the token is returned.
  2. キャッシュされたトークンが Azure Bot Service にない場合は、OAuthCard が作成されます。これは、ユーザーがクリックできるサインイン ボタンです。If Azure Bot Service does not have a cached token, an OAuthCard is created which is a sign in button the user can click on.
  3. ユーザーが OAuthCard サインイン ボタンをクリックしたら、Azure Bot Service によって、ユーザーのトークンがボットに直接送信されます。または、チャット ウィンドウで 6 桁の認証コードがユーザーに表示されます。After the user clicks on the OAuthCard sign in button, Azure Bot Service will either send the bot the user's token directly or will present the user with a 6-digit authentication code to enter in the chat window.
  4. ユーザーに認証コードが表示される場合は、ボットによって、この認証コードがユーザーのトークンと交換されます。If the user is presented with an authentication code, the bot then exchanges this authentication code for the user's token.

次のセクションでは、一般的な認証タスクが、サンプルによってどのように実装されているかを説明します。The following sections describe how the sample implements some common authentication tasks.

OAuth プロンプトを使用してユーザーをサインインさせて、トークンを取得するUse an OAuth prompt to sign the user in and get a token

アーキテクチャ csharp イメージ

Dialogs\MainDialog.csDialogs\MainDialog.cs

OAuth プロンプトを、コンストラクター内の MainDialog に追加します。Add an OAuth prompt to MainDialog in its constructor. ここでは、接続名の値は appsettings.json ファイルから取得されました。Here, the value for the connection name was retrieved from the appsettings.json file.

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 プロンプトを起動します。これによりユーザーのサインインが求められます。Within a dialog step, use BeginDialogAsync to start the OAuth prompt, which asks the user to sign in.

  • ユーザーがサインイン済みの場合は、ユーザーに問い合わせることなく、トークン応答イベントが生成されます。If the user is already signed in, this will generate a token response event, without prompting the user.
  • それ以外の場合は、ユーザーのサインインが求められます。Otherwise, this will prompt the user to sign in. ユーザーがサインインを試みた後、Azure Bot Service によってトークン応答イベントが送信されます。The Azure Bot Service sends the token response event after the user attempts to sign in.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

次のダイアログ ステップ内で、前のステップの結果としてトークンが存在することを確認します。Within the following dialog step, check for the presence of a token in the result from the previous step. null でない場合、ユーザーは正常にサインインしています。If it is not null, the user successfully signed in.

// 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;

TokenResponseEvent の待機Wait for a TokenResponseEvent

OAuth プロンプトを起動すると、そのプロンプトは、ユーザーのトークン取得元となるトークン応答イベントを待ちます。When you start an OAuth prompt, it waits for a token response event, from which it will retrieve the user's token.

Bots\AuthBot.csBots\AuthBot.cs

AuthBotActivityHandler から派生し、トークン応答イベント アクティビティを明示的に処理します。AuthBot derives from ActivityHandler and explicitly handles token response event activities. ここではアクティブなダイアログを続行します。これにより OAuth プロンプトでイベントを処理し、トークンを取得できます。Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

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

ユーザーをログアウトするLog the user out

接続のタイムアウトに依存するのではなく、ユーザーが明示的にサインアウトまたはログアウトできるようにすることをお勧めします。It is best practice to let users explicitly sign out or logout, instead of relying on the connection to time out.

Dialogs\LogoutDialog.csDialogs\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;
}

Teams 認証の追加Adding Teams Authentication

Teams は、OAuth に関して他のチャネルとは多少異なる動作をするため、認証を適切に実装するにはいくつかの変更が必要です。Teams behaves somewhat differently than other channels in regards to OAuth and requires a few changes to properly implement authentication. Teams 認証ボット サンプル(C#JavaScript Java ) から / コードを追加 / しますWe will add code from the Teams Authentication Bot sample (C#/JavaScript/Java).

他のチャネルと Teams の違いの 1 つは、Teams がボットに イベント アクティビティではなく 呼び出し アクティビティを送信することです。One difference between other channels and Teams is that Teams sends an invoke activity to the bot, rather than an event activity.

Bots/TeamsBot.csBots/TeamsBot.cs

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

OAuth プロンプト を使用する場合は、この呼び出しアクティビティをダイアログに転送する必要があります。If you use an OAuth prompt, this invoke activity must be forwarded to the dialog. ここでは、TeamsActivityHandler でこれを行います。We will do so in the TeamsActivityHandler. 次のコードをメイン ダイアログ ファイルに追加します。Add the following code to your main dialog file.

Bots/DialogBot.csBots/DialogBot.cs

public class DialogBot<T> : TeamsActivityHandler where T : Dialog

最後に必ず、ボットのフォルダーの最上位レベルに適切な TeamsActivityHandler ファイル (C# ボットの場合は TeamsActivityHandler.cs、Javascript ボットの場合は teamsActivityHandler.js) を追加してください。Finally, make sure to add an appropriate TeamsActivityHandler file (TeamsActivityHandler.cs for C# bots and teamsActivityHandler.js for Javascript bots) at the topmost level in your bot's folder.

TeamsActivityHandlerメッセージの反応 アクティビティも送信します。The TeamsActivityHandler also sends message reaction activities. メッセージの反応アクティビティは、返信先 ID フィールドを使用して元のアクティビティを参照します。A message reaction activity references the original activity using the reply to ID field. このアクティビティは、Microsoft Teams のアクティビティ フィードでも表示される必要があります。This activity should also be visible through the Activity Feed in Microsoft Teams.

注意

マニフェストを作成して、validDomains セクションに token.botframework.com を含める必要があります。そうしないと、 OAuthCard の [サインイン] ボタンをクリックしても、認証ウィンドウは開きません。You need to create a manifest and include token.botframework.com in the validDomains section; otherwise the OAuthCard Sign in button will not open the authentication window. App Studio を使用して、マニフェストを生成してください。Use the App Studio to generate your manifest.

関連項目Further reading