アダプティブ カード テンプレートにダイアログ ボックスを追加する (プレビュー)

モーダル ダイアログ ボックスを追加することで、Microsoft 365 Copilot の宣言型エージェントでアダプティブ カード応答を強化できます。 これらのポップアップ ダイアログ ボックスでは、カスタム HTML/JavaScript をホストしたり、Web ページ、YouTube ビデオ、Microsoft Stream コンテンツなどの iframe ベースのウィジェットを、焦点を絞った対話型エクスペリエンス内で表示したりできます。

この記事では、 Action.OpenUrlDialog (アダプティブ カード スキーマ バージョン 1.5 で利用可能) を使用して、アダプティブ カード テンプレートからモーダル ダイアログ ボックスを起動する方法と、ユーザー認証を構成する方法について説明します。

注

OpenUrlDialog アクションは現在プレビュー段階です。

前提条件

Action.OpenUrlDialogを使用するには、次の前提条件が必要です。

  • アダプティブ カード スキーマ バージョン 1.5
  • API プラグイン マニフェスト バージョン 2.3
  • Microsoft TeamsJS ライブラリ (認証シナリオ用)

アダプティブ カード テンプレートを定義する

モーダル ダイアログ ボックスのアクションを使用するには:

次の例は、 Action.OpenUrlDialog のスキーマを示しています。

"actions": [
     {
         "type": "Action.OpenUrlDialog",
         "title": "OpenDialogWithDimension",
         "url": "${url}",
         "dialogHeight": "large",
         "dialogWidth": "600px",
         "dialogTitle": "task module"
     }
    ]

スキーマ参照情報については、 Action.OpenUrlDialog を参照してください。

[構成] ダイアログ ボックスのサイズ

dialogHeight プロパティと dialogWidth プロパティを使用して、ダイアログ ボックスの高さと幅を設定します。 これらの値は、ユーザーの画面解像度とウィンドウのサイズに基づいて動的に調整されます。

以下を指定できます。

  • 事前定義サイズ - small、 medium、 large。
  • カスタム ピクセル値 - 例: 400px、 600px。

ヒント

ピクセル値を使用して正確に制御します。 定義済みのサイズは、使用可能な画面スペースを基準にしています。

次の画像は、エージェントによって返されるアダプティブ カード ボタンから呼び出されるダイアログ ボックスの例を示しています。

ユーザーが顧客情報を入力するダイアログ ボックスの画像

認証の構成

ダイアログ ボックス内から API へのセキュリティで保護されたアクセスを許可するには、次のいずれかの方法を使用して認証を構成します。

  • Microsoft Entra ID
  • OAuth 2.0 (プレビュー)

Microsoft Entra ID のセットアップ

API 認証に Entra ID 認証を使用するには、次のいずれかの方法を使用します。

  • Microsoft を ID プロバイダーとして使用して、Entra ID、OAuth 2.0、または API キーベースの認証を構成します。
  • 別の ID プロバイダーを使用して、アプリを Entra ID に登録します。

SSO ベースの認証を構成する

シングル サインオン (SSO) を構成して、ユーザーが複数回サインインしなくても API にアクセスできるようにします。

SSO を有効にするには:

  1. Microsoft Entra ID アプリケーションを更新します。
    • アプリケーション ID URI を構成します。
    • スコープと同意の設定を構成します。
    • 信頼されたクライアント アプリケーションを事前承認して、同意を求めるメッセージが繰り返し表示されないようにします。
  2. トークンの取得と検証ロジックを実装します。
    • TeamsJS ライブラリから getAuthToken() メソッドを使用して、アクセス トークンを取得します。
    • Authorization ヘッダーでサーバーにトークンを送信します。
    • サーバー側でトークンを検証します。
  3. アプリ マニフェストを更新します。
    • webApplicationInfo プロパティをアプリ マニフェストに追加して SSO を有効にします。
    • ダイアログ ボックスのコンテンツのドメインを、アプリ マニフェストの 'validDomains プロパティに追加します。

Microsoft Entra ID アプリケーションを更新する

スコープを構成し、信頼されたクライアント アプリケーションを承認するには、次のように Microsoft Entra ID アプリケーションを更新します。

  1. アプリ マニフェストの identifierUris プロパティに API URI を追加します。 次の例に示すように、URI には 'api://fully-qualified-domain-name.com/{AppID} の形式を使用します。

    "identifierUris": [
    "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db",
    "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db"
    ],
    
  2. API のスコープと、スコープに同意できるユーザーを定義します。 Microsoft Entra 管理センターの [この API で定義されているスコープ] セクションで、[+ スコープの追加] を選択します。

    スコープを追加するフィールドのスクリーンショット

    1. スコープ名を入力します。 このフィールドは必須です。
    2. このスコープに同意できるユーザーを選択します。 既定のオプションは [管理者のみ] です。
    3. 管理同意の表示名を入力します。 このフィールドは必須です。
    4. 管理者の同意の説明を入力します。 このフィールドは必須です。
    5. [ユーザーの同意] の表示名を入力します。
    6. ユーザー同意の説明を入力します。
    7. [ 状態 ] フィールドで、状態の [有効 ] オプションを選択します。
    8. [ スコープの追加] を選択します。
  3. 事前承認するアプリケーションの承認済みクライアント ID を作成します。 これにより、アプリ ユーザーは、追加の同意を必要とせずに、構成したアプリ スコープ (アクセス許可) にアクセスできます。 アプリ ユーザーには同意を拒否する機会がないため、信頼できるクライアント アプリケーションのみを事前承認します。

    1. Microsoft Entra 管理センターの [承認されたクライアント アプリケーション] セクションで、[+ クライアント アプリケーションの追加] を選択します。

      [クライアント アプリケーションの追加] ボタンが強調表示されたスクリーンショット

    2. 承認するアプリケーションの Microsoft 365 クライアント ID を入力します。

トークンの取得と検証ロジックを実装する

アクセス トークンを処理するコードを追加し、Authorization ヘッダーでアプリのサーバー コードにトークンを送信し、アクセス トークンを受信したら検証します。

現在のアプリ ユーザーのアプリ アクセスを取得するには、クライアント側コードで Teams を呼び出してアクセス トークンを取得する必要があります。 次の例に示すように、 getAuthToken() を使用して検証プロセスを開始するようにクライアント側のコードを更新します。

// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
     return new Promise((resolve, reject) => {
         display("1. Get auth token from Microsoft Teams");

         microsoftTeams.authentication.getAuthToken().then((result) => {
             display(result);
             resolve(result);
         }).catch((error) => {
             reject("Error getting token: " + error);
         });
     });
 }

Teams は、アクセス トークンを受け取ると、必要に応じて再利用されるトークンをキャッシュします。 トークンの有効期限が切れるまで、getAuthToken() が呼び出されたときに使用されます。トークンの有効期限が切れるまで、Microsoft Entra ID を再度呼び出す必要はありません。

getAuthToken() を呼び出し、ユーザー レベルのアクセス許可にユーザーの同意が必要な場合、サインインしたユーザーにはMicrosoft Entraダイアログ ボックスが表示され、ユーザーは最初の同意を 1 回提供する必要があります。

ユーザーが同意すると、ダイアログ ボックスの Web ページにアクセスできるようになります。 ユーザーの同意には、次の点が当てはまります。

  • 管理者がテナントに代わって同意を付与した場合、アプリ ユーザーに同意を求めるプロンプトを表示する必要はありません。 つまり、アプリ ユーザーには同意ダイアログ ボックスが表示されず、シームレスにアプリにアクセスできます。
  • Microsoft Entra アプリが Teams で認証を要求しているのと同じテナントに登録されている場合、アプリ ユーザーに同意を求めることはできず、すぐにアクセス トークンが付与されます。 アプリ ユーザーは、Microsoft Entra アプリが別のテナントに登録されている場合にのみ、これらのアクセス許可に同意します。
  • ユーザーは API アクセスに同意する必要があり、同意はユーザーごとに 1 回だけ必要とされるため、ダイアログ ボックスに追加の同意は必要ありません。

アプリ マニフェストの更新

SSO を有効にするには、アプリ マニフェスト ファイルで webApplicationInfo プロパティを構成します。 これにより、エージェント ユーザーはエージェントにシームレスにアクセスできます。 次の表に、 webApplicationInfo プロパティのプロパティを示します。

プロパティ 説明
id Microsoft Entra ID で作成したアプリ ID (GUID) を入力します。
リソース アプリのサブドメイン URI と、スコープの作成時に Microsoft Entra ID で作成したアプリケーション ID URI を入力します。
"webApplicationInfo": {
  "id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
  "resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
 }

次の例に示すように、アプリ マニフェストの validDomains プロパティのダイアログ ボックスで、表示する URL のドメインを指定します。

"validDomains": [
     "contoso.com",
     "mysite.someplace.com",
     "othersite.someplace.com"
 ]

OAuth 2.0 セットアップ (プレビュー)

Microsoft Entra ID またはその他の ID プロバイダーで OAuth 2.0 を使用するエージェントの場合は、TeamsJS ライブラリの authentication.authenticate() 関数を使用して認証フローを開始します。

API プラグイン ダイアログ ボックスの OAuth 2.0 承認を有効にするには:

  • Microsoft Entra ID を ID プロバイダーとして使用するようにアプリを構成します。
  • コードを変更して認証フローを開始し、トークンを処理します。

Microsoft Entra ID を ID プロバイダーとして使用するようにアプリを構成する

Microsoft Entra ID を使用するようにアプリを構成するには:

  • Azure portal で、アプリの登録に移動します。
  • [ 認証] の [ リダイレクト URI ] セクションで、リダイレクト URL を認証エンドポイントに追加します。 リダイレクト URL には次の形式を使用します: https://<hostname>/auth/simple-start。

認証フローを開始し、トークンを処理する

ほとんどの ID プロバイダーは、コンテンツを iframe に配置することを許可していません。 これは、Copilot がポップアップ ウィンドウ内に表示される ID プロバイダーをホストするページが必要であることを意味します。 アダプティブ カード ボタンが選択されているときにこのページを開くには、TeamsJS ライブラリの authentication.authenticate() 関数を使用します。

注

authenticate()に渡す URL は、認証フローのスタート ページです。 Azure portal に登録した内容と一致する必要があります。 認証フローは、ドメイン内のページから開始する必要があります。 このドメインは必ずマニフェストの validDomains プロパティに記載してください。

import { authentication } from "@microsoft/teams-js";

authentication.authenticate({
     url: window.location.origin + "/auth/simple-start",
     width: 600,
     height: 535
 })
.then((result) => {
     console.log("Login succeeded: " + result);
     let data = localStorage.getItem(result);
     localStorage.removeItem(result);
     let tokenResult = JSON.parse(data);
     showIdTokenAndClaims(tokenResult.idToken);
     getUserProfile(tokenResult.accessToken);
 })
.catch((reason) => {
     console.log("Login failed: " + reason);
     handleAuthError(reason);
 });

ポップアップ ページが ID プロバイダーにリダイレクトされるので、ユーザーはサインインできます。 エージェントは Microsoft Entra 承認サービスを呼び出し、ユーザーが Entra ID で認証できるようにユーザーとアプリの情報を渡します。 Entra ID は、指定したコールバック ページを呼び出します。

app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
     let state = _guid(); // _guid() is a helper function in the sample
     localStorage.setItem("simple.state", state);
     localStorage.removeItem("simple.error");

     // Go to the Azure AD authorization endpoint
     let queryParams = {
         client_id: "{{appId}}",
         response_type: "id_token token",
         response_mode: "fragment",
         scope: "https://graph.microsoft.com/User.Read openid",
         redirect_uri: window.location.origin + "/auth/simple-end",
         nonce: _guid(),
         state: state,
         // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
         login_hint: context.user.loginHint,
     };

     let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
     window.location.assign(authorizeEndpoint);
 });

Entra ID によって返された情報に基づいて認証要求の成否を判断し、authentication.notifySuccess() または authentication.notifyFailure() を呼び出します。 サインインが成功した場合、ユーザーはサービス リソースにアクセスできます。