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

[アーティクル]
12/09/2024

エージェント会話内で直接ユーザー認証を有効にすることができます。名前や ID などのユーザーの基本プロパティを変数に割り当てることができます。また、トピックの認証ノードを使用してサインインするようにユーザーに求め、ユーザートークンを取得し、そのトークンを使用してバックエンドシステムからユーザーの情報を取得できることを意味します。

ヒント

Copilot Studio および Microsoft Teams で作成されたエージェントは、 Microsoft Entra ID認証用に自動的に構成されます。

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

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

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

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

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

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

重要

サインイン トピックは、Copilot Studio が提供する認証方法を提供するためだけに使用することをお勧めします。他のアクションやフロー、または他の認証方法を呼び出すせるように変更しないでください。

Copilot Studioでエージェントを開き、ページ上部の選択設定をクリックして、選択 セキュリティをクリックします。
認証を選択します。
手動で認証するを選択し、ユーザーにログインを要求するを選択します。
必要に応じて、すべての手動認証フィールドを構成します。
保存を選びます。

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

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

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

ページ上部の設定を選択し、セキュリティを選択します。
認証タイルを選択します。

注意Note

カスタムトピックにユーザー認証を追加するには、手動で認証 を選択する必要があります。
ユーザーにサインインを要求する チェックボックスをオフにします。
必要に応じて、すべての手動認証フィールドを構成します。
保存を選びます。
ページ上部にある トピック を選択します。
ノードを追加 ( ) >詳細>認証を選択します。
ID プロバイダーで構成されたユーザーを使用して、トピックをテストするを実行します。

チップ

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

認証変数

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

変数の詳細については、変数を使って作業するを参照してください。

認証変数	認証なし	Microsoft で認証する	手動で認証する
User.DisplayName	該当なし	対応可能	対応可能
User.FirstName	該当なし	対応可能	対応可能
User.LastName	該当なし	対応可能	対応可能
User.PrincipalName	該当なし	対応可能	対応可能
User.Email	該当なし	対応可能	対応可能
User.Id	該当なし	対応可能	対応可能
User.IsLoggedIn	該当なし	対応可能	対応可能
User.AccessToken	該当なし	該当なし	対応可能
SignInReason	該当なし	対応可能	対応可能

User.DisplayName

警告

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

User.DisplayName 変数には、ID プロバイダーに保存されている表示名が含まれます。この変数を使用すると、ユーザーがエージェントに名前を明示的に入力しなくても、ユーザーに挨拶したり参照したりできるため、会話がよりパーソナライズされます。

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

User.Id

警告

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

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 ユーザーがログインしておらず、会話の中で認証変数を使用する段階に到達したときに、ログインするように求められることを示します。

認証変数

エージェントが 「Microsoftで認証」 または 「手動」 認証オプションのいずれかで構成されている場合は、トピックで使用できる認証変数のセットが利用できます。エージェントで認証を構成する方法の詳細については、「ユーザー認証を構成する」 Copilot Studioを参照してください。

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

認証変数	認証なし	Microsoft で認証する	手動
`User.DisplayName`	❌	✔️	✔️
`User.Id`	❌	✔️	✔️
`User.IsLoggedIn`	❌	❌	✔️
`User.AccessToken`	❌	❌	✔️

UserDisplayName 変数

User.DisplayName 変数には、ID プロバイダーに保存されているユーザーの表示名が含まれます。この変数を使用すると、エンドユーザーがエージェントに明示的に指示しなくても、よりパーソナライズされた挨拶や参照を行うことができます。

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

UserID 変数

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

警告

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

IsLoggedIn 変数

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

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

User.AccessToken変数

警告

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

認証変数のテスト

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

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

次の表に、これらの変数を設定するコマンドを示します。これらのコマンドは ボットのテスト ペインにのみ適用されます。チャネルにデプロイされた公開済みのエージェントでは使用できません。

通常のエージェントとのチャットと同じように、 ボットのテスト ペインに必要なコマンドを入力します。成功すると、エージェントから確認メッセージが届きます。エージェントが認証を使用しない場合は、エラーが発生します。

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

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

重要

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

「Microsoftで認証」を使用する場合の認証

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

注意

認証オプションが Microsoft との認証 に設定されている場合、トピックに認証を明示的に追加するオプションは必要はありません。

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

認証ノードは、ユーザーにサインインカードを使用してログインするよう要求します。ユーザーがログインすると、別の認証ノードに到達しても再度プロンプトは表示されません。

サインインの要求。

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

エージェントに SSO が設定されている場合、ユーザーはログインを求められません。

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

編集したいエージェントのトピックページに移動します。
認証テンプレートの追加を行うトピックを開きます。

ヒント

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

Note

認証ノードは、ダイアログツリーの最後のアクションピッカーで (リーフノードとして) のみ使用できます。ダイアログの途中で追加することはできません。追加したら、他のノードをその下に追加できます。

新規ノードが自動的に現れます: 親認証ノードが含まれ、後に成功パスと失敗パスの両方のノードが続きます。

Authenticate ノードなしで、User.AccessToken を使用

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

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

Note

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

成功パス

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

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

失敗パス

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

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

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

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

次の方法で共有

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