新增使用者驗證至副手

重要

在對生成式 AI 進行大量投資並增強 Microsoft Copilot 的整合後，Power Virtual Agents 的功能和特性現已成為 Microsoft Copilot Studio 的一部分。

當我們更新文件和培訓內容時，某些文章和螢幕擷取畫面可能會參考 Power Virtual Agents。

您可以直接在副手交談中啟用使用者驗證。 使用者驗證是指您可以在變數中取得使用者的基本屬性 (如名稱和識別碼)，但也可以提示使用者使用驗證節點登入、擷取該使用者的使用者權杖，然後使用該權杖從後端系統擷取使用者的資訊。

注意

在 Web 應用程式和 Microsoft Teams 中建立的副手，均隨附預先設定的驗證，以使用僅適用於 Teams 和 Power Apps驗證。

您也可以設定單一登入 (SSO)，讓您的使用者不需要手動登入。 如需詳細資訊，請參閱設定 Web 的 SSO。

先決條件

• 使用變數
• 設定終端使用者驗證。

Web 應用程式

將使用者驗證新增至主題，以允許客戶直接在交談中登入。 接著就可以透過使用者變數將交談個人化，並代表使用者存取後端系統。

使用 Microsoft Entra ID 設定手動驗證

您需要使用 Microsoft Entra ID 設定使用者驗證，然後才能在主題中使用驗證。

1. 請依照使用 Microsoft Entra ID 設定使用者驗證中的說明進行操作。
2. 返回此文章。

使用登入系統主題新增使用者驗證

建立副手時，Microsoft Copilot Studio 會自動新增一個名為登入的系統主題。 若要使用它，您必須將副手的驗證設定為手動，並要求使用者登入。 當客戶開始與副手交談時，即會觸發登入主題並提示使用者登入。 您可以根據副手的情況自訂登入主題。

1. 在導覽功能表的設定底下，選取安全性。

2. 選取驗證圖格。

3. 選取手動 (用於自訂網站)，然後選取要求使用者登入。

   

   

使用自訂主題新增使用者驗證

登入主題會在交談開始時驗證使用者。 若要允許使用者稍後再登入，您可以將驗證節點新增至任何自訂主題。

客戶輸入使用者名稱和密碼時，系統可能會提示他們輸入驗證碼。 客戶登入後，即使他們到達另一個驗證節點，也不會再次收到提示。

1. 在導覽功能表的設定底下，選取安全性。

2. 選取驗證圖格。

3. 關閉要求使用者登入。

4. 在導覽功能表中，選取主題，然後開啟您要將驗證新增到的主題。

5. 選取新增節點 (+)，選取呼叫動作，然後選取驗證。

6. 透過識別提供者所設定的使用者來測試主題。

提示

對於成功的登入和失敗的登入，都務必要建立路徑。 登入失敗可能有多種原因，包括識別提供者登入體驗發生錯誤。

驗證變數

為副手設定使用者驗證後，您就可以在主題中使用驗證變數。 下表根據您選擇的驗證選項比較這些變數的可用性。

驗證變數	無驗證	僅適用於 Teams 和 Power Apps	手動
User.DisplayName	不適用	可用	可用
User.FirstName	不適用	可用	可用
User.LastName	不適用	可用	可用
User.PrincipalName	不適用	可用	可用
User.Email	不適用	可用	可用
User.Id	不適用	可用	可用
User.IsLoggedIn	不適用	可用	可用
User.AccessToken	不適用	不適用	可用
SignInReason	不適用	可用	可用

User.DisplayName

警告

這個變數不一定包含值。 使用識別提供者中的使用者進行測試，以確保主題可以正確運作。

User.DisplayName 變數包含識別提供者中儲存的顯示名稱。 使用此變數來問候或提及使用者，而不需要使用者明確告知副手其姓名，從而使交談更加個人化。

只要在設定手動驗證時定義了 profile 範圍，Microsoft Copilot Studio 就會根據識別提供者提供的 name 宣告自動設定 User.DisplayName 的值。 有關範圍的詳細資訊，請參閱使用 Microsoft Entra ID 設定使用者驗證。

User.Id

警告

這個變數不一定包含值。 使用識別提供者中的使用者進行測試，以確保主題可以正確運作。

User.Id 變數包含識別提供者中儲存的 userID。 在 Power Automate 流程中使用此變數來呼叫將 UserID 作為值的 API。

Microsoft Copilot Studio 會根據識別提供者提供的 sub 宣告自動設定 User.DisplayName 的值。

User.IsLoggedIn

User.IsLoggedIn 是儲存使用者登入狀態的布林值類型變數。 true 的值表示使用者已登入。 您可以使用此變數來建立主題中檢查是否成功登入的分支邏輯，或只在使用者登入時，才擷取使用者資訊。

User.AccessToken

警告

確定您只是將 User.AccessToken 變數傳遞給信任的來源。 它包含使用者驗證資訊，如果洩漏的話，可能會損害使用者。

User.AccessToken 變數包含在使用者登入之後所取得的使用者權杖。 您可以將此變數傳遞至 Power Automate 流程，這樣就可以連接至後端 API 並讀取使用者資訊，或代表使用者執行動作。

不要在訊息節點或您不信任的流程中使用 User.AccessToken。

SignInReason

SignInReason 是一個選擇類型變數，指示使用者何時必須登入。 其有兩個可能的值：

• SignInRequired 表示使用者必須在交談開始時使用登入系統主題登入。 要求使用者登入必須已開啟。

• Initializer 表示如果使用者尚未登入，且他們在交談中到達使用驗證變數的地方，則系統會提示他們登入。

傳統

驗證變數

如果您的機器人設定為使用僅適用於 Teams 和 Power Apps 或手動驗證選項，則您的主題中將有一組可用的驗證變數。 深入了解如何在機器人中設定驗證，請參閱 驗證設定文件。

下表比較驗證設定選項的驗證變數可用性：

驗證變數	無驗證	僅適用於 Teams 和 Power Apps	手動
UserDisplayName	❌	✔️	✔️
UserID	❌	✔️	✔️
IsLoggedIn	❌	❌	✔️
AuthToken	❌	❌	✔️

UserDisplayName 變數

UserDisplayName 變數包含識別提供者儲存的使用者的顯示名稱。 不需要終端使用者明確地告訴機器人相關資料，您可以使用此變數來問候或提及他們，讓機器人更加個人化。

此欄位的值是從 Microsoft Entra ID name 的宣告中取得。 對於 OAuth 提供者，這是儲存在 name 宣告的值。 Microsoft Copilot Studio 會自動將擷取此欄位到變數，因此請確保您將 profile 當作驗證範圍設定的一部分。

UserID 變數

UserID 變數包含識別提供者儲存的使用者識別碼。 此值可被 Power Automate 流程拿來呼叫用 UserID 為值的 API。 此欄位的值是從 Microsoft Entra ID sub 的宣告中取得。 對於 OAuth 提供者，這是儲存在 sub 宣告的值。 Microsoft Copilot Studio 會自動擷取此欄位到變數中。

警告

UserDisplayName 和 UserID 變數都不能保證會被填入，而且可能會是空字串，這取決於識別提供者的使用者設定。 從您的識別提供者處測試使用者，以確保您的主題可以正確地運作，即使這些變數是空值也一樣。

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，您就沒有選項可以明確地將驗證新增至您的主題。

新增使用者驗證至主題

驗證節點將會提示使用者使用登入卡登入。 如果使用者已經登入，則系統不會再出現提示，即使他們到達另一個驗證節點也一樣。

使用者在提示字元（由識別提供者託管）輸入使用者名和密碼之後，可能會提示您輸入驗證碼，具體視管道而定。 某些管道（例如 Microsoft Teams）不需要使用者輸入驗證碼。

當您已設定機器人使用 SSO，則不會提示使用者登入。

若要將驗證節點新增至您的主題：

1. 移至您要編輯之機器人的主題頁面。

2. 針對您要新增驗證範本的主題，開啟製作畫布。

   Note

   如果 Bot 已連接至 Dynamics 365 Customer Service，則驗證節點不可以是 Bot 最初問候使用者時所依循之交談路徑的一部分；否則，登入卡會顯示兩次。 您應該將驗證節點新增至使用者回覆所觸發的另一個主題。

3. 選取新增節點 (+) 以新增訊息節點。 輸入機器人應該說什麼來指示將要進行的登入體驗。

   

4. 在訊息節點底下，選取新增節點 (+)，再選取呼叫動作，接著選取驗證。

   

   Note

   驗證節點只能在對話樹結尾的動作選擇器中使用，就像分葉節點一樣。 無法在對話的中間新增它。 完成新增後，即可在該節點下方新增其他節點。

5. 選取之後，會自動新增數個新節點。 這些節點包括上層驗證節點，後面跟著成功和失敗路徑的節點。

   

沒有驗證節點的 AuthToken 使用情況

即使您不使用由呼叫動作功能表項目提供的範本，也可以使用 IsLoggedIn 和 AuthToken 變數。 如果您傳遞 AuthToken 變數，但不先讓使用者經過驗證節點，則系統會提示使用者在該步驟登入。

如果如果您預計使用者都是在登入中，或者如果您的使用者是從不同的主題重新導向過來的，則傳遞 AuthToken 變數會很有用。 我們建議您使用呼叫動作項目所提供的範本，來處理使用者無法登入的案例。

Note

如果使用者在交談中間登出，而主題進入使用 AuthToken 變數的節點時，會出現重新登入的提示。

成功路徑

成功路徑相當於 IsLoggedIn = True 的位置，並說明使用者成功登入（或已經登入）的時間。

如果您有使用 AuthToken 變數的邏輯（例如，使用流程擷取使用者的資訊來連接後端系統），則它應該會移至此路徑下。

失敗路徑

失敗路徑相當於 IsLoggedIn = True 以外的任何條件。 在大多數的案例中，失敗路徑的發生原因是使用者用了錯誤的密碼而登入失敗，或是取消了登入體驗。

新增你想用來處理此案例的任何邏輯。 例如，我們提供重試或上呈給即時助理的選項。 為您的特定案例和用法來自訂失敗路徑的動作。

測試您的主題

請務必使用您的識別提供者中真實的使用者設定來測試主題。 確保登入成功與失敗路徑都會執行，以便如果您的使用者無法登入或發生識別提供者的登入體驗錯誤，不會發生任何意外。

相關主題

您也可以設定單一登入 (SSO)，讓您的使用者不需要手動登入。 如需詳細資訊，請參閱設定 Web 的 SSO。