重要
このトピックは Power Virtual Agents プレビューのドキュメントを含み、今後変更される可能性があります。
プレビュー機能は運用環境での使用を想定しておらず、機能が制限される可能性があります。 これらの機能は公式リリースの前に使用できるため、一足先にアクセスして フィードバックを送る ことができます。
運用に対応したボットを構築する場合は、Power Virtual Agents の概要 を参照してください。
ユーザー認証をトピックに追加して、顧客が会話内で直接サインインできるようにします。 次に、ユーザー変数を使用して会話をパーソナライズしたり、ユーザーの代わりにバック エンド システムにアクセスしたりすることができます。
トピックで認証を使用する前に、Azure AD でユーザー認証を設定する必要があります。
- Azure AD でユーザー認証を構成するの指示に従ってください。
- この記事に戻ります。
サインイン システム トピック でユーザー認証を追加する
ボットを作成すると、Power Virtual Agents は自動的に Signin というシステム トピックを追加します。 これを使用するには、ボットの認証を手動に設定し、ユーザーにサインインを要求する必要があります。 顧客がボットと会話を始めると、Signin トピックがトリガーされ、ユーザーにサインインするよう促します。 Signin トピックは、ボットに合わせて適切にカスタマイズできます。
ナビゲーション メニューの 設定 で セキュリティ を選択します。
認証 タイルを選択します。
手動 (カスタム Web サイト用) を選択してから、ユーザーにサインインを要求するを選択します。
カスタム トピックでユーザー認証を追加する
Signin トピックでは、会話の開始時にユーザーを認証します。 ユーザーが後でサインインできるようにするため、任意のカスタム トピックに認証ノードを追加できます。
顧客がユーザー名とパスワードを入力すると、検証コードを入力するよう促される場合があります。 ログインした後、別の認証ノードに到達した場合は、再度プロンプトが表示されることはありません。
ナビゲーション メニューの 設定 で セキュリティ を選択します。
認証 タイルを選択します。
ユーザーにサインインを要求するをオフにします。
ナビゲーション メニューで、トピックを選択してから、認証を追加するトピックを開きます。
ノードの追加 (+) を選択し、アクションの呼び出しを選択し、認証 を選択します。
ID プロバイダーで構成されたユーザーを使用して、トピックをテストするを実行します。
チップ
サインインが成功した場合と失敗した場合の両方のパスを作成することが重要です。 サインインに失敗する理由は、ID プロバイダーのサインイン エクスペリエンスに関するエラーなど、複数あります。
認証変数
ユーザー認証をボットで設定すると、トピック内で認証変数を使用できます。 次の表は、選択した認証オプションに基づくこれらの変数の利用可能性を比較したものです。
User.DisplayName
警告
この変数に値が入ることは保証されていない。 トピックが正しく動作することを確認するために、ID プロバイダーのユーザーを使ってテストしてください。
User.DisplayName 変数には、ID プロバイダーに保存されている表示名が含まれます。 この変数を使用すると、ユーザーが明示的に名前を与えなくても、挨拶や言及したりできるため、会話がよりパーソナライズされたものになります。
Power Virtual Agents は、profile スコープが手動認証の設定時に定義されている限り、ID プロバイダーによって提供される name 要求から User.DisplayName の値を自動的に設定します。 スコープに関する詳細情報は、Azure AD で手動認証を設定するを参照してください。
User.Id
警告
この変数に値が入ることは保証されていない。 トピックが正しく動作することを確認するために、ID プロバイダーのユーザーを使ってテストしてください。
User.Id 変数には、ID プロバイダーに保存されている userID が含まれます。 UserID を値とする API を呼び出す場合は、Power Automate フロー でこの変数を使用する。
Power Virtual Agents は、ID プロバイダから提供される sub 要求からの User.DisplayName の値を自動的に設定します。
User.IsLoggedIn
User.IsLoggedIn とは、ユーザーのサインイン状態を含む格納するブール型の変数です。 true の値は、ユーザーがサインインしていることを示します。 この変数を使用して、サインインに成功したかどうかをチェックするトピック内の分岐ロジックを作成したり、ユーザーがサインインしている場合にのみユーザー情報を取得したりすることができます。
User.AccessToken
警告
信頼できるソースに対してのみ User.AccessToken 変数をパスしていることを確認してください。 これにはユーザー認証情報が含まれており、侵害された場合、ユーザーに害を及ぼす可能性があります。
User.AccessToken 変数には、ユーザーのサイン イン後に取得されるユーザーのトークンが含まれます。 この変数を Power Automate フロー に渡すことができるため、バック エンド API に接続してユーザーの情報を取得したり、ユーザーに代わってアクションを実行したりできます。
メッセージ ノード内または信頼できないフロー内で User.AccessToken を使用しないでください。
SignInReason
SignInReason は、ユーザーがいつサインインする必要があるかを示す選択タイプの変数です。 次の 2 つの値があります:
認証変数
ボットが「チーム専用」または「手動」認証オプションのいずれかで構成されている場合、トピックで使用可能な認証変数のセットがあります。 ボットで認証を構成する方法の詳細については、認証構成ドキュメントを確認してください。
次の表は、認証構成オプションごとの認証変数の可用性を比較しています。
| 認証変数 |
認証なし |
Teams 専用 |
手動 |
UserDisplayName |
❌ |
✔️ |
✔️ |
UserID |
❌ |
✔️ |
✔️ |
IsLoggedIn |
❌ |
❌ |
✔️ |
AuthToken |
❌ |
❌ |
✔️ |
UserDisplayName 変数
UserDisplayName 変数には、ID プロバイダーに保存されているユーザーの表示名が含まれます。 この変数を使用すると、エンドユーザーに明示的に指示しなくても、エンドユーザーに挨拶したり、紹介したりできるため、よりパーソナライズされたものになります。
このフィールド値は、Azure Active Directory (Azure AD) name 要求から取得されます。 OAuth プロバイダーの場合、これは name 要求に保存されている値です。 Power Virtual Agents は、このフィールドを変数に自動的に抽出するので、認証スコープ設定の一部として profile があることを確認します。
UserID 変数
UserID 変数には、ID プロバイダーに保存されているユーザーの ID が含まれます。 この値は、Power Automate が UserID を値として受け取る API を呼び出すためのフロー。
このフィールド値は、Azure AD sub 要求から取得されます。 OAuth プロバイダーの場合、これは sub 要求に保存されている値です。 Power Virtual Agents は、このフィールドを変数に自動的に抽出します。
警告
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 専用」構成を使用する場合の認証
認証オプションがTeams のみに設定されている場合、トピックに認証を明示的に追加する必要はありません。 この構成では、Microsoft Teams の Teams 資格情報を介して自動的にログインし、認証カードを使用して明示的にログインする必要はありません。 認証オプションが手動に設定されている場合は、認証ノードを追加する必要があります (Teams チャネルの場合でも)。
Note
認証オプションが「Teams のみ」に設定されている場合、トピックに認証を明示的に追加するオプションは必要はありません。
トピックにエンド ユーザー認証を追加
認証ノードは、ユーザーにサインイン カードでログインするように求めます。 ユーザーがすでにログインしている場合は、別の認証ノードにアクセスしても、再度プロンプトが表示されることはありません。
ユーザーがユーザー 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 プロバイダーのサイン イン エクスペリエンスにエラーが発生したりしても、予期せぬ事態は発生しません。