使用 Microsoft Entra ID 設定單一登入

發行項
04/22/2024

重要

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

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

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

先決條件

注意

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

例如，副手是託管在公司內部網站或在使用者已經登入的應用程式中。

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

在 Microsoft Entra ID 中建立自訂畫布的應用程式註冊。
為您的副手定義自訂範圍。
在 Copilot Studio 中設定驗證以啟用 SSO。
設定您的自訂畫布 HTML 代碼以啟用 SSO。

支援的管道

下表詳細描述目前支援 SSO 的管道。您可以在 Microsoft Copilot Studio 構想論壇中，建議支援其他管道。

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

¹ 如果您也已啟用團隊管到，則需要遵循為 Teams 管道設定 SSO 文件的設定指示。如果無法根據該頁面上的指示設定 Teams SSO 設定，會導致您的使用者在使用 Teams 管道時一直無法通過驗證。

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

重要

當副手處於以下任一狀態時，目前不支援 SSO：

發佈到 Power Apps 入口網站。
以 iframe 形式發佈到 SharePoint 網站。

但是，已作為 SPFx 元件發佈到 SharePoint 網站的副手支援 SSO。

Web 應用程式
傳統

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

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

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

出於安全原因，不建議您的副手和自訂網站重複使用相同的應用程式註冊。

依照使用 Microsoft Entra ID設定使用者驗證中的說明建立驗證應用程式註冊。
再次按照相同的說明建立第二個應用程式註冊，做為畫布應用程式註冊。

設定畫布應用程式註冊

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

尋找副手的權杖端點 URL

在 Copilot Studio 中，移至設定，然後選取管道。
選取行動裝置應用程式。
在權杖端點底下，選取複製。

在網頁中設定 SSO

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

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

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

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

例如:

var clientApplication;
    (function (){
    var msalConfig = {
        auth: {
            clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
            authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
        },

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

(async function main() {

    var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"

編輯 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);

儲存您的變更。

使用您的網頁測試副手

在瀏覽器中打開網頁。
選取登入。

注意

如果您的瀏覽器封鎖快顯視窗，或者您使用的是無痕瀏覽或私密瀏覽視窗，系統會提示您登入。否則，將使用驗證碼完成登入。

新的瀏覽器索引標籤會開啟。
切換至新的索引標籤，並複製驗證代碼。
切換回副手索引標籤，然後將驗證碼貼到副手對話中。

Azure App 註冊

技術概觀

下列圖解顯示使用者如何登入，而不會在 Copilot Studio 中看到登入提示 (SSO)：

SSO 驗證流程圖解。

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

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

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

一種供您的副手使用 Microsoft Entra ID 啟用使用者驗證的工具。
一個用於您的自訂畫布以啟用 SSO。

重要

您無法為副手的使用者驗證和自訂畫布重複使用相同的應用程式註冊。

為副手畫布建立應用程式註冊

登入 Azure 入口網站。
若要移至應用程式註冊，請選取圖示或在頂端搜尋欄中搜尋。
選取新增註冊。
輸入註冊的名稱。使用要註冊之畫布的副手名稱，並加入「canvas」以協助將它與應用程式註冊相分離以進行驗證，這會非常實用。

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

新增重新導向 URL

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

重要

若要避免使用者同意每個應用程式，全域系統管理員、應用程式系統管理員或雲端應用程式管理員必須將用戶範圍的同意授與您的應用程式註冊。

為您的副手定義自訂範圍

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

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

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

重要

若要避免使用者同意每個應用程式，全域系統管理員、應用程式系統管理員或雲端應用程式管理員必須將用戶範圍的同意授與您的應用程式註冊。
移至公開 API 並選取新增範圍。
輸入範圍的名稱，以及在使用者進入 SSO 畫面時，應該向使用者顯示的資訊。選取新增範圍。
選取新增用戶端應用程式。
從畫布應用程式註冊的概觀頁面，將應用程式 (用戶端) 識別碼輸入至用戶端識別碼欄位。選取所建立之列出範圍的核取方塊。
選取新增應用程式。

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

Copilot Studio 驗證設定頁面中的權杖交換 URL 用於透過機器人框架，交換 OBO 權杖和要求的存取權杖。

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

登入 Copilot Studio。
確認您已透過選取頂端功能表上的副手圖示，然後選擇正確的副手，來選取要啟用驗證的副手。
在導覽功能表的設定底下，選取安全性。接著選取驗證卡片。
在代用文字交換 URL欄位中，從副手驗證應用程式註冊的接觸 API 刀鋒視窗中輸入完整範圍的 URI。 URI 的格式為 api://1234-4567/scope.name。
選取儲存然後發佈副手內容。

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

更新副手所在的自訂畫布頁面，以攔截登入卡片要求，並交換 OBO 權杖。

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

使用畫布應用程式註冊的應用程式 (用戶端) 識別碼更新 clientId。將 <Directory 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 方法中，此代碼會新增帶有副手唯一識別碼的條件式到您的 store。它也會產生唯一的識別碼做為您的 userId 變數。

使用您的副手識別碼更新 <COPILOT ID>。您可以前往所使用副手的管道索引標籤，然後在 Copilot Studio 入口網站上選取行動裝置應用程式，以查看您的副手識別碼。

在行動裝置應用程式頻道設定頁面上顯示的副手識別碼。

<script>
    (async function main() {

        // Add your COPILOT 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') {
                                        // copilot 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>

完整範例程式碼

如需更多資訊，您可以在我們的 GitHub 存放庫找到完整的範例程式碼，以及 MSAL 及儲存條件指令碼。

共用方式為

使用 Microsoft Entra ID 設定單一登入

先決條件

支援的管道

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

設定畫布應用程式註冊

尋找副手的權杖端點 URL

在網頁中設定 SSO

使用您的網頁測試副手

技術概觀

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

為副手畫布建立應用程式註冊

新增重新導向 URL

為您的副手定義自訂範圍

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

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

完整範例程式碼

意見反應

意見反應

其他資源

共用方式為

使用 Microsoft Entra ID 設定單一登入

先決條件

支援的管道

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

設定畫布應用程式註冊

尋找副手的權杖端點 URL

在網頁中設定 SSO

使用您的網頁測試副手

相關內容

意見反應

意見反應

其他資源