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

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

この記事では、このプロセスを主に4つのステップに分けて説明します。

1. レジスタアプリケーション
2. リダイレクトURIを設定してください
3. アプリケーション(クライアント)IDをコピー
4. API のアクセス許可を構成する

問題がある場合は、 トラブルシューティング のセクションを参照してください。

[前提条件]

開始する前に、Microsoft Entra管理センターにアクセスできることを確認し、必要に応じて、同意を付与するために必要な管理者ロールの 1 つを持っていることを確認します。

アプリの登録方法

既定では、テナント内の任意のユーザーがアプリケーションを登録可能です。Microsoft Entra管理センター。 しかし、 テナント管理者はこの機能を制限することができます。 アプリを登録できない場合は、管理者に連絡してください。

権限の追加と同意付与

これらの管理職のうち1つが必要です 。API権限を設定しましょう。

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

1. 登録申請

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

1. Microsoft Entra管理センター に移動します

2. App registrations を選択します

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

4. 次のように入力します。

   • 名前: my-agent-appなど、アプリに意味のある名前を入力してください。 アプリ ユーザーにはこの名前が表示され、いつでも変更できます。 同じ名前で複数のアプリ登録を行うことができます。
   • 対応アカウントタイプ: この組織ディレクトリ内のアカウントのみ (シングルテナント)
   • URIをリダイレクト: パブリッククライアント/ネイティブ(モバイルおよびデスクトップ) を選択し、エンター http://localhost:8400/

5. [登録] を選択します

2. リダイレクトURIの設定

1. 概要に行き、アプリケーション(クライアント)IDの値をコピーしてください。
2. 認証(プレビュー)に行き、Add Redirect URIを選択してください。
3. モバイルおよびデスクトップアプリケーションを選択し、値をms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}に設定します。ここで{client-id}はコピーしたアプリケーション(クライアントID)の値です。
4. 値を追加するには 「構成」 を選択してください。

3. アプリケーション(クライアント)IDのコピー

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

4. API権限の設定

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

• Option A: すべてのアクセス許可Microsoft Entra管理センターを使用します (ベータ版のアクセス許可が表示されている場合)
• Option B: Microsoft Graph API を使用してすべてのアクセス許可を追加します (ベータ版のアクセス許可が表示されない場合に推奨)

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

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

1. アプリの登録で、 API のアクセス許可に移動します。

2. アクセス許可の追加>Microsoft Graph>削除されたアクセス許可を選択します。

   Important

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

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

   権限	目的
   AgentIdentityBlueprint.ReadWrite.All	エージェントブループリント設定管理(ベータAPI)
   AgentIdentityBlueprint.UpdateAuthProperties.All	エージェント ブループリントの継承可能な権限を更新する（ベータ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 管理センターでアクセス許可が表示されない場合は、このメソッドを使用してください。

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

2. 管理者アカウント(Application AdministratorまたはCloud Application Administrator)でサインインしてください。

3. Graph APIを使用して管理者の同意を付与します。 この手順を完了するには、次のものが必要です。

   • サービスプリンシパルIDです。 SP_OBJECT_ID変数値が必要です。
   • グラフリソースID。 GRAPH_RESOURCE_ID変数値が必要です。
   • oAuth2PermissionGrantリソースタイプとSP_OBJECT_ID、GRAPH_RESOURCE_ID変数の値を使用して、委任されたアクセス許可を作成または更新します。

以下のセクションの情報を活用して、これらのステップをクリアしてください。

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

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

1. Graph Explorerメソッドを GET に設定し、このURLを使います。 <YOUR_CLIENT_APP_ID>をステップ3: アプリケーション（クライアント）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. [クエリの実行] を選択します。 200 OK欄で5つの権限すべてが入ったscope返答が返ってくるはずです。

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

これらのガイドラインを確認し、アプリ登録の安全性とコンプライアンスを保ってください。

すべきこと:

• 単一テナント登録を使いましょう。
• 必要な委任許可のみを付与してください。
• 定期的に権限を見直します。
• 不要になったらアプリを削除してください。

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

• アプリケーションのアクセス許可を付与します。 委任されたものだけを使いましょう。
• クライアントIDを公開しましょう。
• 不要な許可を与えてください。
• アプリは他の目的で使ってください。

次のステップ

カスタムクライアントアプリを登録した後、Agent 365の開発ライフサイクル内のCLIと共に使用してください:

トラブルシューティング

このセクションでは、カスタムクライアントアプリの登録に関するエラーのトラブルシューティング方法について説明します。

CLIの検証が設定中に失敗します

症状：a365 config initコマンドまたはa365 setupを実行すると、カスタムクライアントアプリに関する検証エラーが発生します。

解決策: このチェックリストを使って、アプリ登録が正しいか確認してください:

# Run configuration to see validation messages
a365 config init

期待結果: CLIは Custom client app validation successfulを表示します。

期待された結果が得られない場合は、以下のチェックをすべて確認してください。

必須の委任許可:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All [ベータ版]
• AgentIdentityBlueprint.UpdateAuthProperties.All [ベータ版]
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All

管理者の同意が誤って与えられました

症状： 権限が追加されても検証が失敗します。

根本原因: 管理者の同意が与えられないか、誤って与えられている場合もあります。

解決策: 正しい解決策は、どの方法を使ったかによって異なります:

オプション B の後に、Microsoft Entra 管理センターを誤って使用した場合、ベータ版の権限を削除します。 委任された権限を更新し、それを復元してください。

誤った許可タイプ

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

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

この表は、さまざまな権限の種類を説明しています。

なぜ委任されたのか?

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

解決策:

1. Microsoft Entra 管理センター>アプリ登録> そのアプリ >API のアクセス許可 に移動します
2. アプリケーションの権限をすべて削除してください。 これらの権限は「タイプ」列の「アプリケーション」として表示されます。
3. 委任権限と同じ権限を追加してください。
4. 再度管理者の同意を与えてください。

Microsoft Entra 管理センターで管理者同意すると、ベータ版のアクセス許可が消えます。

Symptom: ベータ版のアクセス許可を追加するには、Option B: Microsoft Graph API (ベータ版のアクセス許可の場合) を使用しましたが、管理者センター Microsoft Entraで Grant admin consent を選択すると表示されなくなります。

根本原因: 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 管理センターで管理者の同意を使用しないでください。
• ベータ版のアクセス許可を誤って削除した場合は、Option B 手順 3 (Graph API を使用して管理者の同意を付与する) を再実行して復元します。 Request_MultipleObjectsWithSameKeyValueエラーが出た場合は、委任権限の更新手順に従ってください。
• 5つの権限すべてがリストされているか確認するには、scopeまたはPOSTレスポンスのPATCHフィールドを確認してください。

バリデーション時にアプリが見つからない

症状： CLIは Application not found または Invalid client ID エラーを報告します。

Solution:

1. アプリケーション (クライアント)ID をGUID形式でコピーしたか確認してください。オブジェクト IDではなく。

   • Microsoft Entra管理センター>アプリ登録> アプリ>概要 に移動します
   • アプリケーション(クライアント)IDの値をコピーしてください
   • フォーマットは以下の通りであるべきです: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. アプリがあなたのテナントに存在しているか確認してください:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

アプリケーションをMicrosoft Entra IDに登録する方法について説明します。