使用通用 OAuth 提供者設定單一登入

發行項
12/09/2024

Copilot Studio 支援使用 OAuth 2.0 相容驗證提供者進行單一登入 (SSO)。 SSO 允許您網站上的代理在客戶登錄到部署了專員的頁面或應用程式時登錄客戶。

必要條件

建立或使用支援通用 OAuth 提供者 SSO 流程的自訂畫布

當身份驗證主題在與通用 OAuth 2.0 提供者連接的代理中觸發時， Copilot Studio 會發送一條包含安全 URL 的消息，該 URL 用於發佈使用者的存取權杖。

自訂畫布或嵌入畫布的頁面應實作以下模式：

使用您的慣用方法從 OAuth 2.0 驗證提供者取得已登入使用者的存取權杖。
攔截來自 Copilot Studio的傳入訊息，並提取安全 URL。
將存取權杖發佈到安全 URL。

提取安全 URL 並行佈權杖

自訂畫布使用中介軟體概念攔截傳入訊息，中介軟體概念是在從 Copilot Studio 接收訊息的上下文中執行的程式碼。

若要回應登入要求，自訂畫布需要攔截帶有具有內容類型 application/vnd.microsoft.card.oauth 附件的訊息。 OAuthCard 附件包含 content.tokenPostResource.sasUrl 屬性，可以從中提取安全 URL。最後，自訂畫布應將使用者存取權杖發佈到安全 URL。

以下 JavaScript 程式碼是提取安全 URL 並行布權杖的中介軟體程式碼範例。如果發佈成功，則中介軟體會傳回 false。如果發佈不成功，或者活動沒有 application/vnd.microsoft.card.oauth 屬性，則將傳回 next(…args)。

const activityMiddleware = () => next => (...args) => {
  if (args[0].activity.attachments?.[0]?.contentType === 'application/vnd.microsoft.card.oauth') {
    var postEndpoint = args[0].activity.attachments?.[0].content.tokenPostResource.sasUrl;

    // Perform an HTTP POST to the secure URL with the body of:
    // {
    //     "token": <user_token> 
    // } 

    if(success)
       return false;
    else
       return next(...args);
  } else {
    return next(...args);
  }
};

完整範例程式碼

根據您的驗證提供者，為登入使用者取得權杖並將權杖發佈到 Copilot Studio 的自訂畫布或應用程式的實作會有所差異。有關詳細資訊，請參閱驗證提供者的文件，深入了解登入流程和如何取得存取權杖。有關使用 OKTA 的參考範例，請參閱使用 OKTA 的協力廠商 SSO。

在 Copilot Studio 中使用權杖

使用安全 URL 發佈的權杖將填入Copilot Studio 中的 System.User.AccessToken 變數中。專員製作者可以使用此系統變數來訪問連接到生成令牌的經過身份驗證的供應商的受保護 API。

在下列範例中，HTTP 呼叫設定了使用 System.User.AccessToken 的授權標頭。

顯示存取安全 APU 的 HTTP 呼叫的螢幕擷取畫面。

支援的管道

具有通用 OAuth 驗證提供者的 SSO 是一種自訂模式，可透過自訂畫布或使用 Directline API 的任何其他用戶端執行。

共用方式為