Agent 365 CLI用のカスタムクライアントアプリ登録

Agent 365のCLIは、エージェントIDブループリントの認証と管理のために、Microsoft Entra IDテナント内でカスタムクライアントアプリの登録が必要です。

[前提条件]

アプリの登録方法 (ステップ1と2):

• デフォルトでは、テナント内のどのユーザーでもMicrosoft Entra管理センターでアプリケーションを登録できます。 しかし、 テナント管理者はこの機能を制限することができます。

許可証の追加および同意付与(ステップ3):

• これらの管理職のうちの1つが必須です:
  • アプリケーション管理者:推奨 - アプリ登録管理および同意付与が可能です
  • クラウドアプリケーション管理者:アプリの登録管理と同意付与が可能です
  • グローバル管理者:すべての権限を持っていますが必須ではありません

ステップ1:申請登録

これらの手順は 、アプリ登録を作成するための全ての手順をまとめたものです。

1. Microsoft Entra管理センターへ行く
2. 選択 アプリ登録
3. 新規登録を選択します
4. 入力：
   • 名前: Agent365 CLI (またはお好みの名前)
   • 対応アカウントタイプ: この組織ディレクトリ内のアカウントのみ (シングルテナント)
   • リダイレクト URI:Public client/native (mobileおよびデスクトップ) → Enter http://localhost:8400/
5. [登録] を選択します

ステップ2:アプリケーション(クライアント)IDをコピーする

アプリの 概要 ページから、 アプリケーション(クライアント)ID (GUID形式)をコピーします。 a365 config initコマンドを使うときにこの値を入力してください。

ステップ3:API権限の設定

適切な方法を選択してください:

• オプションA:すべての権限はMicrosoft Entra管理センターで行う(ベータ権限が見える場合)
• オプションB:Microsoft Graph APIを使ってすべての権限を追加する(ベータ権限が見えない場合は推奨)

オプションA:Microsoft Entra管理センター(標準方法)

テナントにベータ権限が表示されている場合はこの方法を使ってください。

1. アプリ登録でAPI権限に行ってください

2. Microsoft Graph→権限を追加→委任権限を選択します

   Important

   委任 権限 (アプリケーション権限ではなく)を必ず使用してください。 CLIはインタラクティブに認証します。あなたがサインインすると、CLIが代わりに行動します。 誤ってアプリケーション権限を追加した場合は「 間違った権限タイプ 」を参照してください。

3. これら5つの権限を一つずつ追加してください:

   権限	目的
   AgentIdentityBlueprint.ReadWrite.All	エージェントブループリント設定管理(ベータAPI)
   AgentIdentityBlueprint.UpdateAuthProperties.All	Update Agent Blueprint inheritable permissions (ベータAPI)
   Application.ReadWrite.All	アプリケーションとエージェントブループリントの作成・管理
   DelegatedPermissionGrant.ReadWrite.All	エージェントブループリントに対する権限付与
   Directory.Read.All	ディレクトリデータを読み込んで検証してください

   各許可について:

   • 検索ボックスで権限名(例: AgentIdentityBlueprint.ReadWrite.All)を入力してください。
   • 許可欄の隣のチェックボックスにチェックを入れてください
   • [アクセス許可の追加] を選択する
   • この繰り返しは5つの権限すべてで

4. [Your Tenant] の管理者同意を付与を選択します

   • これが必要な理由 エージェント識別ブループリントは、複数のユーザーやアプリケーションが参照できるテナント全体のリソースです。 テナント全体の同意がなければ、CLIは認証中に失敗します。
   • もし失敗したら? アプリケーション管理者、クラウドアプリケーション管理者、またはグローバル管理者の役割が必要です。 テナント管理者に助けを求めてください。

5. すべての権限を確認し、ステータスの下に緑色のチェックマークが表示されます

ベータ権限(AgentIdentityBlueprint.*)が表示され ない場合は、 オプションBに進みます。

オプションB:Microsoft Graph API(ベータ権限用)

Microsoft Entra管理センターで権限が見えない場合は AgentIdentityBlueprint.* この方法を使ってください。

1. オープン グラフエクスプローラー

2. 管理者アカウント(アプリケーション管理者またはクラウドアプリケーション管理者)でサインインしてください。

3. Graph APIを使って管理者の同意を付与します。 これを完成させるには、以下の条件が必要です:

   • サービスプリンシパルIDです。 SP_OBJECT_ID変数値が必要です。
   • グラフリソースID。 GRAPH_RESOURCE_ID変数値が必要です。
   • oAuth2PermissionGrantリソースタイプを用いて、変数のSP_OBJECT_IDとGRAPH_RESOURCE_ID値を付けて委任権限を作成(または更新)できます。

以下のセクションの情報を活用してこれを完成させてください。

サービスプリンシパルIDを取得しましょう

サービスプリンシパルとは、APIを通じて権限を付与する前にテナント内でアプリのアイデンティティのことです。

1. グラフエクスプローラーのメソッドを GET に設定し、このURLを使います( <YOUR_CLIENT_APP_ID> をステップ2の実際のアプリケーションクライアントIDに置き換えてください :アプリケーション(クライアント)IDをコピーしてください):

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. [クエリの実行] を選択します。

   • クエリが成功した場合、返される値はあなたの SP_OBJECT_IDとなります。

   • もしクエリが権限エラーで失敗した場合は、「 権限の変更 」タブを選択し、必要な権限に同意してから再度 「クエリを実行する 」を選択します。 返される価値があなたの SP_OBJECT_IDです。

   • もしクエリが空の結果("value": [])を返した場合、以下の手順でサービスプリンシパルを作成します。

     1. メソッドを POST に設定し、このURLを使います:

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        リクエストボディ ( YOUR_CLIENT_APP_ID を実際のアプリケーションクライアントIDに置き換える):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. [クエリの実行] を選択します。 201 Created返事が来るはずです。 返 id 値があなたの SP_OBJECT_IDです。

GraphリソースIDを取得しましょう

1. グラフエクスプローラーのメソッドを GET に設定し、次のURLを使います:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. [クエリの実行] を選択します。

   • クエリが成功したら、 id 値をコピーします。 これがあなたの GRAPH_RESOURCE_IDです。
   • もしクエリが権限エラーで失敗した場合は、「 権限の変更 」タブを選択し、必要な権限に同意してから再度 「クエリを実行する 」を選択します。 id 値をコピーします。 これがあなたの GRAPH_RESOURCE_IDです。

権限委託の作成

このAPIコールにより、Microsoft Entra管理センターには表示されない2つのベータ権限を含む5つの権限すべてに対してテナント全体の管理者同意が付与されます。

1. グラフエクスプローラーのメソッドを POST に設定し、このURLとリクエスト本文を使用します:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   リクエスト本文:

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. [クエリの実行] を選択します。

   • もし201 Created返事があれば:成功です! レスポンスの scope フィールドには5つの権限名すべてが表示されます。 これで完了です。
   • もしクエリが権限エラー(おそらくDelegatedPermissionGrant.ReadWrite.All)で失敗した場合は、「権限の修正」タブを選択し、同意DelegatedPermissionGrant.ReadWrite.Allから再度「クエリを実行する」を選択します。
   • エラーRequest_MultipleObjectsWithSameKeyValueの場合は、すでに助成金が存在します。 もしかすると誰かが先に権限を追加したのかもしれません。 以下の更新権限委 譲を参照してください。

委任された権限を更新

「委任権限の作成」ステップでRequest_MultipleObjectsWithSameKeyValueエラーが出たら、これらのステップを使って委任権限を更新してください。

1. グラフエクスプローラーのメソッドを GET に設定し、次のURLを使います:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. [クエリの実行] を選択します。 応答から id の値をコピーします。 これは YOUR_GRANT_ID。

3. グラフエクスプローラーのメソッドを PATCH に設定し、このURLを YOUR_GRANT_IDで使います。

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   リクエスト本文:

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. [クエリの実行] を選択します。 scope欄で5つの権限すべてが入った200 OK返答が返ってくるはずです。

トラブルシューティング

このセクションには、カスタムクライアントアプリの登録に関するエラーのトラブルシューティング方法に関する情報が含まれています。

誤った権限タイプ(委任 vs アプリケーション)

症状:CLIが認証エラーや権限拒否エラーで失敗します。

根本原因:委任権限の代わりにアプリケーション権限を追加したことです。

なぜ委任されたのか?

• サインインはインタラクティブ(ブラウザ認証)です
• CLIは あなたの行動をリアルタイムで 実行します(監査トレイルであなたの身元が示されます)
• より安全です - 実際の権限によって制限されます
• 説明責任とコンプライアンスの確保

解決策:

1. Microsoft Entra管理センター>App registrations> Your app >API permissions に移動します
2. アプリケーションの権限をすべて削除してください( Type 列に「Application」として表示されています)
3. 委任権限と同じ権限を追加してください
4. 再度管理者の同意を与える

Microsoft Entra管理者の同意後にベータ権限が消滅します

症状: オプションB:Microsoft Graph API(ベータ権限用) を使ってベータ権限を追加しましたが、Microsoft Entra管理センターで 管理者同意を付与 した後に消えました。

根本原因:Microsoft Entra管理センターのUIでベータ権限が表示されないため、「 管理者同意を付与」を選択すると 、見える 権限のみが付与され、APIで付与された同意が上書きされます。

これが起こる原因:

1. Graph API(オプションB)を使ってベータ権限を含む5つの権限すべてを追加します
2. consentType: "AllPrincipals"のAPI呼び出しはすでにテナント全体の管理者の同意を与えます
3. Microsoft Entra管理センターに行くと、ベータ権限が見えないため、3つの権限しか見られません
4. 管理者同意を 付与 する必要があると思い込んで選択します
5. Microsoft Entra管理センターは、APIで付与された同意を、見える3つの権限のみで上書きします
6. あなたの2つのベータ権限は削除されました

解決策:

• APIメソッドの後にMicrosoft Entra管理者センターの管理者同意は絶対に使わないでください:APIメソッドはすでに管理者の同意を与えています
• もし誤ってベータ権限を削除した場合は、オプションBのステップ3(Graph APIを使って管理者の同意を付与)を再実行して復元してください。 Request_MultipleObjectsWithSameKeyValueエラーが出ると、委任権限の更新手順に従ってください。
• POSTまたはPATCHの回答のscope欄で、5つの権限すべてがリストされているか確認してください

検証エラー

CLIは a365 setup または a365 config initを実行する際に自動的にクライアントアプリを検証します。

一般的な問題:

• アプリが見つからないこと: アプリケーション(クライアント)ID (オブジェクトIDではなく)をコピーしたか確認してください
• 権限が欠けている:必要な5つの権限すべてを追加してください
• 管理者の同意が下りませんでした:
  • オプションA(Microsoft Entra管理センターのみ)を使った場合:Microsoft Entra管理センターで「管理者同意を付与する」を選択してください
  • もしオプションB(グラフAPI)を使ったなら、POSTまたはリクエストPATCH再実行してください。 Microsoft Entra管理センターの同意ボタンは使わないでください
• 誤った権限タイプ:アプリケーション権限ではなく委任権限を使う

詳細なトラブルシューティングについては、「 Microsoft Entra IDでアプリケーションを登録する」をご覧ください。

セキュリティのベスト プラクティス

すべきこと:

• 単一テナント登録の利用
• 必要な5つの委任許可のみを付与してください
• 定期的に監査権限を行っています
• 不要になったらアプリを削除してください

次の手順を実行しないでください。

• アプリケーションの権限を付与する(使用委譲のみ)
• クライアントIDを公開して共有する
• 不要な権限を付与する
• アプリは他の目的で使ってください

次のステップ

カスタムクライアントアプリが登録されたので、Agent 365 CLIで使えます:

• Agent 365 CLIを使い始める - クライアントアプリでCLIをインストールし設定する
• エージェントブループリントとインスタンスの設定 - エージェントIDの作成と設定
• エージェントをデプロイ・公開 する - エージェントをAzureにデプロイし、Microsoft 365に公開する