ユーザー認証User authentication

適用対象: SDK v4APPLIES TO: SDK v4

電子メールのチェック、フライトステータスのチェック、注文の配置など、bot がユーザーの代わりにセキュリティで保護されたオンラインリソースにアクセスする必要がある場合があります。At times a bot must access secured online resources on behalf of the user, such as checking email, checking on flight status, or placing an order. ユーザーは、bot に代わってそのことを承認する必要があります。 bot を承認するには、ユーザーが自分の id を認証する必要があります。The user must authorize the bot to do so on their behalf, and in order to authorize the bot, the user must authenticate their identity. OAuth は、ユーザーを認証し、bot を承認するために使用されます。OAuth is used to authenticate the user and authorize the bot. 認証の種類」も参照してください。See also Authentication types.

ご利用の OAuth ナレッジを更新する場合は、次を参照してください。If you want to refresh your OAuth knowledge, see the following:

会話でのユーザー認証User authentication in a conversation

ボットがユーザーに代わって一定の操作 (メールの確認、カレンダーの参照、フライト状況の確認、発注など) を実行するには、Microsoft Graph や GitHub、組織の REST サービスなど、外部サービスを呼び出す必要があります。To perform certain operations on behalf of a user, such as checking email, referencing a calendar, checking on flight status, or placing an order, the bot will need to call an external service, such as the Microsoft Graph, GitHub, or a company's REST service. 各外部サービスには、これらの呼び出しをセキュリティで保護する方法があります。Each external service has a way of securing those calls. これらの要求を発行する一般的な方法は、その外部サービスのユーザーを一意に識別する "ユーザートークン" を使用することです (JSON Web トークン (JWT) とも呼ばれます)。A common way to issue those requests is to use a user token that uniquely identifies the user on that external service (sometimes referred to as a JSON Web Token (JWT)).

外部サービスの呼び出しをセキュリティ保護するには、ボットがそのサービスのユーザー トークンを取得できるように、ユーザーにサインインを要求する必要があります。To secure the call to an external service, the bot must ask the user to sign-in, so it can acquire the user's token for that service. 多くのサービスでは、OAuth または OAuth2 プロトコルによるトークンの取得がサポートされています。Many services support token retrieval via the OAuth or OAuth2 protocol.

Azure Bot Service には、OAuth プロトコルと連携し、トークンのライフサイクルを管理する特別な サインイン カードおよびサービスが用意されています。The Azure Bot Service provides specialized sign-in cards and services that work with the OAuth protocol and manage the token life-cycle. ボットは、これらの機能を使用してユーザー トークンを取得できます。A bot can use these features to acquire a user token.

  • ボット構成の一環として、OAuth 接続 が Azure の Azure Bot Service リソース内に登録されます。As part of bot configuration, an OAuth connection is registered within the Azure Bot Service resource in Azure.

    この接続には、使用する ID プロバイダー の情報のほか、有効な OAuth クライアント ID およびシークレット、有効にする OAuth スコープ、その ID プロバイダーによって必要とされるその他の接続メタデータが含まれています。The connection contains information about the identity provider to use, along with a valid OAuth client ID and secret, the OAuth scopes to enable, and any other connection metadata required by that identity provider.

  • OAuth 接続は、ユーザーのサインインとユーザー トークンの取得を楽にするためにボットのコード内で使用されます。In the bot's code, the OAuth connection is used to help sign-in the user and get the user token.

次の画像は、認証プロセスに関連する要素を示しています。The following image shows the elements involved in the authentication process.

ボット認証コンポーネント

Bot Framework トークン サービスについてAbout the Bot Framework Token Service

Bot Framework トークン サービスの役割は次のとおりです。The Bot Framework Token Service is responsible for:

  • 幅広い外部サービスとの OAuth プロトコルの使用を容易にすること。Facilitating the use of the OAuth protocol with a wide variety of external services.
  • 特定のボット、チャネル、会話、ユーザーのトークンを安全に格納すること。Securely storing tokens for a particular bot, channel, conversation, and user.
  • ユーザー トークンを取得すること。Acquiring user tokens.

    ヒント

    ボットのユーザー トークンが期限切れになっている場合は、ボットが次のことを行います。If the bot has an expired user token, the bot should:

    • ユーザーをログアウトするLog the user out
    • サインイン フローをもう一度開始するInitiate the sign in flow again

たとえば、ユーザーの最新のメールを確認できるボットでは、Microsoft Graph API を使用して、ID プロバイダー (この場合は Azure Active Directory) のユーザー トークンを要求します。For example, a bot that can check a user's recent emails, using the Microsoft Graph API, requires a user token from an Identity Provider, in this case Azure Active Directory. デザイン時に、ボットの開発者は次の 2 つの重要な手順を実行します。At design time, the bot developer performs these two important steps:

  1. Azure Active Directory アプリケーション (ID プロバイダー) を、Azure Portal を使用して Bot Framework トークン サービスに登録します。Registers an Azure Active Directory application, an Identity Provider, with the Bot Framework Token Service, via the Azure Portal.
  2. ボットの OAuth 接続を (たとえば GraphConnection という名前で) 構成します。Configures an OAuth connection (named for example GraphConnection) for the bot.

次の図は、Microsoft Graph サービスを使用して電子メール要求が行われた場合のユーザーとボットとの対話の時間シーケンスを示しています。The following picture shows the time sequence of the user's interaction with a bot when an email request is made using the Microsoft Graph service.

ボット認証時間シーケンス

  1. ユーザーがボットに電子メール要求を行います。The user makes an email request to the bot.

  2. このメッセージが含まれたアクティビティがユーザーから Bot Framework チャネル サービスに送信されます。An activity with this message is sent from the user to the Bot Framework channel service. アクティビティ内の userid フィールドが設定されていることがチャネル サービスによって確認され、メッセージがボットに送信されます。The channel service ensures that the userid field within the activity has been set and the message is sent to the bot.

    注意

    ユーザー ID はチャネル固有です (ユーザーの Facebook ID や SMS 電話番号など)。User ID's are channel specific, such as the user's Facebook ID or their SMS phone number.

  3. ボットは Bot Framework トークン サービスに要求を実行し、OAuth 接続 GraphConnection のユーザー ID のトークンが既にあるかどうかを問い合わせます。The bot makes a request to the Bot Framework Token Service asking if it already has a token for the UserId for the OAuth connection GraphConnection.

  4. このユーザーがボットを操作したのはこれが初めてであるため、Bot Framework トークン サービスにはまだこのユーザー用のトークンがありません。NotFound が結果としてボットに返されます。Since this is the first time this user has interacted with the bot, the Bot Framework Token Service does not yet have a token for this user, and returns a NotFound result to the bot.

    注意

    トークンが見つかった場合、認証手順はスキップされ、ボットは、格納されているトークンを使用して電子メール要求を行うことができます。If the token is found, the authentication steps are skipped and the bot can make the email request using the stored token.

  5. ボットによって、GraphConnection という接続名が含まれた OAuthCard が作成され、このカードを使用してサインインするようユーザーに要求する応答が返されます。The bot creates an OAuthCard with a connection name of GraphConnection and replies to the user asking to sign-in using this card.

  6. アクティビティが Bot Framework チャネル サービスを通過します。これにより、Bot Framework トークン サービスが呼び出され、この要求で有効な OAuth サインイン URL が作成されます。The activity passes through the Bot Framework Channel Service, which calls into the Bot Framework Token Service to create a valid OAuth sign-in URL for this request. このサインイン URL が OAuthCard に追加され、そのカードがユーザーに返されます。This sign-in URL is added to the OAuthCard and the card is returned to the user.

  7. OAuthCard のサインイン ボタンをクリックしてサインインするよう、ユーザーにメッセージが表示されます。The user is presented with a message to sign-in by clicking on the OAuthCard's sign-in button.

  8. ユーザーがサインイン ボタンをクリックすると、チャネル サービスによって Web ブラウザーが開かれます。また、外部サービスが呼び出され、そのサインイン ページが読み込まれます。When the user clicks the sign-in button, the channel service opens a web browser and calls out to the external service to load its sign-in page.

  9. ユーザーが外部サービスのこのページにサインインします。The user signs-in to this page for the external service. 次に、外部サービスが Bot Framework トークン サービスとの OAuth プロトコル交換を完了します。その結果、外部サービスが Bot Framework トークン サービスにユーザー トークンを送信します。Then the external service completes the OAuth protocol exchange with the Bot Framework Token Service, resulting in the external service sending the Bot Framework Token Service the user token. Bot Framework トークン サービスがこのトークンを安全に格納し、このトークンと共にアクティビティをボットに送信します。The Bot Framework Token Service securely stores this token and sends an activity to the bot with this token.

  10. ボットがトークン付きのアクティビティを受け取り、それを使用して MS Graph API に対して呼び出しを実行できるようになります。The bot receives the activity with the token and is able to use it to make calls against the MS Graph API.

サインイン URL のセキュリティ保護Securing the sign-in URL

Bot Framework でユーザー ログインを容易にする際に重要な考慮事項は、サインイン URL をセキュリティ保護する方法です。An important consideration when the Bot Framework facilitates a user login is how to secure the sign-in URL. ユーザーにサインイン URL が表示されるとき、その URL は、そのボットの特定の会話 ID とユーザー ID に関連付けられています。When a user is presented with a sign-in URL, this URL is associated with a specific conversation ID and user ID for that bot. この URL は共有しないようにする必要があります。特定のボットの会話で不適切なサインインが行われる原因となるためです。This URL should not be shared, as it would cause the wrong sign-in to occur for a particular bot conversation. サインイン URL の共有に関するセキュリティ攻撃を緩和するには、マシンとサインイン URL をクリックする人物が会話ウィンドウを "所有" していることを保証する必要があります。To mitigate security attacks regarding sharing the sign-in URL, it is necessary to ensure that the machine and person who clicks on the sign-in URL is the person who owns the conversation window.

Microsoft Teams、Direct Line、WebChat などの一部のチャネルでは、ユーザーに気付かずにこの操作を行うことができます。Some channels such as Microsoft Teams, Direct Line, and WebChat are able to do this without the user noticing. たとえば、WebChat では、サインイン フローが WebChat 会話と同じブラウザーで実行されるように、セッション Cookie を使用します。For example, WebChat uses session cookies to ensure that the sign-in flow took place in the same browser as the WebChat conversation. しかし、他のチャネルでは多くの場合、ユーザーに 6 桁の "マジック コード" が表示されます。However, for other channels the user is often presented with a 6-digit magic code. これは組み込みの多要素認証に類似しています。Bot Framework トークン サービスは、ユーザーが最終的な認証を完了するまでトークンをボットにリリースしないためです。これにより、サインインした人物は、6 桁のコードを入力してチャット エクスペリエンスにアクセスすることになります。This is similar to a built-in multi-factor authentication, as the Bot Framework Token Service will not release the token to the bot unless the user finishes the final authentication, proving that the person who signed-in has access to the chat experience by entering the 6-digit code.

重要

こちらの重要なセキュリティに関する考慮事項に留意してください。Please, keep in mind these important Security considerations. 追加情報は次のブログ記事で見つけることができます。Azure Bot Service 認証でのWebChat の使用You can find additional information in this blog post: Using WebChat with Azure Bot Service Authentication.

次の手順Next steps

ユーザー認証について理解したところで、bot に適用する方法を見てみましょう。Now that you know about user authentication, let's take a look at how to apply that to your bot.

関連項目See also