Microsoft Entra ID を使用してシングル サインオンを構成する

カスタム Web サイト用のアプリ登録を作成する

SSO を有効にするには、2 つの別々のアプリ登録を作成してください:

• 認証アプリの登録でじゃ、 エージェントの Microsoft Entra ID ユーザー認証を有効にします
• カスタム Web ページの SSO を有効にするキャンバス アプリの登録

セキュリティ上の理由から、エージェントとカスタム Web サイトの両方で同じアプリ登録を再利用しないでください。

1. 認証アプリの登録を作成するには、Microsoft Entra ID を使用したユーザー認証の構成の手順に従ってください。

2. キャンバス アプリの登録で、2 つ目のアプリ登録を作成します。

トークンの交換 URL の追加

Copilot Studio で Microsoft Entra ID 認証設定を更新するには、トークン交換 URL を追加してアプリと Copilot Studio が情報を共有してください。

1. 認証アプリの登録ページにある Azure ポータルで、API の公開に移動します。

2. スコープの下で、クリップボードにコピー アイコンを選択します。

3. Copilot Studio の設定メニューから、セキュリティを選択し、認証タイルを選択します。

4. トークンの交換 URL (SSO に必要)に、先ほどコピーしたスコープを貼り付けます。

5. 保存を選択します。

キャンバス アプリ クライアント ID を構成して API メニューを公開する

1. 認証アプリの登録ページにある Azure portalで、概要に移動します。

2. Essentials配下のアプリケーション (クライアント) ID の値をコピーします。

3. ナビゲーション バーで管理>API の公開を選択します。

4. 承認済みクライアント アプリケーションでクライアント アプリケーションの追加を選択し、コピーしたクライアント ID を貼り付けます。

5. 保存を選択します。

キャンバス アプリの登録を構成する

1. キャンバス アプリの登録を作成した後は、認証にアクセスし、プラットフォームの追加を選択します。

2. プラットフォームの構成 で プラットフォームの追加、次に SPA を選択します。

3. リダイレクト URI 配下で、Web ページの URL を入力します。 たとえば、http://contoso.com/index.html などとします。

   

4. 暗黙的な許可とハイブリッド フロー セクションで、アクセス トークン (暗黙的なフローに使用) と ID トークン (暗黙的およびハイブリッド フローに使用) の両方をオンにします。

5. 構成を選択します。

エージェントのトークン エンドポイント URL を見つける

1. Copilot Studio でご利用のエージェントを開き、チャネルを選択します。

2. モバイル アプリを選択します。

3. トークン エンドポイントの下で、コピーを選択します。

   

Web ページで SSO を構成する

Copilot Studio サンプル GitHub リポジトリ で提供されているコードを使用して、リダイレクト URL の Web ページを作成します。 GitHub リポジトリからコードをコピーし、次の手順に従ってそれを変更してください。

1. Azure ポータルの概要ページに移動し、キャンバス アプリ登録からアプリケーション (クライアント) ID とディレクトリ (テナント) ID をコピーします。

   

2. Microsoft Authentication Library (MSAL) を構成する方法:

   • clientId を アプリケーション (クライアント) ID に割り当てます。
   • authority を https://login.microsoftonline.com/ に割り当て、最後に ディレクトリ (テナント) ID を追加します。

   例:

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

3. theURL 変数を、すでにコピーしたトークン エンドポイント URL に設定します。 例:

   (async function main() {
   
       var theURL = "https://<token endpoint URL>"
   

4. 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);
   

5. 変更を保存。

6. SSO が正常に構成されたことを確認します。

   エージェントのテスト時に、SSO が正常に構成されていない場合は、サインインを求められます。 ログイン手続きが完了すると、認証コードが発行されますので、それをチャット ウィンドウにコピーしてください。

   サインイン プロンプトが表示されたら、この手順のステップ 1 から 5 を正しく完了したか確認します。 SSO が正常に構成されている場合、サインインのプロンプトは表示されません。

   紙幣

   GitHub リポジトリのコードでは、ユーザーがサインイン ボタンを選択する必要があります。 運用環境では、ボタンの機能をページへの遷移など、より適切なイベントに置き換えることを検討してください。

技術的概要

次の図は、ユーザーが Copilot Studio: でログイン プロンプト (SSO) を表示せずにサインインする方法を示します:

1. エージェント ユーザーは、サインイン トピックをトリガーする フレーズを入力します。 サインイン トピックは、ユーザーをサインインしてユーザーの認証されたトークン (User.AccessToken 変数) を使用するように設計されています。

2. Copilot Studio はサインイン プロンプトを送信して、ユーザーが構成された ID プロバイダーでサインインできるようにします。

3. エージェントのカスタム キャンバス はサインイン プロンプトを傍受し、代理 (OBO) トークンを Microsoft Entra ID から要求します。 キャンバスはトークンをエージェントに送信します。

4. OBO トークンの受信時に、エージェントは OBO トークンを「アクセス トークン」に交換し、アクセス トークンの値を使用して AuthToken 変数を入力します。 IsLoggedIn 変数はこの時点でも設定されます。

Microsoft Entra ID でカスタム キャンバスにアプリ登録を作成する

SSO を有効にするには、2 つの個別のアプリ登録が必要です:

• Microsoft Entra ID によるユーザー認証を有効化するためのエージェント用設定。
• 他の 1 つは カスタム キャンバスが SSO を有効にするためです。

エージェントのキャンバス用アプリ登録を作成する

1. Azure ポータルにサインインします。

2. アプリ登録 に移動して、アイコンを選択するか、上部の検索バーで検索します。

   

3. 新規登録を選択します。

   

4. 登録の名前を入力してください。 登録するキャンバスのエージェント名を使用し、認証用のアプリ登録と区別しやすくするため、「canvas」を含めてください。

   たとえば、エージェントが "Contoso 営業ヘルプ" と呼ばれている場合、アプリ登録に "ContosoSalesCanvas" などの名前を付ける場合があります。

5. サポート対象のアカウントの種類で、組織テナント内のアカウント (任意の Microsoft Entra ID ディレクトリ - マルチテナント) および個人用 Microsoft アカウント (Skype、Xbox など) を選択します。

6. 次のステップでその情報を入力するので、今回は リダイレクト URI セクションを空白のままにします。 登録 を選択します。

   

7. 登録が完了した後、概要 ページが開きます。 マニフェストにアクセスします。 accessTokenAcceptedVersion が 2 に設定されていることを確認します。 そうでない場合は、2 に変更し、保存を選択します。

リダイレクト URL の追加

1. 登録を開いた状態で、認証にアクセスし、プラットフォームの追加を選択します。

   

2. プラットフォームの構成パネルで、Web を選択します。

   

3. リダイレクト URI で、チャット キャンバスがホストされているページに完全な URL を追加します。 暗示的な許可セクションで、ID トークンおよびアクセス トークン チェックボックスを選択します。

4. 構成を選択して変更を確認します。

   

5. API アクセス許可に移動します。 <テナント名>に管理者の承認を付与するを選択してから、はいを選択します。

   重要

   ユーザーが各アプリケーションに対して同意する必要をなくすために、少なくともアプリケーション管理者またはクラウド アプリケーション管理者の役割を割り当てられた担当者は、アプリケーション登録に対してテナント全体にわたる同意を与えることができます。

   

エージェントのカスタム スコープを定義する

認証アプリ登録内でキャンバス アプリ登録用の API を公開することにより、カスタム スコープを定義します。 スコープ により、ユーザーと管理者の役割およびアクセス権を決定できます。

この手順では、認証用の認証アプリ登録とカスタム キャンバス用のアプリ登録の間に信頼関係が作成されます。

1. 認証を構成したとき に作成したアプリ登録を開きます。

2. API アクセス許可に移動し、エージェントに適切なアクセス許可が追加されていることを確認してください。 <テナント名>に管理者の承認を付与するを選択してから、はいを選択します。

   重要

   ユーザーが各アプリケーションに対して同意する必要をなくすために、少なくともアプリケーション管理者またはクラウド アプリケーション管理者の役割を割り当てられた担当者は、アプリケーション登録に対してテナント全体にわたる同意を与えることができます。

3. API を公開するに移動してからスコープの追加を選択します。

   

4. スコープの名前と、ユーザーが SSO 画面にアクセスしたときに表示される表示情報を入力します。 [スコープの追加] を選択します。

   

5. クライアント アプリケーションの追加を選択します。

6. アプリケーション (クライアント) ID を、キャンバス アプリ登録の概要ページからクライアント ID フィールドに入力します。 作成した一覧表示スコープのチェックボックスを選択します。

7. [アプリケーションの追加]をクリックします。

Copilot Studio でユーザー認証を構成して SSO を有効化する

Copilot Studio の認証設定ページの トークン交換 URL を使用して、Bot Framework を通じて要求されたアクセス トークンに対する OBO トークンを交換します。

Copilot Studio は Microsoft Entra ID を呼び出して実際の交換を実行します。

1. Copilot Studio にサインインします。

2. 認証を有効化するエージェントを選択したことを確認するには、上部メニューのエージェントアイコンを選択し、正しいエージェントを選択します。

3. ナビゲーション メニューの 設定 で セキュリティ を選択します。 次に、認証 カードを選択します。

   

4. トークンの交換 URL フィールドにあるエージェントの認証アプリ登録について、API の公開ページから完全スコープ URI を入力します。 URI の形式は api://1234-4567/scope.name です。

   

   

5. 保存を選択してからエージェント コンテンツを公開します。

SSO を有効にするように、カスタム キャンバス HTML コードを構成する

エージェントが配置されているカスタム キャンバス ページを更新して、サインイン カードのリクエストを受信し、OBO トークンを交換します。

1. 次のコードを <head> セクションの <script> タグに追加して、Microsoft 認証ライブラリ (MSAL) を構成します。

2. アプリケーション (クライアント) ID キャンバス アプリ登録用を使用して clientId を更新します。 <Directory ID> をディレクトリ (テナント) 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>
   

3. 次の <script> を <body> セクションに挿入します。 このスクリプトはメソッドを呼び出して 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>
   

4. 次の <script> を <body> セクションに挿入します。 main メソッド内で、このコードはエージェントの一意識別子を使用して store に条件を追加します。 また固有の ID を、userId 変数として生成します。

5. エージェントの ID を使用して <BOT ID> を更新します。 Copilot Studio でエージェントの ID を表示するには、エージェントの Channels ページに移動し、Mobile アプリを選択します。

   <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>
   

完全なサンプル コード

MSAL およびストアの条件付きスクリプトがすでに組み込まれた完全なサンプルコードは、Copilot Studio Samples の GitHub リポジトリで確認できます。