Microsoft Entra マニフェストを編集する

Microsoft 365 Agents Toolkit (以前は Teams Toolkit と呼ばれていました) は、Microsoft Teams アプリケーション開発ライフサイクル中に信頼できるソースとしてアプリ マニフェスト ファイルを使用して Microsoft Entra アプリケーションを管理するようになりました。

Microsoft Entra マニフェスト テンプレートをカスタマイズする

Microsoft Entra マニフェスト テンプレートをカスタマイズして、Microsoft Entra アプリケーションを更新できます。

  1. プロジェクトで aad.template.json を開きます。

    テンプレートを示すスクリーンショット。

  2. テンプレートを直接更新するか、 別のファイルの値を参照します。 カスタマイズのシナリオを次に示します。

    アプリケーションのアクセス許可を追加する

    Teams アプリケーションが追加のアクセス許可を持つ API を呼び出すために追加のアクセス許可を必要とする場合は、Microsoft Entra マニフェスト テンプレートrequiredResourceAccessプロパティを更新する必要があります。 このプロパティの例を次に示します。

    "requiredResourceAccess": [
        {
            "resourceAppId": "Microsoft Graph",
            "resourceAccess": [
                {
                    "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                    "type": "Scope" // Scope is for delegated permission
                },
                {
                    "id": "User.Export.All",
                    "type": "Role" // Role is for application permission
                }
            ]
        },
        {
            "resourceAppId": "Office 365 SharePoint Online",
            "resourceAccess": [
                {
                        "id": "AllSites.Read",
                "type": "Scope"
                }
            ]
        }
    ]
    
    

    次の一覧に、さまざまなプロパティ ID とその使用法を示します。

    • resourceAppId プロパティは、さまざまな API に使用されます。 Microsoft Graph および Office 365 SharePoint Online の場合は、UUID の代わりに名前を直接入力し、他の API の場合は UUID を使用します。

    • resourceAccess.id プロパティは、さまざまなアクセス許可に使用されます。 Microsoft Graph と Office 365 SharePoint Online の場合は、UUID の代わりにアクセス許可名を直接入力し、他の API の場合は UUID を使用します。

    • resourceAccess.type プロパティは、委任されたアクセス許可またはアプリケーションのアクセス許可に使用されます。 Scope は、委任されたアクセス許可を意味し、 Role はアプリケーションのアクセス許可を意味します。

    クライアント アプリケーションを事前承認する

    preAuthorizedApplicationsプロパティを使用すると、API がアプリケーションを信頼していることを示すクライアント アプリケーションを承認できます。 クライアントが公開されている API を呼び出すときに、ユーザーは同意しません。 このプロパティの例を次に示します。

    "api": {
       ...
       "preAuthorizedApplications": [
           {
               "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
               "delegatedPermissionIds": [
                   "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
               ]
           }
       ]
       ...
    }
    
    

    preAuthorizedApplications.appId プロパティは、承認するアプリケーションに使用されます。 アプリケーション ID がわからず、アプリケーション名だけがわかっている場合は、次の手順を使用してアプリケーション ID を検索します。

    1. Azure portal に移動し、[アプリケーションの登録] を開きます。

    2. [ すべてのアプリケーション ] を選択し、アプリケーション名を検索します。

    3. アプリケーション名を選択し、概要ページからアプリケーション ID を取得します。

    認証応答のリダイレクト URL を更新する

    リダイレクト URL は、認証に成功した後にトークンなどの認証応答を返すときに使用されます。 リダイレクト URL は、web、spa、publicClient 内のプロパティ redirectUrisを使用してカスタマイズできます。 たとえば、リダイレクト URL として https://www.examples.com/auth-end.html を追加するには、次の例のように追加します。

    "publicClient": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html"
      ]
    },
    "web": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html"
      ],
      "implicitGrantSettings": {}
    },
    "spa": {
      "redirectUris": [
          "https://www.examples.com/auth-end.html",
      ]
    }
    
  3. ローカル環境またはリモート環境の Microsoft Entra アプリケーション変更を更新します。

    1. aad.template.jsonで Preview CodeLens を選択します。

      スクリーンショットはプレビューを示しています。

    2. ローカル環境または開発環境を選択します。

      スクリーンショットは、環境リストを示しています。

    3. aad.local.json または aad.dev.json でDeploy Azure AD Manifest CodeLens を選択します。

      スクリーンショットは、強調表示された展開オプションを示しています。

    4. ローカル環境または開発環境で使用される Microsoft Entra アプリケーションの変更がデプロイされます。

    5. さらに、コマンド パレットを開いて [Teams: Microsoft Entra アプリの更新] を選択して Microsoft Entra アプリを更新することもできます。 スクリーンショットは、[コマンド パレット] オプションを示しています。

Microsoft Entra マニフェスト テンプレート プレースホルダー

Microsoft Entra マニフェスト ファイルには、{{...}} の付いたプレースホルダー引数が含まれています 異なる環境用にビルド中に置き換えられます。 プレースホルダー引数を使用して環境変数を参照できます。

Microsoft Entra マニフェスト テンプレートの参照環境変数

Microsoft Entra マニフェスト テンプレートに永続的な値を入力する必要はありません。また、Microsoft Entra マニフェスト テンプレート ファイルでは参照環境変数値がサポートされます。 ツールの構文 ${{YOUR_ENV_VARIABLE_NAME}} をパラメーター値として使用して、環境変数値を解決できます。

CodeLens を使用して Microsoft Entra マニフェストを編集してプレビューする

Microsoft Entra マニフェスト テンプレート ファイルには、コードを確認および編集するための CodeLens が含まれています。

Microsoft Entra マニフェスト テンプレート ファイル

Microsoft Entra マニフェスト テンプレート ファイルの先頭にプレビューの CodeLens があります。 CodeLens を選択して、環境に基づいて Microsoft Entra マニフェストを生成します。

スクリーンショットは、codelens の追加プレビューを示しています。

プレースホルダー引数 CodeLens

プレースホルダー引数 CodeLens は、ローカル デバッグの値を確認し、環境を開発するのに役立ちます。 プレースホルダー引数の上にマウス ポインターを置くと、すべての環境値のヒント ボックスが表示されます。

スクリーンショットは、引数の追加を示しています。

必要なリソース アクセス CodeLens

Agents Toolkit のマニフェスト テンプレートMicrosoft Entra、Microsoft GraphおよびOffice 365 SharePoint Onlineアクセス許可についてユーザーが判読できる文字列もサポートしています。 公式のMicrosoft Entra マニフェスト スキーマ (requiredResourceAccess プロパティのresourceAppIdとresourceAccess) は、UUID のみをサポートします。 UUID を入力すると、CodeLens はユーザーが読み取り可能な文字列を表示し、それ以外の場合は UUID を表示します。

スクリーンショットは、必要なリソース アクセスへのリソースの追加を示しています。

事前承認済みアプリケーション CodeLens

CodeLens は、API プロパティ内の preAuthorizedApplications プロパティの事前承認済みアプリケーション ID のアプリケーション名を表示します。

Azure portal で Microsoft Entra アプリケーションを表示する

  1. AAD_APP_CLIENT_ID プロパティの .env.xxx () ファイルからMicrosoft Entra アプリケーション クライアント ID をコピーします。

    スクリーンショットはクライアント ID を示しています。

    注:

    クライアント ID の xxx は、Microsoft Entra アプリケーションを展開した環境名を示します。

  2. Azure portal に移動し、Microsoft 365 アカウントにサインインします。

    注:

    Teams アプリケーションと M365 アカウントのログイン資格情報が同じであることを確認します。

  3. [アプリの登録] ページを開き、以前にコピーしたクライアント ID を使用して Microsoft Entra アプリケーションを検索します。

    スクリーンショットは、[すべてのアプリケーション] タブの下のクライアント ID を示しています。

  4. 検索結果から [Microsoft Entra アプリケーション] を選択して、詳細情報を表示します。

  5. Microsoft Entra アプリの情報ページで、[マニフェスト] メニューを選択して、このアプリケーションのマニフェストを表示します。 マニフェストのスキーマは、 aad.template.json ファイル内のスキーマと同じです。 マニフェストの詳細については、「Microsoft Entra アプリ マニフェスト」を参照してください。

    スクリーンショットは、マニフェスト画面を示しています。

  6. [その他] メニューを選択すると、ポータルを介して Microsoft Entra アプリケーションを表示または構成できます。

既存の Microsoft Entra アプリケーションを使用する

Teams プロジェクトには既存の Microsoft Entra アプリケーションを使用できます。 詳細については、「Teams アプリケーションに既存の Microsoft Entra アプリケーションを使用する」を参照してください。

Teams アプリケーション開発ライフサイクルでの Microsoft Entra アプリケーション

Teams アプリケーション開発ライフサイクルのさまざまな段階で、Microsoft Entra アプリケーションを操作する必要があります。

  1. プロジェクトを作成するには

    SSO-enabled tab など、デフォルトでシングル サインオン (SSO) サポートが付属する Agents Toolkit を使用してプロジェクトを作成できます。 新しいアプリを作成する方法の詳細については、「 Agents Toolkit を使用して新しい Teams アプリケーションを作成する」を参照してください。 Microsoft Entra マニフェスト ファイルが aad.template.json で自動的に作成されます。 Agents Toolkit では、ローカル開発中またはクラウドへの移動中に、Microsoft Entra アプリケーションが作成または更新されます。

  2. ボットまたはタブに SSO を追加するには

    SSO を内蔵していない Teams アプリケーションを作成した後、Agents Toolkit は、プロジェクトの SSO を段階的に追加するのに役立ちます。 その結果、Microsoft Entra マニフェスト ファイルが aad.template.json で自動的に作成されます。

    Agents Toolkit では、次回のローカル開発セッション中、またはクラウドへのアプリケーションの移動中に、Microsoft Entra アプリケーションが作成または更新されます。

  3. ローカルでビルドするには

    Agents Toolkit は、ローカル開発中に次の機能を実行します。

    • .env.local ファイルを読み、既存の Microsoft Entra アプリケーションを見つけます。 Microsoft Entra アプリケーションが既に存在する場合、エージェント ツールキットは既存の Microsoft Entra アプリケーションを再利用します。 それ以外の場合は、 aad.template.json ファイルを使用して新しいアプリケーションを作成する必要があります。

    • マニフェスト ファイルを使用して新しい Microsoft Entra アプリケーションを作成するときにローカル開発エンドポイントを必要とするプロパティなどredirectUris追加のコンテキストを必要とするマニフェスト ファイルの一部のプロパティを最初に無視します。

    • ローカル開発環境が正常に起動すると、作成段階で使用できなかったMicrosoft Entra アプリケーションのidentifierUris、redirectUris、およびその他のプロパティがそれに応じて更新されます。

    • Microsoft Entra アプリケーションに加えた変更は、次回のローカル開発セッション中に読み込まれます。 手動で適用された Microsoft Entra アプリケーションの変更を確認できます。

  4. クラウド リソースをプロビジョニングするには

    アプリケーションをクラウドに移動しながら、クラウド リソースをプロビジョニングしてアプリケーションをデプロイする必要があります。 ローカル デバッグなどの段階では、Agents Toolkit:

    • .env.{env} ファイルを読み取り、既存の Microsoft Entra アプリケーションを見つけます。 Microsoft Entra アプリケーションが既に存在する場合、エージェント ツールキットは既存の Microsoft Entra アプリケーションを再利用します。 それ以外の場合は、 aad.template.json ファイルを使用して新しいアプリケーションを作成する必要があります。

    • プロパティなど、より多くのコンテキストを必要とするマニフェスト ファイル内の一部のプロパティ redirectUris 最初に無視します。 このプロパティには、マニフェスト ファイルを使用して新しい Microsoft Entra アプリケーションを作成するときにフロントエンドまたはボット エンドポイントが必要です。

    • 他のリソースのプロビジョニングを完了し、アプリケーションのidentifierUrisとredirectUrisMicrosoft Entra正しいエンドポイントに従って更新します。

  5. アプリケーションをビルドするには

    • クラウド コマンドは、プロビジョニングされたリソースにアプリケーションをデプロイします。 行った Microsoft Entra アプリケーションのデプロイは含まれません。

    • エージェント ツールキットは、Microsoft Entra マニフェスト テンプレート ファイルに従って Microsoft Entra アプリケーションを更新します。

制限事項

  1. Agents Toolkit 拡張機能は、Microsoft Entra マニフェスト スキーマに記載されているすべてのプロパティをサポートしているわけではありません。

    次の表に、Agents Toolkit 拡張機能でサポートされていないプロパティを示します。

    サポートされていないプロパティ 理由
    passwordCredentials マニフェストでは許可されていません
    createdDateTime 読み取り専用で、変更できません
    logoUrl 読み取り専用で、変更できません
    publisherDomain 読み取り専用で、変更できません
  2. requiredResourceAccess プロパティは、Microsoft Graph および Office 365 SharePoint Online API の場合にのみ、ユーザーが読み取り可能なリソース アプリケーション名またはアクセス許可名の文字列に使用されます。 他の API には UUID を使用する必要があります。 Azure portal から ID を取得するには、次の手順を実行します。

    1. Azure portal に新しい Microsoft Entra アプリケーションを登録します。
    2. [Microsoft Entra アプリケーション] ページから [API permissions] を選択します。
    3. [ add a permission ] を選択して必要なアクセス許可を追加します。
    4. requiredResourceAccess プロパティから Manifest を選択します。ここで、API の ID とアクセス許可を確認できます。

関連項目