使用 Microsoft Entra ID 設定單一登入

Copilot Studio 支援單一登入 (SSO)。如果客戶已登入部署 Agent 的頁面或應用程式，SSO 允許您網站上的 Agent 讓客戶登入。

例如，Agent 託管在公司網路上，或使用者已登入的應用程式中。

為 Copilot Studio 設定 SSO 主要有五個步驟：

使用 Microsoft Entra ID 為您的 Agent 啟用手動驗證
在 Microsoft Entra ID 中為您的自訂畫佈建立應用程式註冊。
在 Microsoft Entra ID 中為您的 Agent 定義自訂範圍。
將自訂範圍新增至您的 Agent 設定。
設定您的自訂畫布用戶端程式碼以啟用 SSO。

必要條件

注意

若要使用其他 OAuth 2.0 提供者設定 SSO，請參閱使用通用 OAuth 提供者設定單一登入。

支援的管道

下表詳細描述目前支援 SSO 的管道。您可以在 Copilot Studio 上建議額外頻道的支援。

通道	已支援
Azure Bot Service 頻道	不支援
自訂網站	已支援
示範網站	不支援
Facebook	不支援
Microsoft Teams¹	已支援
行動應用程式	不支援
Customer Service 全通路²	已支援
SharePoint¹	已支援

¹ 如果您發佈至 Teams 管道，則需要依照在 Microsoft Teams 中使用 Microsoft Entra ID 為 Agent 設定單一登入文件中的設定說明進行操作。如果無法根據該頁面上的指示設定 Teams SSO 設定，會導致您的使用者在使用 Teams 管道時一直無法通過驗證。

² 僅支援即時聊天頻道。如需其他資訊，請參閱設定移交至 Dynamics 365 Customer Service。

重要

目前發佈 Agent 至 Power Apps 入口網站，並不支援 SSO。

Web 應用程式
Teams 方案

建立自訂網站的應用程式註冊

若要啟用 SSO，請建立兩個不同的應用程式註冊：

驗證應用程式註冊，為您的 Agent 啟用 Microsoft Entra ID 使用者驗證
畫布應用程式註冊，這會為自訂網頁啟用 SSO

基於安全性理由，我們不建議您的 Agent 和自訂網站重複使用相同的應用程式註冊。

若要建立驗證應用程式註冊，請依循使用 Microsoft Entra ID 設定使用者驗證中的指示。
建立第二個應用程式註冊，做為您的畫布應用程式註冊。

新增權杖交換 URL

若要更新 Copilot Studio 中的 Microsoft Entra ID 驗證設定，請新增權杖交換 URL，以允許您的應用程式和 Copilot Studio 共用資訊。

在身份驗證應用註冊頁上的 Azure 入口網站中，轉到公開 API。
在範圍下，選擇複製到剪貼簿圖示。
在 Copilot Studio 中，在導覽功能表的設定下，選擇安全性，然後選擇驗證圖塊。
在權杖交換 URL (SSO 的必要項) 中，將先前複製的範圍貼上。
選取儲存。

在驗證應用註冊頁面上的 Azure 入口網站中，移至概觀。
複製基本資料下的應用程式 (用戶端) ID 值。
在導覽列中，選擇管理>公開 API。
在授權的客戶端應用程式下，選擇新增客戶端應用程式，然後貼上先前複製的客戶端 ID。
選取儲存。

設定畫布應用程式註冊

建立畫布應用程式註冊之後，移至驗證，然後選取新增平台。
在平台設定下，選擇新增平台，然後選擇 SPA。
在重新導向 URL 下，輸入網頁的 URL。例如，http://contoso.com/index.html。
在隱含授與和混合流程區段中，開啟存取權杖 (用於隱含流程) 和識別碼權杖 (用於隱含和混合流程)。
選取設定。

尋找 Agent 的權杖端點 URL

在 Copilot Studio 中，開啟您的 Agent，然後選擇頻道。
選取行動裝置應用程式。
在權杖端點底下，選取複製。

在網頁中設定 SSO

重要

在啟用 SSO 的應用程式中的 SharePoint 和 Graph Connector 資料來源，訪客使用者無法存取 AI 生成式解答。

使用 Copilot Studio 樣本 GitHub 存放庫中提供的程式碼，為重新導向 URL 建立網頁。從 GitHub 存放庫複製程式碼並使用以下指示進行修改。

前往 Azure 入口網站中的概觀頁面，並複製畫布應用程式註冊中的應用程式 (用戶端) 識別碼和目錄 (租用戶) 識別碼。

若要設定 Microsoft 驗證庫 (MSAL)：

指派 clientId 給您的應用程式 (用戶端) 識別碼。
指派 authority 至 https://login.microsoftonline.com/ 並將目錄 (租用戶) 識別碼新增至結尾。

例如:

var clientApplication;
    (function (){
    var msalConfig = {
        auth: {
            clientId: '00001111-aaaa-2222-bbbb-3333cccc4444',
            authority: 'https://login.microsoftonline.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'     
        },

將 theURL 變數設定為先前複製的權杖端點 URL。例如:

(async function main() {

    var theURL = "https://<token endpoint URL>"

編輯 userId 的值以加入自訂首碼。例如:

var userId = clientApplication.account?.accountIdentifier != null ? 
        ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
        : (Math.random().toString() + Date.now().toString()).substr(0,64);

儲存您的變更。
驗證是否已成功設定 SSO。

測試 Agent 時，如果 SSO 未成功設定，系統會提示您登入。登入過程會提供一個驗證碼，您必須將其複製到聊天視窗。

如果您看到登入提示，請確認您正確完成了此程序的第 1 步至第 5 步。如果 SSO 設定成功，系統不會提示您登入。

注意

GitHub 倉庫中的程式碼要求使用者選擇登入按鈕。在生產環境中，您可能會想用更合適的事件取代按鈕功能，比如導覽到頁面。

技術概觀

下圖說明使用者如何在 Copilot Studio 中無需看到登入提示 SSO 提示即可登入：

SSO 驗證流程圖解。

Agent 使用者輸入觸發登入主題的字詞。登入主題的設計目的是為了讓使用者登入，並使用使用者的已驗證權杖 (User.AccessToken 變數)。
Copilot Studio 傳送登入提示，以允許使用者使用其設定的識別提供者登入。
Agent 的自訂畫布會攔截登入提示，並從 Microsoft Entra ID 請求代表 (OBO) 權杖。畫布將權杖發送給 Agent。
收到 OBO 權杖後，Agent 會將 OBO 權杖交換為「存取權杖」，並使用存取權杖的值填入 AuthToken 變數。此時也會設定 IsLoggedIn 變數。

在 Microsoft Entra ID 中為您的自訂畫佈建立應用程式註冊

若要啟用 SSO，您需要兩個不同的應用程式註冊：

一個用於您的 Agent，以使用 Microsoft Entra ID 啟用使用者驗證。
一個用於您的自訂畫布以啟用 SSO。

重要

您不能將相同的應用程式註冊重複用於 Agent 的使用者驗證和自訂畫布。

為 Agent 畫佈建立應用程式註冊

登入 Azure 入口網站。
若要移至應用程式註冊，請選取圖示或在頂端搜尋欄中搜尋。
選取新增註冊。
輸入註冊的名稱。使用所要註冊畫布的 Agent 名稱並包含 “canvas” 一詞，協助將其與用於驗證的應用程式註冊區分。

例如，如果您的 Agent 名為「Contoso sales help」，您可以將應用程式註冊命名為「ContosoSalesCanvas」或類似名稱。
在支援的帳戶類下，選擇任何組織租用戶 (任何 Microsoft Entra ID 目錄 - 多租用戶) 中的帳戶和個人 Microsoft 帳戶 (例如 Skype、Xbox)。
目前將重新導向 URI 區段保留空白，將在後續步驟中輸入該資訊。選取註冊。
註冊完成後，會開啟概觀頁面。移至清單。確認 accessTokenAcceptedVersion 設定為 2。如果不是，請將它變更為 2，然後選取儲存。

新增重新導向 URL

在註冊開放後，前往驗證然後選取新增平臺。
在設定平台面板上，選取 Web。
在重新導向 URI 下，將完整 URL 新增至您的聊天畫布被託管的頁面。在隱含授與區段中，選取 識別碼權杖和存取權杖核取方塊。
選取設定以確認變更。
移至 API 權限。選取代表 <您的用戶名稱> 授與管理員同意然後是。

重要

為了避免使用者必須同意每個應用程式，獲指派應用程式管理員或雲端應用程式管理員角色的人員可以向您的應用程式註冊授予全租用戶範圍的同意。

定義 Agent 的自訂範圍

透過為驗證應用程式註冊中的畫布應用程式註冊公開 API，以定義自訂範圍。範圍可讓您確定使用者和管理員角色及存取權限。

此步驟會在驗證應用程式註冊和自訂畫布的應用程式註冊之間建立信任關係。

開啟您在設定驗證時所建立的應用程式註冊。
前往 API 權限並確保為您的 Agent 新增正確的權限。選取代表 <您的用戶名稱> 授與管理員同意然後是。

重要

為了避免使用者必須同意每個應用程式，獲指派應用程式管理員或雲端應用程式管理員角色的人員可以向您的應用程式註冊授予全租用戶範圍的同意。
移至公開 API 並選取新增範圍。
輸入範圍的名稱，以及在使用者進入 SSO 畫面時，會看到的資訊。選取新增範圍。
選取新增用戶端應用程式。
從畫布應用程式註冊的概觀頁面，將應用程式 (用戶端) 識別碼輸入至用戶端識別碼欄位。選取您所建立已列出範圍的核取方塊。
選取新增應用程式。

在 Copilot Studio 中設定驗證以啟用 SSO

使用 Copilot Studio 驗證設定頁面中的權杖交換 URL來透過 Bot Framework，將 OBO 權杖交換為要求的存取權杖。

Copilot Studio 呼叫 Microsoft Entra ID 來執行實際交換。

登入 Copilot Studio。
透過在頂部選單選取 Agent 圖示，並選擇正確的 Agent，確認您已選擇要啟用驗證的 Agent。
在導覽功能表的設定底下，選取安全性。接著選取驗證卡片。
在權杖交換 URL 欄位中，輸入來自 Agent 驗證應用程式註冊公開 API 頁面的完整範圍 URI。 URI 的格式為 api://1234-4567/scope.name。
選擇儲存，然後發佈 Agent 內容。

設定您的自訂畫布 HTML 代碼以啟用 SSO

更新 Agent 所在的自訂畫布頁面，以攔截登入卡片請求並交換 OBO 令牌。

將下列程式碼新增至 <head> 區段的 <script> 標記中，即可設定 Microsoft 驗證程式庫 (MSAL)。

使用畫布應用程式註冊的應用程式 (用戶端) 識別碼更新 clientId。將 <Directory ID> 取代為目錄 (租用戶) 識別碼。從畫布應用程式註冊概觀頁面取得這些識別碼 (ID)。

<head>
 <script>
   var clientApplication;
     (function () {
       var msalConfig = {
           auth: {
             clientId: '<Client ID [CanvasClientId]>',
             authority: 'https://login.microsoftonline.com/<Directory ID>'
           },
           cache: {
             cacheLocation: 'localStorage',
             storeAuthStateInCookie: false
           }
       };
       if (!clientApplication) {
         clientApplication = new Msal.UserAgentApplication(msalConfig);
       }
     } ());
 </script>
</head>

在 <body> 區段中插入下列 <script>。此指令碼會呼叫方法，擷取 resourceUrl 並將您目前的權杖交換為 OAuth 提示要求的權杖。

<script>
function getOAuthCardResourceUri(activity) {
  if (activity &&
       activity.attachments &&
       activity.attachments[0] &&
       activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
       activity.attachments[0].content.tokenExchangeResource) {
         // asking for token exchange with Microsoft Entra ID
         return activity.attachments[0].content.tokenExchangeResource.uri;
   }
}

function exchangeTokenAsync(resourceUri) {
  let user = clientApplication.getAccount();
   if (user) {
     let requestObj = {
       scopes: [resourceUri]
     };
     return clientApplication.acquireTokenSilent(requestObj)
       .then(function (tokenResponse) {
         return tokenResponse.accessToken;
         })
         .catch(function (error) {
           console.log(error);
         });
         }
         else {
         return Promise.resolve(null);
   }
}
</script>

在 <body> 區段中插入下列 <script>。在 main 方法中，此程式碼使用 Agent 的唯一識別碼為您的 store 新增條件。它也會產生唯一的識別碼做為您的 userId 變數。

使用您的 Agent 識別碼更新 <BOT ID>。要在 Copilot Studio 查看您的 Agent ID，請前往您的 Agent 頻道頁面，選擇行動應用程式。

<script>
    (async function main() {

        // Add your BOT ID below 
        var BOT_ID = "<BOT ID>";
        var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

        const {
            token
        } = await fetchJSON(theURL);

        var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 

        const directLine = window.WebChat.createDirectLine({
            domain: `${directline}v3/directline`,
            token
        });

        var userID = clientApplication.account?.accountIdentifier != null ?
            ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
            (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
        const store = WebChat.createStore({}, ({
            dispatch
        }) => next => action => {
            const {
                type
            } = action;
            if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                dispatch({
                    type: 'WEB_CHAT/SEND_EVENT',
                    payload: {
                        name: 'startConversation',
                        type: 'event',
                        value: {
                            text: "hello"
                        }
                    }
                });
                return next(action);
            }
            if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                const activity = action.payload.activity;
                let resourceUri;
                if (activity.from && activity.from.role === 'bot' &&
                    (resourceUri = getOAuthCardResourceUri(activity))) {
                    exchangeTokenAsync(resourceUri).then(function(token) {
                        if (token) {
                            directLine.postActivity({
                                type: 'invoke',
                                name: 'signin/tokenExchange',
                                value: {
                                    id: activity.attachments[0].content.tokenExchangeResource.id,
                                    connectionName: activity.attachments[0].content.connectionName,
                                    token,
                                },
                                "from": {
                                    id: userID,
                                    name: clientApplication.account.name,
                                    role: "user"
                                }
                            }).subscribe(
                                id => {
                                    if (id === 'retry') {
                                        // The agent was not able to handle the invoke, so display the oauthCard
                                        return next(action);
                                    }
                                    // else: tokenexchange successful and we do not display the oauthCard
                                },
                                error => {
                                    // an error occurred to display the oauthCard
                                    return next(action);
                                }
                            );
                            return;
                        } else
                            return next(action);
                    });
                } else
                    return next(action);
            } else
                return next(action);
        });

        const styleOptions = {

            // Add styleOptions to customize Web Chat canvas
            hideUploadButton: true
        };

        window.WebChat.renderWebChat({
                directLine: directLine,
                store,
                userID: userID,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })().catch(err => console.error("An error occurred: " + err));
</script>

完整範例程式碼

您可以在 Copilot Studio 範例 GitHub 存放庫中找到包含 MSAL 的完整範例程式碼，並儲存條件式指令碼。

Azure 應用程式註冊

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-07-30