汎用 OAuth プロバイダーを使用してシングル サインオンを構成する

Copilot Studio は、OAuth 2.0 互換の認証プロバイダーによるシングル サインオン (SSO) に対応しています。 SSO を使用すると、エージェントが展開されているページまたはアプリにサインインした場合は、web サイト上のエージェントが顧客をサインインさせることができます。

必要条件

汎用 OAuth プロバイダーの SSO フローをサポートするカスタム キャンバスを作成または使用する

汎用 OAuth 2.0 プロバイダーに接続されたエージェントで認証トピックがトリガーされると、Copilot Studio は、ユーザーのアクセス トークンを転記するために使用されるセキュアな URL を含むメッセージを送信します。

カスタム キャンバスまたはキャンバスが埋め込まれているページでは、次のパターンを実装する必要があります:

  1. サインインしたユーザーのアクセストークンを、OAuth 2.0　認証プロバイダから好ましい方法で取得します。

  2. Copilot Studioからの受信メッセージをインターセプトし、セキュアな URL を抽出します。

  3. アクセス トークン をセキュアな 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 にアクセスできます。

次の例では、System.User.AccessToken を使用する Authorization ヘッダーで HTTP 呼び出しが構成されています。

安全な API にアクセスする HTTP 呼び出しを示すスクリーンショット。

サポート対象のチャネル

汎用 OAuth 認証プロバイダーを使用した SSO はカスタムパターンで、カスタム キャンバスまたは Directline API を使用するその他のクライアントで実装できます。

  • Last updated on