新增單一登錄

6 分鐘

在本單元中，您將瞭解如何使用 Microsoft Entra 將單一登錄新增至訊息延伸模組。

使用單一登錄設定Teams應用程式

Microsoft Teams 應用程式支援使用 Microsoft Entra 的單一登錄 (SSO) 。 SSO 可讓使用者登入一次，並存取多個應用程式，而不需要再次登入。

若要設定 SSO，您可以設定 Azure Bot 資源Microsoft Entra 應用程式註冊，以代表使用者提出要求。

在 Microsoft Entra 應用程式註冊上，您會設定下列設定：

應用程式識別碼 URI，這是應用程式註冊的唯一標識碼，用來識別用戶端在應用程式中起始單一登錄流程時應該使用的資源。
範圍，授與 Bot 存取用戶數據的許可權。
授權的用戶端應用程式，允許向應用程式註冊要求令牌的用戶端應用程式。

在應用程式指令清單中，webApplicationInfo 物件是使用 Bot 的識別碼和應用程式識別碼 URI 來設定。他們會決定用戶端在應用程式中起始單一登錄流程時應該使用的資源。

下列代碼段顯示如何在應用程式指令清單檔案中設定 webApplicationInfo 物件：

"webApplicationInfo": {
    "id": "dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a",
    "resource": "api://grttxrk0-5130.uks1.devtunnels.ms/botid-dbeb8ea7-8ac3-4bb2-bcba-b210b087a73a"
}

設定 OAuth 連線

Azure Bot 資源可讓您存取 Bot Framework 令牌服務。令牌服務可用來使用您所設定的 OAuth 連線設定，為使用者取得存取令牌。令牌會安全地儲存在服務中，並在 Bot 程式代碼中需要時擷取。

若要建立連線設定，您可以設定下列設定：

名稱 - 連線設定的名稱。
服務提供者 - 連線用來驗證使用者的識別提供者。線上設定支援數個識別提供者，包括 Microsoft Entra。
用戶端識別碼 - 來自Microsoft Entra 應用程式註冊的用戶端標識符，該註冊是以存取用戶數據所需的許可權設定。
客戶端密碼 - 來自Microsoft Entra 應用程式註冊的用戶端密碼，該註冊設定了存取用戶數據所需的許可權。
令牌 Exchange URL - 用戶端在應用程式中起始單一登錄流程時應該使用的 URL。
租使用者標識碼 - Microsoft Entra 應用程式註冊所在的租用戶標識碼。
範圍 - 授與 Bot 存取使用者數據的許可權。

下列代碼段示範如何在 Bicep 檔案中設定 OAuth 連線設定：

resource botServiceProductsAPIConnection 'Microsoft.BotService/botServices/connections@2022-09-15' = {
    parent: botService
    name: 'Products API'
    location: 'global'
    properties: {
        serviceProviderDisplayName: 'Azure Active Directory v2'
        serviceProviderId: '30dd229c-58e3-4a48-bdfd-91ec48eb906c'
        clientId: productsApiEntraAppClientId
        clientSecret: productsApiEntraAppClientSecret
        scopes: 'api://${backendApiEntraAppClientId}/Product.Read'
        parameters: [
            {
                key: 'tenantID'
                value: 'common'
            }
            {
                key: 'tokenExchangeUrl'
                value: 'api://${botAppDomain}/botid-${botEntraAppClientId}'
            }
        ]
    }
}

提示

建議您建立新的Microsoft用戶對服務驗證的 Entra 應用程式註冊。搭配 Azure Bot 服務使用的應用程式註冊應該保持分開，並用於 Web 服務與 Bot 服務之間的服務對服務驗證。

與連線設定搭配使用的 Microsoft Entra 應用程式註冊必須設定為使用重新導向 URI https://token.botframework.com/.auth/web/redirect ，才能成功從 Bot Framework 令牌服務取得存取令牌。重新導向 URI 可用來在使用者驗證之後，將存取令牌傳回令牌服務。

當令牌服務重新導向 URI 裝載於外部網域時，它必須包含在應用程式指令清單檔案中。 validDomains 陣列會告知用戶端應用程式要使用的網域。它可確保用戶端可以在起始單一登錄流程時信任網域。

下列代碼段示範如何將網域新增至應用程式指令清單檔案：

"validDomains": [
    "token.botframework.com"
]

驗證用戶查詢

若要在訊息延伸模組中驗證用戶查詢，您可以使用 Bot Framework SDK 從 Bot Framework 令牌服務取得使用者的存取令牌。存取令牌接著可用來存取外部服務的數據。

首先，您會檢查令牌服務中是否有使用者的令牌存在。

下列代碼段示範如何取得 UserTokenClient ，並使用 GetUserTokenAsync 方法，使用具名 OAuth 連線設定傳回使用者的存取令牌：

var userTokenClient = turnContext.TurnState.Get<UserTokenClient>();

var tokenResponse = await userTokenClient.GetUserTokenAsync(userId, connectionName, channelId, magicCode, cancellationToken);

如果未傳回令牌，您必須要求使用者登入。建立在使用者介面中轉譯連結的回應，使用者可以遵循此回應來啟動登入流程。

下列代碼段示範 如何使用 GetSignInResourceAsync 方法從令牌服務傳回登入連結，並將其包含在訊息擴充功能回應中：

var resource = await userTokenClient.GetSignInResourceAsync(connectionName, activity, null, cancellationToken);

return new MessagingExtensionResponse
{
    ComposeExtension = new MessagingExtensionResult
    {
        Type = "auth",
        SuggestedActions = new MessagingExtensionSuggestedAction
        {
            Actions = [
                new() {
                    Type = ActionTypes.OpenUrl,
                    Value = resource.SignInLink,
                    Title = "Sign In",
                },
            ],
        },
    },
};

當使用者遵循登入連結時，他們會同意 OAuth 連線設定上 [範圍] 欄位中要求的許可權。在使用者同意許可權之後，令牌服務會取得存取令牌，並將其安全地儲存在服務中。

下次使用者在訊息延伸模組中起始搜尋時，會在令牌服務中找到存取令牌。傳回的存取令牌可用來存取外部服務的數據。

新增單一登錄

使用單一登錄設定Teams應用程式

設定 OAuth 連線

驗證用戶查詢

意見反應