コパイロットにエンドユーザー認証を追加

[アーティクル]
04/01/2024

重要

Power Virtual Agents 機能は、生成 AI への多大な投資と Microsoft Copilot 全体の統合の強化により、現在 Microsoft Copilot Studio の一部となっています。

ドキュメントやトレーニングコンテンツが更新される間、一部の記事やスクリーンショットで Power Virtual Agents が参照される場合があります。

コパイロットの会話内で、直接ユーザー認証を有効にすることができます。ユーザー認証とは、変数で名前や ID などのユーザーの基本プロパティを取得できるだけでなく、認証ノードを使用してユーザーにサインインを求め、そのユーザーのユーザートークンを取得し、そのトークンを使用してバックエンドシステムからユーザーの情報を取得することもできます。

注意

Web アプリと Microsoft Teams で作成されたコパイロットには、Teams および Power Apps 専用 認証を使用するように事前に構成された認証が付属しています。

ユーザーが手動でサインインする必要がないように、シングルサインオン (SSO) を構成できます。詳細については、Web 用の SSO を設定するを参照してください。

前提条件

変数を使用する
エンドユーザー認証を構成します。

Web アプリケーション
クラシック

ユーザー認証をトピックに追加して、顧客が会話内で直接サインインできるようにします。次に、ユーザー変数を使用して会話をパーソナライズしたり、ユーザーの代わりにバックエンドシステムにアクセスしたりすることができます。

Microsoft Entra ID で手動認証を構成する

トピックで認証を使用する前に、Microsoft Entra ID を使用してユーザー認証を構成する必要があります。

「Microsoft Entra ID を使用してユーザー認証を構成する」の手順に従います。
この記事に戻ります。

コパイロットを作成すると、Microsoft Copilot Studio では Signin というシステムトピックが自動的に追加されます。これを使用するには、コパイロットの認証を手動に設定し、ユーザーにサインインを要求する必要があります。顧客がコパイロットとの会話を開始すると、Signin トピックがトリガーされ、ユーザーにサインインを求めます。コパイロットに合わせて サインイン トピックをカスタマイズできます。

ナビゲーションメニューの設定で セキュリティ を選択します。
認証タイルを選択します。
手動 (カスタム Web サイト用) を選択してから、ユーザーにサインインを要求するを選択します。

カスタムトピックでユーザー認証を追加する

Signin トピックでは、会話の開始時にユーザーを認証します。ユーザーが後でサインインできるようにするため、任意のカスタムトピックに認証ノードを追加できます。

顧客がユーザー名とパスワードを入力すると、検証コードを入力するよう促される場合があります。ログインした後、別の認証ノードに到達した場合は、再度プロンプトが表示されることはありません。

ナビゲーションメニューの設定で セキュリティ を選択します。
認証タイルを選択します。
ユーザーにサインインを要求するをオフにします。
ナビゲーションメニューで、トピックを選択してから、認証を追加するトピックを開きます。
ノードの追加 (+) を選択し、アクションの呼び出しを選択し、認証を選択します。
ID プロバイダーで構成されたユーザーを使用して、トピックをテストするを実行します。

チップ

サインインが成功した場合と失敗した場合の両方のパスを作成することが重要です。サインインに失敗する理由は、ID プロバイダーのサインインエクスペリエンスに関するエラーなど、複数あります。

認証変数

コパイロットのユーザー認証を構成すると、トピックで認証変数を使用できます。次の表は、選択した認証オプションに基づくこれらの変数の利用可能性を比較したものです。

認証変数	認証なし	Teams と Power Apps のみ	手動
User.DisplayName	使用できません	対応可能	対応可能
User.FirstName	使用できません	対応可能	対応可能
User.LastName	使用できません	対応可能	対応可能
User.PrincipalName	使用できません	対応可能	対応可能
User.Email	使用できません	対応可能	対応可能
User.Id	使用できません	対応可能	対応可能
User.IsLoggedIn	使用できません	対応可能	対応可能
User.AccessToken	使用できません	使用できません	対応可能
SignInReason	使用できません	対応可能	対応可能

User.DisplayName

警告

この変数に値が入ることは保証されていない。トピックが正しく動作することを確認するために、ID プロバイダーのユーザーを使ってテストしてください。

User.DisplayName 変数には、ID プロバイダーに保存されている表示名が含まれます。この変数を使用して、コパイロットに明示的に名前を指定しなくてもユーザーに挨拶や参照を行い、会話をよりカスタマイズされたものにします。

Microsoft Copilot Studio は、profile スコープが手動認証の設定時に定義されている限り、ID プロバイダーによって提供される name 要求から User.DisplayName の値を自動的に設定します。スコープの詳細については、Microsoft Entra ID を使用してユーザー認証を構成するを参照してください。

User.Id

警告

User.Id 変数には、ID プロバイダーに保存されている userID が含まれます。 UserID を値とする API を呼び出す場合は、Power Automate フローでこの変数を使用する。

Microsoft Copilot Studio は、ID プロバイダから提供される sub 要求からの User.DisplayName の値を自動的に設定します。

User.IsLoggedIn

User.IsLoggedIn とは、ユーザーのサインイン状態を含む格納するブール型の変数です。 true の値は、ユーザーがサインインしていることを示します。この変数を使用して、サインインに成功したかどうかをチェックするトピック内の分岐ロジックを作成したり、ユーザーがサインインしている場合にのみユーザー情報を取得したりすることができます。

User.AccessToken

警告

信頼できるソースに対してのみ User.AccessToken 変数をパスしていることを確認してください。これにはユーザー認証情報が含まれており、侵害された場合、ユーザーに害を及ぼす可能性があります。

User.AccessToken 変数には、ユーザーのサインイン後に取得されるユーザーのトークンが含まれます。この変数を Power Automate フローに渡すことができるため、バックエンド API に接続してユーザーの情報を取得したり、ユーザーに代わってアクションを実行したりできます。

メッセージ ノード内または信頼できないフロー内で User.AccessToken を使用しないでください。

SignInReason

SignInReason は、ユーザーがいつサインインする必要があるかを示す選択タイプの変数です。次の 2 つの値があります:

SignInRequired は、ユーザーが会話の最初に サインイン システムトピックを使用してサインインする必要があることを示しています。 ユーザーにサインインを要求するをオンにする必要があります。
Initializer は、ユーザーがまだサインインしていない場合、会話の中で認証変数を使用するポイントに到達すると、サインインするように促されることを示しています。

認証変数

ボットが Teams および Power Apps 専用 または手動認証オプションのいずれかで構成されている場合、トピックで使用可能な認証変数のセットがあります。ボットで認証を構成する方法の詳細については、認証構成ドキュメントを確認してください。

次の表は、認証構成オプションごとの認証変数の可用性を比較しています。

認証変数	認証なし	Teams と Power Apps のみ	手動
`UserDisplayName`	❌	✔️	✔️
`UserID`	❌	✔️	✔️
`IsLoggedIn`	❌	❌	✔️
`AuthToken`	❌	❌	✔️

UserDisplayName 変数

UserDisplayName 変数には、ID プロバイダーに保存されているユーザーの表示名が含まれます。この変数を使用すると、エンドユーザーに明示的に指示しなくても、エンドユーザーに挨拶したり、紹介したりできるため、よりパーソナライズされたものになります。

このフィールド値は、Microsoft Entra ID name 要求から取得されます。 OAuth プロバイダーの場合、これは name 要求に保存されている値です。 Microsoft Copilot Studio は、このフィールドを変数に自動的に抽出するので、認証スコープ設定の一部として profile があることを確認します。

UserID 変数

UserID 変数には、ID プロバイダーに保存されているユーザーの ID が含まれます。この値は、Power Automate が UserID を値として受け取る API を呼び出すためのフロー。このフィールド値は、Microsoft Entra ID sub 要求から取得されます。 OAuth プロバイダーの場合、これは sub 要求に保存されている値です。 Microsoft Copilot Studio は、このフィールドを変数に自動的に抽出します。

警告

UserDisplayName そして UserID 変数が入力される保証はなく、ID プロバイダーのユーザー構成によっては空の文字列になる場合があります。これらの変数が空の場合でも、ID プロバイダーのユーザーでテストして、トピックが正しく機能することを確認します。

IsLoggedIn 変数

IsLoggedIn 変数は、ユーザーがサインインしているか (サインインする、または既にサインインしているため、サインイン成功パスとも呼ばれます)、またはサインインしていないか (サインイン失敗パスとなる) を示します。

IsLoggedIn とは、ユーザーのサインイン状態を含むブール型の変数です。この変数を使用して、サインインが成功したかどうかをチェックする分岐ロジックをトピックに作成が可能で (たとえば、認証ノード追加の一部としてすでに提供されているテンプレートで)、またユーザーがサインインしている場合にのみ、便宜的にユーザー情報をフェッチします。

AuthToken 変数

AuthToken 変数には、ユーザーのサインイン後に取得されるユーザーのトークンが含まれます。この変数を Power Automate フローに渡すことができるため、バックエンド API に接続してユーザーの情報を取得したり、ユーザーに代わってアクションを実行したりできます。

警告

信頼できるソースに対してのみ AuthToken 変数をパスしていることを確認してください。これにはユーザー認証情報が含まれており、侵害された場合、ユーザーに害を及ぼす可能性があります。

AuthToken 内部メッセージ ノード、または信頼できないフローを使用しないでください。

認証変数のテスト

デフォルトでは、テストボット ペインは、現在サインインしているユーザーのアカウントを使用して、UserDisplayName および UserID 変数に入力します。ただし、認証を使用するトピックをテストする場合は、これらの変数に他の値 (または空白の値) を使用することをお勧めします。

たとえば、特殊文字がどのように使用されるか、または変数が空の場合に何が起こるかをテストしたい場合があります。

これは、テストボット ペインにのみ適用されます。チャネルにデプロイされた公開ボットでは、このセクションで説明されているコマンドを使用できません。

次の表に、これらの変数を設定するコマンドを示します。通常ボットとチャットしている場合と同じように、コマンドをテストボットに入力します。成功すると、ボットから確認メッセージが届きます。ボットが認証を使用しない場合、エラーが発生します。

テストボット ペインをリセットした場合 (または、トピックに変更を加えてテストボットが自動的にリセットされるようにした場合)、コマンドを再度送信する必要があります。

変数	カスタム値コマンド	空の (空白の) 値コマンド
`UserDisplayName`	`/debug set bot.UserDisplayName "Value"`	`/debug set bot.UserDisplayName ""`
`UserID`	該当なし	`/debug set bot.UserID ""`

重要

セキュリティ上の理由から、UserID 変数に、カスタム値 (空または空白の値以外) を入力することはできません。

「Teams および Power Apps 専用」構成を使用する場合の認証

認証オプションが Teams および Power Apps 専用に設定されている場合、トピックに認証を明示的に追加する必要はありません。この構成では、Microsoft Teams の Teams 資格情報を介して自動的にログインし、認証カードを使用して明示的にログインする必要はありません。認証オプションが手動に設定されている場合は、認証ノードを追加する必要があります (Teams チャネルの場合でも)。

注意

認証オプションが Teams および Power Apps 専用に設定されている場合、トピックに認証を明示的に追加するオプションは必要はありません。

トピックにエンドユーザー認証を追加

認証ノードは、ユーザーにサインインカードでログインするように求めます。ユーザーがすでにログインしている場合は、別の認証ノードにアクセスしても、再度プロンプトが表示されることはありません。

サインインの要求。

ユーザーがユーザー ID とパスワードをプロンプトに (ID プロバイダーによってホストされている) 入力すると、チャネルに応じて、検証コードの入力を求められる場合があります。 Microsoft Teams などのいくつかのチャネルは、ユーザーが検証コードを入力を要請しません。

ボットが SSO 構成の場合、ユーザーはサインインを求められません。

トピックに認証ノードを追加するには:

編集するボット用の トピックページ に移動します。
認証テンプレートを追加したいトピックのキャンバスの作成を開きます。

Note

ボットが Dynamics 365 Customer Service に接続されている場合、最初にユーザーに挨拶するときにボットがたどる会話パスに認証ノードを含めることはできません。そうしない場合、サインインカードが 2 回表示されます。代わりに、ユーザーの応答によってトリガーされる別のトピックに認証ノードを追加する必要があります。
ノードの追加 (+) を選択して、メッセージノードを追加します。サインオンエクスペリエンスが発生しようとしていることをボットが示す内容を入力します。
メッセージノードの下で、ノードの追加 (+) を選択し、アクションを呼び出す、認証の順に選択します。

Note

認証ノードは、ダイアログツリーの最後のアクションピッカーで (リーフノードとして) のみ使用できます。ダイアログの途中で追加することはできません。追加したら、他のノードをその下に追加できます。
一度選択すると、いくつかの新しいノードが自動的に追加されます。これらのノードには親認証ノードが含まれ、後に成功パスと失敗パスの両方のノードが続きます。

Authenticate ノードなしで、AuthToken を使用

IsLoggedIn と AuthToken 変数は、アクションを呼び出すメニューエントリで提供されるテンプレートを使用しなくても、変数は使用できます。最初にユーザーが認証するノードを介することなく AuthToken 変数をパスする場合、ユーザーはその手順でサインインするように求められます。

AuthToken 変数は、ユーザーが常にサインインすることを予想している場合、またはユーザーが別のトピックからリダイレクトされている場合に役立ちます。ユーザーがサインインに失敗した場合に扱うアクションを呼び出すエントリで、提供されるテンプレートの使用をお勧めします。

Note

ユーザーが会話の途中でサインアウトした場合、トピックが AuthToken 変数を使用するノードに取得されると、ユーザーは再度サインインするよう求められます。

成功パス

成功パスは、IsLoggedIn = True に等しく、ユーザーが正常にサインインした場合の (またはすでにサインインしていた) アカウントです。

AuthToken 変数を使用するロジックがある場合 (たとえば、フローを使用してユーザーの情報を取得するバックエンドシステムに接続する場合)、このパスの下に置く必要があります。

失敗パス

失敗パスは、IsLoggedIn = True 以外の条件に相当します。ほとんどの場合、失敗のパスは、ユーザーがサインインに失敗したか、間違ったパスワードを使用したか、サインイン処理をキャンセルしたために発生します。

このケースを扱うロジックを追加します。例として、再試行するためのオプション、またはライブエージェントにエスカレートするオプションを提供しています。特定のシナリオと使用状況に合わせて失敗パスのアクションをカスタマイズします。

使用しているトピックをテストする

IDプロバイダーで構成された実際のユーザーを使用して、必ずトピックをテストしてください。サインインの成功パスと失敗パスの両方が実行されていることを確認すれば、ユーザーがサインインに失敗したり、ID プロバイダーのサインインエクスペリエンスにエラーが発生したりしても、予期せぬ事態は発生しません。

コパイロットにエンドユーザー認証を追加