將使用者驗證新增至主題

您可以直接在副手交談中啟用使用者驗證。 您可以將使用者的基本屬性 (例如名稱和 ID) 指派給變數。 您也可以提示使用者使用主題中的驗證節點登入，該驗證節點會擷取使用者權杖，然後使用該權杖從後端系統檢索使用者的資訊。

注意

在 Copilot Studio 和 Microsoft Teams 中建立的副手會自動設定為進行 Microsoft Entra ID 驗證。

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

先決條件

• 使用變數
• 在 Copilot Studio 中設定使用者驗證

Web 應用程式

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

使用 Microsoft Entra ID 設定手動驗證

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

請依照使用 Microsoft Entra ID 設定使用者驗證中的說明進行操作。

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

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

重要

建議登入主題僅用於提供 Copilot Studio 提供的驗證方法。 不應對其進行修改以呼叫任何其他動作或流程，或其他驗證方法。

1. 在 Copilot Studio 中打開副手後，選取頁面頂部的設定，然後選取安全性。

2. 選取驗證。

3. 選取手動驗證，然後選取要求使用者登入。

4. 根據需要設定所有手動驗證欄位。

5. 選取儲存。

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

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

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

1. 選取頁面頂端的設定，然後選取安全性。

2. 選取驗證圖格。

   注意

   您必須選取手動驗證才能將使用者驗證新增至自訂主題。

3. 清除要求使用者登入核取方塊。

4. 根據需要設定所有手動驗證欄位。

5. 選取儲存。

6. 選取頁面頂端的主題。

7. 選取新增節點 () >進階>認證。

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

提示

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

驗證變數

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

有關變數的更多資訊，請參閱使用變數。

驗證變數	無驗證	使用 Microsoft 進行驗證	手動驗證
User.DisplayName	無法使用	可提供服務	可提供服務
User.FirstName	無法使用	可提供服務	可提供服務
User.LastName	無法使用	可提供服務	可提供服務
User.PrincipalName	無法使用	可提供服務	可提供服務
User.Email	無法使用	可提供服務	可提供服務
User.Id	無法使用	可提供服務	可提供服務
User.IsLoggedIn	無法使用	可提供服務	可提供服務
User.AccessToken	無法使用	無法使用	可提供服務
SignInReason	無法使用	可提供服務	可提供服務

User.DisplayName

警告

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

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

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

User.Id

警告

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

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

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 表示當使用者未登入並且到達交談中使用驗證變數的點時，系統會提示他們登入。

傳統

驗證變數

如果您的副手設定了透過 Microsoft 進行驗證或手動驗證選項，則您的主題中將有一組可用的驗證變數。 如需深入了解如何在副手中設定驗證，請參閱在 Copilot Studio 中設定使用者驗證。

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

驗證變數	無驗證	使用 Microsoft 進行驗證	手動
User.DisplayName	❌	✔️	✔️
User.Id	❌	✔️	✔️
User.IsLoggedIn	❌	❌	✔️
User.AccessToken	❌	❌	✔️

UserDisplayName 變數

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

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

UserID 變數

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

警告

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

IsLoggedIn 變數

User.IsLoggedIn 變數表示使用者是否已登入 (結果是登入中或已登入，也稱為登入成功路徑) 或尚未登入 (結果為登入失敗路徑)。

User.IsLoggedIn 是包含使用者登入狀態的布林值變數。 您可以使用此變數來建立主題中的分支邏輯，檢查是否已成功登入 (例如，在新增驗證節點的過程中已提供的範本)，或只在使用者登入時，才有機會獲取使用者資訊。

User.AccessToken 變數

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

警告

確定您只是將 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 進行驗證，您將無法選擇向您的主題明確新增驗證。

新增使用者驗證至主題

驗證節點提示使用者使用登入卡片登入。 使用者登入後，即使他們到達另一個驗證節點，也不會再次收到提示。

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

當您已為副手設定 SSO 時，則不會提示使用者登入。

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

1. 移至您要編輯之副手的主題頁面。

2. 開啟要新增驗證範本的主題。

   注意

   如果您的副手已連接到 Dynamics 365 Customer Service，則驗證節點不能是副手最初問候使用者時遵循的交談路徑的一部分；否則，登入卡將顯示兩次。 相反，您應該將驗證節點新增至由使用者回應觸發的另一個主題。

3. 選取新增節點 (+) 以新增訊息節點。 輸入副手應該說什麼來表明將發生登入體驗。

   

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

   

   Note

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

   新節點會自動出現：上層驗證節點，後面是成功路徑和失敗路徑的節點。

在沒有驗證節點的情況下使用 User.AccessToken

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

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

Note

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

成功路徑

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

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

失敗路徑

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

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

測試您的主題

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

相關內容

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