將驗證新增至 Bot

發行項
01/11/2024

適用於： SDK v4

Azure AI Bot Service v4 SDK 可協助開發 Bot，以存取需要使用者驗證的在線資源。您的 Bot 不需要管理驗證令牌，因為 Azure 會為您使用 OAuth 2.0 來根據每個使用者的認證產生令牌。您的 Bot 會使用 Azure 所產生的令牌來存取這些資源。如此一來，使用者就不需要提供標識符和密碼給 Bot，即可存取受保護的資源，而只能提供給受信任的識別提供者。

如需 Bot Framework 如何處理這類驗證的概觀，請參閱用戶驗證。

本文參考兩個範例。其中一個示範如何取得驗證令牌。另一個較複雜，並示範如何代表使用者存取 Microsoft Graph 。在這兩種情況下，您可以使用 Azure AD v1 或 v2 作為識別提供者來取得 Bot 的 OAuth 令牌。本文說明如何：

建立 Azure Bot 資源
建立 Microsoft Entra ID 識別提供者
向 Bot 註冊 Microsoft Entra ID 識別提供者
準備 Bot 程式代碼

完成本文之後，您就會有一個 Bot，可以回應一些簡單的工作。在 Microsoft Graph 範例中，您可以傳送電子郵件、顯示您是誰，以及檢查最近的電子郵件。您不需要發佈 Bot 來測試 OAuth 功能;不過，Bot 將需要有效的 Azure 應用程式識別碼和密碼。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Power Virtual Agents ，並閱讀選擇正確的聊天機器人解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

網路聊天和 Direct Line 考慮

重要

您必須使用已啟用增強驗證的 Direct Line，以在使用網路聊天控件連線到 Bot 時降低安全性風險。如需詳細資訊，請參閱 Direct Line 增強驗證。

必要條件

Bot 基本概念、管理狀態、對話連結庫，以及如何實作循序對話流程，以及如何重複使用對話的知識。
瞭解 Azure 和 OAuth 2.0 開發。
適用於 .NET 的 Visual Studio 2017 或更新版本。
適用於 JavaScript 的Node.js。
Python 3.8+ for Python。

下面所列的其中一個範例。

範例	BotBuilder 版本	示範
C# 或 JavaScript 或 Java 或 Python 中的驗證	v4	OAuthCard 支援
C# 或 JavaScript 或 Java 或 Python 中的 Microsoft Graph 驗證	v4	OAuth 2.0 的 Microsoft Graph API 支援
C# 或 JavaScript 或 Java 或 Python 中的 Microsoft Teams 驗證	v4	OAuth 2.0 的 Microsoft Graph API 支援

若要執行本文中參考的範例，您需要：

在 Azure 中註冊 Bot 資源的 Microsoft Entra ID 應用程式。此應用程式可讓 Bot 存取外部安全資源，例如 Microsoft Graph。它也允許使用者透過數個通道與 Bot 通訊，例如網路聊天。
作為識別提供者的個別 Microsoft Entra ID 應用程式。此應用程式提供建立 Bot 與受保護資源之間 OAuth 連線所需的認證。請注意，本文使用 Active Directory 作為識別提供者。其他許多提供者也受到支援。

重要

每當您在 Azure 中註冊 Bot 時，就會獲指派 Microsoft Entra ID 應用程式。不過，此應用程式可保護通道對 Bot 的存取。您需要每個外部安全資源的額外 Microsoft Entra ID 應用程式，讓 Bot 代表使用者存取。

建立資源

建立 Azure Bot 資源，可讓您向 Azure AI Bot 服務註冊 Bot。

提示

無法建立新的 Web 應用程式 Bot 和 Bot 通道註冊 資源;不過，任何已設定和部署的現有資源都會繼續運作。從 SDK 4.14.1.2 版或更新版本建立的 VSIX 或 Yeoman 樣本所建立的 Bot 包含將產生 Azure Bot 資源的 ARM 範本。

前往 Azure 入口網站。
在右窗格中，選取 [建立資源]。
在搜尋方塊中輸入 bot，然後按 Enter。
選取 Azure Bot 卡片。
選取建立。
在必要欄位中輸入值，然後檢閱和更新設定。
1. 提供 [專案詳細數據] 底下的資訊。選取您的 Bot 是否具有全域或本機數據落地。目前，本機數據落地功能適用於「westeurope」和「centralindia」區域中的資源。如需詳細資訊，請參閱 Azure AI Bot Service 中的區域化。
2. 提供 Microsoft 應用程式識別子下的資訊。選取如何在 Azure 中管理 Bot 身分識別，以及建立新的身分識別或使用現有的身分識別。
選取 [檢閱 + 建立]。
如果驗證通過，請選取 [ 建立]。
部署完成後，請選取 [移至資源]。您應該會看到 Bot 和相關資源列在您選取的資源群組中。
如果您還沒有 Bot Framework SDK，請選取 [從 GitHub 下載] 以瞭解如何取用您慣用語言的套件。

您現在已準備好使用 Bot Framework SDK 建置 Bot。

提示

當 Azure 使用新的應用程式識別碼建立新的單一租使用者或多租使用者 Azure Bot 資源時，也會產生密碼。

Bot 身分識別資訊

請遵循下列步驟，將身分識別資訊新增至 Bot 的組態檔。檔案會根據您用來建立 Bot 的程式設計語言而有所不同。

重要

Bot Framework SDK 的 Java 版本僅支援多租使用者 Bot。 Bot Framework SDK 的 Python 版本支援多租使用者和單一租使用者 Bot。 C# 和 JavaScript 版本支援這三種應用程式類型來管理 Bot 的身分識別。

語言	檔案名稱	備註
C#	appsettings.json	支援這三種應用程式類型來管理 Bot 的身分識別。
JavaScript	.env	支援這三種應用程式類型來管理 Bot 的身分識別。
Java	application.properties	僅支援多租使用者 Bot。
Python	config.py	支援多租使用者和單一租使用者 Bot。提供屬性做為方法呼叫的 `os.environ.get` 自變數。

您需要新增的身分識別資訊取決於 Bot 的應用程式類型。在您的組態檔中提供下列值。

僅適用於 C# 和 JavaScript Bot。

屬性	值
`MicrosoftAppType`	`UserAssignedMSI`
`MicrosoftAppId`	使用者指派受控識別的用戶端標識碼。
`MicrosoftAppPassword`	不適用。針對使用者指派的受控識別 Bot，將此保留空白。
`MicrosoftAppTenantId`	使用者指派受控識別的租用戶標識碼。

僅適用於 C#、JavaScript 和 Python Bot。

屬性	值
`MicrosoftAppType`	`SingleTenant`
`MicrosoftAppId`	Bot 的應用程式識別碼。
`MicrosoftAppPassword`	Bot 的應用程式密碼。
`MicrosoftAppTenantId`	Bot 的應用程式租用戶標識碼。

適用於所有程式設計語言的 Bot：C#、JavaScript、Java 和 Python。

屬性	值
`MicrosoftAppType`	`MultiTenant`
`MicrosoftAppId`	Bot 的應用程式識別碼。
`MicrosoftAppPassword`	Bot 的應用程式密碼。
`MicrosoftAppTenantId`	不適用。針對多租使用者 Bot 保留此空白。

更新您的應用程式服務

如果您的 Bot 有現有的 App Service 資源（Web 應用程式），而 Bot 是 使用者指派的受控識別 應用程式，您可能需要更新 Bot 的應用程式服務：

移至 Bot Web 應用程式的 App Service 刀鋒視窗。
在 [設定] 下，選取 [身分識別]。
在 [ 身分識別] 刀鋒視窗上，選取 [ 使用者指派] 索引標籤和 [新增 ] （+）。
在 [ 新增使用者指派的受控識別 ] 刀鋒視窗上：
1. 選取您的訂用帳戶。
2. 針對 [使用者指派的受控識別]，選取 Bot 的受控識別。如果為您自動產生受控識別，其名稱會與您的 Bot 相同。
3. 選取 [ 新增 ] 以針對您的 Bot 使用此身分識別。

取得您的應用程式或租用戶識別碼

若要取得 Bot 的應用程式或租使用者識別碼：

移至 Bot 的 [Azure Bot 資源] 刀鋒視窗。
移至 Bot 的 [設定 ] 刀鋒視窗。從此刀鋒視窗中，您可以複製 Bot 的 Microsoft 應用程式識別碼 或 應用程式租使用者識別碼。

產生新密碼

單一租使用者和多租使用者 Bot 具有某些作業所需的應用程式秘密或密碼。 Azure AI Bot Service 會隱藏 Bot 秘密。不過，Bot App Service 資源的擁有者可以產生新的密碼：

移至 Bot 的 [Azure Bot 資源] 刀鋒視窗。
移至 Bot 的 [設定 ] 刀鋒視窗。
選取 [管理]，在 [Microsoft 應用程式標識符] 旁，移至 應用程式服務的 [憑證 + 秘密 ] 刀鋒視窗。
請遵循刀鋒視窗上的指示來建立新的客戶端密碼，並將值記錄在安全的地方。

Microsoft Entra ID 身分識別服務

Microsoft Entra ID 是雲端身分識別服務，可讓您建置應用程式，以使用 OAuth 2.0 等業界標準通訊協定安全地登入使用者。

您可以使用這兩個身分識別服務的其中一個：

Microsoft Entra ID 開發人員平臺（v1.0）。 也稱為 Azure AD v1 端點，可讓您建置應用程式，以使用 Microsoft 公司或學校帳戶安全地登入使用者。如需詳細資訊，請參閱適用於開發人員的 Microsoft Entra 識別碼（v1.0）概觀。
Microsoft 身分識別平台（v2.0）。 也稱為 Microsoft Entra 識別符端點，這是 Azure AD 平臺（v1.0）的演進。它可讓您建置登入所有 Microsoft 身分識別提供者的應用程式，並取得令牌來呼叫 Microsoft API，例如 Microsoft Graph 或其他開發人員建置的 API。如需詳細資訊，請參閱 Microsoft 身分識別平台（v2.0）概觀。

如需 v1 與 v2 端點之間差異的相關信息，請參閱為什麼更新為 Microsoft 身分識別平台（v2.0）？。如需完整資訊，請參閱 Microsoft 身分識別平台（先前為開發人員的 Microsoft Entra ID）。

建立 Microsoft Entra ID 識別提供者

本節說明如何建立使用 OAuth 2.0 驗證 Bot 的 Microsoft Entra ID 識別提供者。您可以使用 Azure AD v1 或 Microsoft Entra ID 端點。

提示

您必須在租使用者中建立和註冊 Microsoft Entra ID 應用程式，以便同意委派應用程式所要求的許可權。

在 Azure 入口網站中開啟 Microsoft Entra ID 面板。如果您不在正確的租使用者中，請選取 [ 切換目錄 ] 以切換至正確的租使用者。（如需如何建立租用戶的資訊，請參閱存取入口網站並建立租使用者。
開啟應用程式註冊面板。
在 [應用程式註冊] 面板中，選取 [新增註冊]。
填寫必要的欄位並建立應用程式註冊。
1. 為您的應用程式命名。
2. 選取應用程式的支持帳戶類型。（這些選項中的任何一個都會與這個範例搭配使用。
3. 針對 [ 重新導向 URI]，選取 [Web ]，並將 URL 設定為其中一個支援的 OAuth 重新導向 URL。
4. 選取註冊。
  - 建立之後，Azure 會顯示應用程式的 [ 概觀 ] 頁面。
  - 記錄應用程式（用戶端）識別碼值。您稍後會在建立連接字串並使用 Bot 註冊註冊 Microsoft Entra ID 提供者時，使用此值作為用戶端識別符。
  - 記錄目錄（租使用者）識別碼值。您將使用此值向 Bot 註冊此提供者應用程式。
在瀏覽窗格中，選取 [ 憑證和秘密 ] 來為您的應用程式建立秘密。
1. 在 [用戶端祕密] 下，選取 [新增用戶端祕密]。
2. 新增描述，以識別其他可能需要為此應用程式建立的秘密，例如 bot login。
3. 針對 [到期]，選擇密碼到期的時間長度。
4. 選取 [新增]。
5. 離開 憑證和秘密之前，請先記錄秘密。您稍後會在向 Bot 註冊 Microsoft Entra ID 應用程式時， 使用此值作為客戶端密碼 。
在瀏覽窗格中，選取 [API 許可權 ] 以開啟 [API 許可權 ] 面板。最佳做法是明確設定應用程式的 API 許可權。
1. 選取 [新增許可權 ] 以顯示 [要求 API 許可權 ] 窗格。
2. 在此範例中，選取 [Microsoft API ] 和 [Microsoft Graph]。
3. 選擇 [委派的許可權 ]，並確定已選取所需的許可權。此範例需要這些許可權。
  
  注意
  
  任何標示為 「需要管理員同意 」的許可權都需要使用者和租用戶系統管理員登入，因此您的 Bot 通常會遠離這些許可權。
  - Openid
  - profile
  - Mail.Read
  - Mail.Send
  - User.Read
  - User.ReadBasic.All
4. 選取新增權限。（使用者第一次透過 Bot 存取此應用程式時，必須授與同意。

您現在已設定 Microsoft Entra ID 應用程式。

注意

當您建立連接字串並使用 Bot 註冊註冊身分識別提供者時，您會指派應用程式（用戶端）識別碼和客戶端密碼。請參閱下一節。

向 Bot 註冊 Microsoft Entra ID 識別提供者

下一個步驟是向 Bot 註冊您的識別提供者。

Microsoft Entra ID
Azure AD v1

在 Azure 入口網站中開啟 Bot 的 Azure Bot 資源頁面。
選取設定。
在頁面底部附近的 OAuth 連線 ion 設定 下，選取 [新增設定]。
填寫表單，如下所示：
1. 名稱. 輸入您的連線名稱。您將在 Bot 程式代碼中使用。
2. 服務提供者。選取 [Microsoft Entra ID ] 以顯示 Microsoft Entra ID 特定字段。
3. 用戶端識別碼。輸入您為 Microsoft Entra ID 識別提供者記錄的應用程式（用戶端）識別碼。
4. 客戶端密碼。輸入您為 Microsoft Entra ID 識別提供者記錄的秘密。
  
  提示
  
  如果您想要使用憑證，您可以選取具有憑證提供者的 AAD v2。您必須為 Bot 服務令牌存放區（appid： 5b404cf4-a79d-4cfe-b866-24bf8e1a4921）提供取得憑證的許可權。
5. 令牌交換 URL。將它保留空白，因為它只用於 Microsoft Entra ID 中的 SSO。
6. 租用戶標識碼。 輸入您稍早為 Microsoft Entra ID 應用程式記錄的目錄（租使用者）標識碼，或根據您建立 Azure DD 應用程式時選取的支持帳戶類型而常見的目錄（租使用者）。若要決定要指派的值，請遵循下列準則：
  - 建立 Microsoft Entra 識別符應用程式時，如果您只選取 此組織目錄中的帳戶（僅限 Microsoft - 單一租使用者），請輸入您稍早為 Microsoft Entra ID 應用程式記錄的租使用者識別碼。
  - 不過，如果您在任何組織目錄中選取 [帳戶] （任何 Microsoft Entra ID 目錄 - 多租使用者和個人 Microsoft 帳戶，例如 Xbox、Outlook.com） 或 任何組織目錄中的帳戶（Microsoft Entra ID 目錄 - 多租使用者），請輸入 common 而不是租使用者標識符。否則，Microsoft Entra ID 應用程式會透過已選取標識碼並排除個人 Microsoft 帳戶的租用戶進行驗證。
  這會是與可驗證的使用者相關聯的租使用者。如需詳細資訊，請參閱 Microsoft Entra ID 中的租用。
7. 針對 [範圍]，輸入您從應用程式註冊中選擇的許可權名稱。為了進行測試，您可以直接輸入： openid profile。
  
  注意
  
  針對 Microsoft Entra ID， [範圍 ] 欄位會採用區分大小寫、以空格分隔的值清單。
選取 [儲存]。

流覽至 Azure 入口網站上的 Bot 資源頁面。
選取設定。
在靠近頁面底部的 [OAuth 連線 ion 設定 下，選取 [新增設定]。
填寫表單，如下所示：
1. 針對 [ 名稱]，輸入連線的名稱。您將在 Bot 程式代碼中使用此名稱。
2. 針對 [服務提供者]，選取 [Microsoft Entra ID]。選取此項目之後，將會顯示 Microsoft Entra ID 特定欄位。
3. 針對 [ 用戶端識別符]，輸入您為 Azure AD v1 應用程式記錄的應用程式（client）識別碼。
4. 針對 [客戶端密碼]，輸入您建立的秘密，以授與 Bot 對 Microsoft Entra ID 應用程式的存取權。
5. 針對 [授與類型]，輸入 authorization_code。
6. 針對 [ 登入 URL]，輸入 https://login.microsoftonline.com。
7. 針對 [ 租使用者標識符]，輸入 您稍早為 Microsoft Entra ID 應用程式記錄的目錄（租使用者）標識符 ，或 根據您建立 ADD 應用程式時選取的支持帳戶類型而通用 。若要決定要指派的值，請遵循下列準則：
  - 建立 Microsoft Entra 識別符應用程式時，如果您只選取 此組織目錄中的帳戶（僅限 Microsoft - 單一租使用者），請輸入您稍早為 Microsoft Entra ID 應用程式記錄的租使用者識別碼。
  - 不過，如果您在任何組織目錄中選取 [帳戶] （任何 Microsoft Entra ID 目錄 - 多租使用者和個人 Microsoft 帳戶，例如 Xbox、Outlook.com） 或 任何組織目錄中的帳戶（Microsoft Entra ID 目錄 - 多租使用者），請輸入 common 而不是租使用者標識符。否則，Microsoft Entra ID 應用程式會透過已選取標識碼並排除個人 MS 帳戶的租用戶進行驗證。
  這會是與可驗證的使用者相關聯的租使用者。如需詳細資訊，請參閱 Microsoft Entra ID 中的租用。
8. 對於資源 URL，請輸入 https://graph.microsoft.com/。
9. 將 [範圍] 保留空白。
選取 [儲存]。

注意

這些值可讓應用程式透過 Microsoft Graph API 存取 Office 365 資料。此外， 令牌交換 URL 應該保留空白，因為它僅用於 Microsoft Entra 識別碼中的 SSO。

測試您的連線

選取連線項目以開啟您所建立的連接。
選取 [服務提供者連線設定] 窗格頂端的 [測試連線。
第一次，這應該會開啟新的瀏覽器索引標籤，其中列出您的應用程式要求的許可權，並提示您接受。
選取 [接受]。
然後，這應該會將您重新導向至 Test 連線 ion 至<您的連線名稱>成功頁面。

您現在可以在 Bot 程式代碼中使用此連線名稱來擷取使用者令牌。

準備 Bot 程式代碼

您需要 Bot 的應用程式識別碼和密碼，才能完成此程式。

從 GitHub 存放庫複製您想要使用範例：適用於 Microsoft Graph 的 Bot 驗證或 Bot 驗證。

更新 appsettings.json：

設定 ConnectionName 為您新增至 Bot 的 OAuth 連線設定名稱。
將和 MicrosoftAppPassword 設定MicrosoftAppId為 Bot 的應用程式識別碼和應用程式秘密。

視 Bot 秘密中的字元而定，您可能需要 XML 逸出密碼。例如，任何連字元（&）都必須編碼為 &。

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": ""
}

若要在 Bot 中使用 OAuth 搭配公用雲端中的數據落地，您必須在 appsettings 中新增下列設定

"OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

其中 <Regional-OAuth-Url> 是下列其中一個 URI：

URI	描述
`https://europe.api.botframework.com`	適用於在歐洲具有數據落地的公用雲端 Bot。
`https://unitedstates.api.botframework.com`	針對具有數據落地的公用雲端 Bot，美國。
`https://india.api.botframework.com`	適用於具有印度數據落地的公用雲端 Bot。

更新 Startup.cs：

若要在非公用 Azure 雲端中使用 OAuth，例如政府雲端，您必須在 Startup.cs 檔案中新增下列程序代碼。

string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

其中 <uri-to-use> 是下列其中一個 URI：

URI	描述
`https://api.botframework.azure.us`	針對沒有數據落地的美國政府雲端 Bot。
`https://api.botframework.com`	針對沒有數據落地的公用雲端 Bot。這是預設 URI，不需要變更 Startup.cs。

從您想要使用之 GitHub 存放庫複製：適用於 Microsoft Graph 的 Bot 驗證或 Bot 驗證。
更新 .env：
- 設定 connectionName 為您新增至 Bot 的 OAuth 連線設定名稱。
- 將和 MicrosoftAppPassword 值設定MicrosoftAppId為 Bot 的應用程式識別碼和應用程式秘密。
  
  視 Bot 秘密中的字元而定，您可能需要 XML 逸出密碼。例如，任何連字元（&）都必須編碼為 &。
```
MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
connectionName=
```

從 GitHub 存放庫複製您想要使用範例：適用於 Microsoft Graph 的 Bot 驗證或 Bot 驗證。
更新 application.properties：
- 設定 ConnectionName 為您新增至 Bot 的 OAuth 連線設定名稱。
- 將和 MicrosoftAppPassword 設定MicrosoftAppId為 Bot 的應用程式識別碼和應用程式秘密。
```
MicrosoftAppId=
MicrosoftAppPassword=
server.port=3978
ConnectionName=
```

複製您要使用之範例的 GitHub 存放庫：適用於 Microsoft Graph 的 Bot 驗證或 Bot 驗證。

更新 config.py：

設定 ConnectionName 為您新增至 Bot 的 OAuth 連線設定名稱。
將和 MicrosoftAppPassword 設定MicrosoftAppId為 Bot 的應用程式識別碼和應用程式秘密。

視 Bot 秘密中的字元而定，您可能需要 XML 逸出密碼。例如，任何連字元（&）都必須編碼為 &。

#!/usr/bin/env python3
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.

import os

""" Bot Configuration """


class DefaultConfig:
    """ Bot Configuration """

    PORT = 3978
    APP_ID = os.environ.get("MicrosoftAppId", "")
    APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
    APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
    APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
    CONNECTION_NAME = os.environ.get("ConnectionName", "")

若要取得 Microsoft 應用程式識別碼 和 Microsoft 應用程式密碼 值，請參閱取得註冊密碼。

注意

您現在可以將此 Bot 程式代碼發佈至您的 Azure 訂用帳戶（在項目上選取滑鼠右鍵並選擇 [發佈]），但本文並不需要這樣做。您必須設定發行組態，以使用您在 Azure 入口網站中設定 Bot 時所使用的應用程式和主控方案。

使用模擬器測試 Bot

如果您尚未這麼做，請安裝 Bot Framework 模擬器。另請參閱使用模擬器進行偵錯。

為了讓 Bot 範例登入能夠運作，您必須設定模擬器，如設定模擬器以進行驗證所示。

測試

設定驗證機制之後，您可以執行實際的 Bot 範例測試。

注意

系統可能會要求您輸入 魔術程式碼，因為 Bot 範例的實作方式。此魔術程式代碼是 RFC#7636 的一部分，而且會新增額外的安全性元素。藉由移除魔術程式代碼，安全性風險會增加。使用已啟用增強式驗證的 Direct Line 可以減輕此問題。如需詳細資訊，請參閱 Bot Framework 增強式驗證。

在本機計算機上執行 Bot 範例。
啟動模擬器。
當您連線到 Bot 時，您必須提供 Bot 的應用程式識別碼和密碼。
- 您可以從 Azure 應用程式註冊取得應用程式識別碼和密碼。這些是您在或 .env 檔案中appsettings.json指派給 Bot 應用程式的相同值。在模擬器中，您會在組態檔中指派這些值，或第一次連線到 Bot 時。
- 如果您需要在 Bot 程式代碼中逸出密碼，您也必須在這裡執行此動作。
輸入 help 以查看 Bot 可用命令的清單，並測試驗證功能。
登入之後，在註銷之前，您不需要再次提供認證。
若要登出並取消您的驗證，請輸入 logout。

注意

Bot 驗證需要使用 Bot 連線 or 服務。服務會從 Azure Bot 資源存取資訊。

驗證範例

在 Bot 驗證 範例中，對話的設計目的是在使用者登入之後擷取使用者令牌。

使用驗證範例 Bot 進行範例交談。

Microsoft Graph 的驗證範例

在 Microsoft Graph 的 Bot 驗證範例中，對話框的設計目的是在使用者登入之後接受一組有限的命令。

與 Microsoft Graph 驗證範例 Bot 的範例交談。

其他資訊

當使用者要求 Bot 執行需要 Bot 讓使用者登入的專案時，Bot 可以使用 OAuthPrompt 來起始擷取指定連線的令牌。會 OAuthPrompt 建立令牌擷取流程，其中包含：

檢查 Azure AI Bot Service 是否已經有目前使用者和連線的令牌。如果有令牌，則會傳回令牌。
如果 Azure AI Bot Service 沒有快取的令牌， OAuthCard 則會建立，這是使用者可以選取的登入按鈕。
在用戶選取 OAuthCard [登入] 按鈕之後，Azure AI Bot Service 會直接將使用者的令牌傳送給 Bot，或向使用者顯示 6 位數的驗證碼，以在聊天視窗中輸入。
如果使用者看到驗證碼，Bot 就會交換此驗證碼給使用者的令牌。

下列各節說明範例如何實作一些常見的驗證工作。

使用 OAuth 提示登入使用者並取得令牌

C# 範例的架構圖表。

Dialogs\MainDialog.cs

在其建構函式中，將 OAuth 提示新增至 MainDialog 。在這裡，從appsettings.json檔案擷取連線名稱的值。

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

在對話框步驟中，使用 BeginDialogAsync 來啟動 OAuth 提示，以要求使用者登入。

如果用戶已經登入，這會產生令牌回應事件，而不會提示使用者。
否則，這會提示使用者登入。 Azure AI Bot Service 會在用戶嘗試登入之後傳送令牌回應事件。

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

在下列對話框步驟中，檢查上一個步驟中是否有令牌是否存在。如果不是 Null，則使用者已成功登入。

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There is an example of this in the next method.
var tokenResponse = (TokenResponse)stepContext.Result;

JavaScript 範例的架構圖表。

dialogs/mainDialog.js

在其建構函式中，將 OAuth 提示新增至 MainDialog 。在這裡，已從 .env 檔案擷取連線名稱的值。

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

在對話框步驟中，使用 beginDialog 來啟動 OAuth 提示，以要求使用者登入。

如果用戶已經登入，這會產生令牌回應事件，而不會提示使用者。
否則，這會提示使用者登入。 Azure AI Bot Service 會在用戶嘗試登入之後傳送令牌回應事件。

const tokenResponse = stepContext.result;

在下列對話框步驟中，檢查上一個步驟中是否有令牌是否存在。如果不是 Null，則使用者已成功登入。

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

Java 範例的架構圖表。

MainDialog.java

在其建構函式中，將 OAuth 提示新增至 MainDialog 。在這裡，從 application.properties 檔案擷取連線名稱的值。

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

在對話框步驟中，使用 beginDialog 來啟動 OAuth 提示，以要求使用者登入。

如果用戶已經登入，這會產生令牌回應事件，而不會提示使用者。
否則，這會提示使用者登入。 Azure AI Bot Service 會在用戶嘗試登入之後傳送令牌回應事件。

return stepContext.beginDialog("OAuthPrompt");

在下列對話框步驟中，檢查上一個步驟中是否有令牌是否存在。如果不是 Null，則使用者已成功登入。

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

Python 範例的架構圖表。

dialogs/main_dialog.py

在其建構函式中，將 OAuth 提示新增至 MainDialog 。在這裡，從 config.py 檔案擷取連線名稱的值。

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

在對話框步驟中，使用 begin_dialog 來啟動 OAuth 提示，以要求使用者登入。

如果用戶已經登入，這會產生令牌回應事件，而不會提示使用者。
否則，這會提示使用者登入。 Azure AI Bot Service 會在用戶嘗試登入之後傳送令牌回應事件。

return await step_context.begin_dialog(OAuthPrompt.__name__)

在下列對話框步驟中，檢查上一個步驟中是否有令牌是否存在。如果不是 Null，則使用者已成功登入。

if step_context.result:
    await step_context.context.send_activity("You are now logged in.")
    return await step_context.prompt(
        ConfirmPrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Would you like to view your token?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

等候 TokenResponseEvent

當您啟動 OAuth 提示時，它會等候令牌回應事件，從中擷取使用者的令牌。

Bots\AuthBot.cs

AuthBot 衍生自 ActivityHandler 並明確處理令牌回應事件活動。在這裡，我們會繼續使用中的對話框，這可讓 OAuth 提示處理事件並擷取令牌。

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

bots/authBot.js

AuthBot 衍生自 ActivityHandler 並明確處理令牌回應事件活動。在這裡，我們會繼續使用中的對話框，這可讓 OAuth 提示處理事件並擷取令牌。

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot 衍生自 Dialog 並明確處理令牌回應事件活動。在這裡，我們會繼續使用中的對話框，這可讓 OAuth 提示處理事件並擷取令牌。

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot 會明確處理令牌回應事件活動。在這裡，我們會繼續使用中的對話框，這可讓 OAuth 提示處理事件並擷取令牌。

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

註銷使用者

最佳做法是讓使用者明確註銷，而不是依賴連線逾時。

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }
    }

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        text = inner_dc.context.activity.text.lower()
        if text == "logout":
            bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
            await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
            await inner_dc.context.send_activity("You have been signed out.")
            return await inner_dc.cancel_all_dialogs()

新增 Teams 驗證

OAuth 在Teams中處理的方式與其他頻道不同。 Teams 驗證 Bot 範例（在 C#、 JavaScript、 Java 或 Python 中）示範如何正確實作 Teams 的驗證。

進一步閱讀

Bot Framework 其他資源包含其他支持的連結。
Bot Framework SDK 存放庫具有與 Bot Builder SDK 相關聯之存放庫、範例、工具和規格的詳細資訊。

將驗證新增至 Bot

網路聊天 和 Direct Line 考慮

必要條件

建立資源

Bot 身分識別資訊

更新您的應用程式服務

取得您的應用程式或租用戶識別碼

產生新密碼

Microsoft Entra ID 身分識別服務

建立 Microsoft Entra ID 識別提供者

向 Bot 註冊 Microsoft Entra ID 識別提供者

測試您的連線

準備 Bot 程式代碼

使用模擬器測試 Bot

測試

驗證範例

Microsoft Graph 的驗證範例

其他資訊

使用 OAuth 提示登入使用者並取得令牌

等候 TokenResponseEvent

註銷使用者

新增 Teams 驗證

進一步閱讀

其他資源

網路聊天和 Direct Line 考慮