PowerShellによるAgent 365の一括オンボーディング

複数のエージェントをオンボーディングする際の繰り返しのセットアップを減らすために、Agent 365の一括オンボーディングを活用しましょう。 エージェントの識別、スポンサー、所有者、登録を1つのレビュー可能なCSVで定義し、プロビジョニング前にそれらの関係を検証し、結果を1つの統合レポートでレビューします。 スクリプトは完全なファイルを検証し、依存関係の順序を計算し、Microsoft Graphを使って各オブジェクトを作成します。

Agent 365 CLIで単一のエージェントをオンボーディングする方法を理解した後、このワークフローを活用してください。 複数のエージェントを同時にオンボーディングしたり、テナントオンボーディングを繰り返す必要がある場合は、各エージェントごとにCLIオンボーディングワークフローを別々に動かすのではなく、オブジェクトとその関係を1つのCSVファイルで定義してください。

この記事では、自動化、アプリケーションのセットアップ、CSV要件から検証、実行、トラブルシューティングに至るまで、エンドツーエンドの一括オンボーディング手順を提供します。

ワークフローが生み出すもの

各CSV行は1つのオブジェクトを表します。 サポートされる関係は以下の通りです:

Blueprint
  |
  +-- AgentIdentity
        |-- AgentUser
        +-- AgentRegistration

エージェントユーザーとエージェント登録は、エージェントアイデンティティの独立した子です。 一方の失敗がもう一方の試みを妨げるわけではありません。

これらのオブジェクトについての詳細は、Agent 365 identityを参照してください。

Prerequisites

始める前に、以下のことを確認してください:

• Microsoft Agent 365が利用可能なテナントです。
• PowerShell 7 以降。
• Git を使用して DevTools リポジトリ をクローンします。
• Microsoft.Graph.AuthenticationPowerShellモジュールバージョン2.x。
• 1 回限りの自動化アプリケーションのアクセス許可を行うには、特権ロール管理者以上のアクセス許可が必要です。
• 新しいブループリントやエージェント ID ごとに、スポンサーがあります。
• すでにMicrosoft Entra IDに存在する所有者、管理者、登録所有者。
• 新しいエージェントのユーザー プリンシパル名 (UPN) ごとに、検証済みのテナント ドメイン。
• CSV でエージェント ユーザーにライセンスが割り当てられている場合、適切なライセンスと 2 文字の利用場所を指定します。

エージェントユーザーは Frontierプレビュープログラムに参加しているテナントのみが利用可能です。

必要なMicrosoft Graphモジュールをインストールする:

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser

スクリプトを入手する

Agent 365 DevToolsリポジトリをクローンし、その後バルク登録ディレクトリに移動します:

git clone https://github.com/microsoft/Agent365-devTools.git
Set-Location .\Agent365-devTools\scripts\bulk-agent-registration

このディレクトリ内のスクリプトをまとめて保管してください。 A365-BulkOnboarding.ps1 は A365-AutomationOrchestrator.ps1 を呼び出し、オブジェクト固有のプロビジョニングスクリプトを呼び出します。

認証を構成する

一括オンボーディングは、テナント所有の自動化アプリケーションやシステムに割り当てられたマネージドIDを用いて無人で実行できます。 また、委任認証でインタラクティブに動作することも可能です。

最初のバッチの前には、アプリケーションのセットアップ、権限の同意、認証設定を完了させてください。 その後のバッチごとにCSVを作成し、計画を検証し、オンボーディングを実行し、結果を確認します。

アプリのみの実行は、自動化アプリケーションまたはマネージド ID のサービス プリンシパルに付与されたアプリケーション ロールを使用します。オペレーターの管理者ロールではありません。

ランナーアイデンティティへの権限の付与は、ブループリントまたはエージェントアイデンティティによって宣言された権限への同意を要求する CSV の GrantAdminConsent 設定とは別です。 ランレポートで同意に関する未処理のアクションを確認しましょう。

バルクオンボーディングは以下のランナー認証方法をサポートしています:

連合型ID認証やユーザー割り当て管理型アイデンティティ選択はランナー認証方法としてサポートされていません。

自動化アプリケーションを作成する

グローバル管理者または特権ロール管理者として対話形式でサインインし、サポートされているすべてのオブジェクトタイプを対象とした自動化アプリケーションを作成します。 クライアントシークレットや証明書なしでアプリケーションを作成し、Microsoft Entra 管理センターで認証情報を追加・管理できます:

.\New-A365AutomationApp.ps1 `
    -TenantId <tenant-id> `
    -Interactive `
    -DisplayName 'A365 Provisioning Automation' `
    -Scenario All `
    -SkipGrant

スクリプトはアプリケーションとサービスプリンシパルを作成または再利用し、必要なMicrosoft Graphアプリケーション権限と委任されたスコープを宣言します。 認証情報が追加されていないという警告は予想されます。クライアントのシークレットや証明書を追加しないと、アプリケーションは認証できません。 コマンドが -SkipGrantを使うため、管理者の同意は付与されません。

コマンドの実行が完了したら、スクリプトによって表示されたポータルの URLを、管理者に開いてもらうよう依頼します。 Microsoft Entra 管理センターで、宣言された権限に対して「Grant admin consent」を選択します。 管理者の同意が完了するまでは一括オンボーディングを始めないでください。 アプリケーションと不足している権限宣言を整合させるために、スクリプトを再度実行できます。

自動化アプリケーションの アプリケーション(クライアント)IDを記録します。 コマンドが -ClientIdを求めているときにサービスプリンシパルオブジェクトIDを使わないでください。

アプリケーションの権限を確認しましょう

-Scenario All は、以下の Microsoft Graph アプリケーションアクセス許可の結合を宣言します:

AgentUser、AgentIdentity、Registration、All の各シナリオでも、選択した対話型操作に対して委任されたスコープを宣言します。 登録スコープは既定で宣言され、抑止できます。 Auth=Sameを使う無人実行は、前のテーブルのアプリケーション権限に依存します。

認証入力の設定

認証ハッシュテーブルを1つ定義し、それを検証と実行に再利用します。

クライアント シークレット

Microsoft Entra 管理センターでIdentity>Applications>アプリの登録にアクセスし、自動化アプリケーションを選択します。 証明書とシークレット>クライアント シークレット>新しいクライアント シークレット を選択し、説明と有効期限を入力してから 追加 を選択します。 秘密 の値を すぐにコピーして安全に保存してください。ページを離れた後は表示されません。 詳細については、「アプリケーションに資格情報を追加する」をご覧ください。

クライアント シークレットをコマンドラインに直接指定するのではなく、SecureString として読み込んでください:

$clientSecret = Read-Host -Prompt 'Automation application client secret' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    ClientSecret = $clientSecret
}

クライアント シークレットは証明書よりも安全性が低く、テストや短期間の自動化に限定すべきです。 無人本番自動化の場合は、証明書またはシステムに割り当てられたマネージドアイデンティティを使用します。

Certificate

本番自動化については、組織の認証機関から証明書を取得してください。 テスト環境については、「アプリケーションを認証するための自己署名済みパブリック証明書を作成する」を参照してください。 自動化アプリケーションの 証明書 & シークレット ページで、証明書>証明書のアップロード を選択し、パブリック .cer、.pem、または .crt ファイルをアップロードしてから、追加 を選択します。 ランナーは秘密鍵へのアクセスが必要です。自動化アプリケーションは公開証明書のみを保存します。 アプリのみの証明書認証についての詳細は、「Microsoft Graph PowerShell SDKでアプリのみ認証を使う」をご覧ください。

秘密鍵を持つ証明書の指紋を使ってください:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificateThumbprint = '<certificate-thumbprint>'
}

AgentUserの行を含むバッチの場合は、証明書を Cert:\CurrentUser\Myにインストールしてください。 Cert:\LocalMachine\Myの証明書をすべてのオブジェクトタイプで使用する場合は、サムプリントではなく証明書オブジェクトとして渡してください。

あるいは、証明書を X509Certificate2 オブジェクトとして提供することもできます:

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Certificate = Get-Item 'Cert:\CurrentUser\My\<certificate-thumbprint>'
}

またはパスワード保護されたPFXから秘密鍵を読み込む方法もあります:

$pfxPassword = Read-Host -Prompt 'PFX password' -AsSecureString
$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    CertificatePath = 'C:\secure\a365-automation.pfx'
    CertificatePassword = $pfxPassword
}

証明書ソースは 1 つだけ指定してください。 -CertificatePassword は -CertificatePathに対してのみ有効です。

システムによって割り当てられた管理ID

スクリプトを実行するAzureリソースでシステム割り当てのマネージド アイデンティティを有効にしてください。 前のテーブルからマネージド ID のサービス プリンシパルに直接必要な Microsoft Graph アプリケーション権限を付与します。 手順については、「管理されたアイデンティティに対するAPI権限の付与および取り消し」を参照してください。

$authParameters = @{
    TenantId = '<tenant-id>'
    UseManagedIdentity = $true
}

ClientId を UseManagedIdentity に含めないでください。 スクリプトはホストのシステム割り当てIDを使用し、ユーザー割り当てのID選択には対応していません。

対話型委任サインイン

呼び出し側制御のアプリケーションクライアントIDを使用して、同じ例でAgentUserの行を含むCSVファイルもサポートします。

$authParameters = @{
    TenantId = '<tenant-id>'
    ClientId = '<automation-app-client-id>'
    Interactive = $true
}

ClientIdを提供する場合、インタラクティブな認可はそのアプリケーションの同意された委任スコープとサインインしたユーザーのディレクトリロールに依存します。 New-A365AutomationApp.ps1 -Scenario All 委任されたスコープを宣言し、パブリッククライアントフローを可能にします。 最初のインタラクティブ実行前に、セットアップスクリプトで表示された管理者同意URLにアクセスしてください。 バッチにAgentUserの行が含まれていなければ、ClientIdを省略できます。その場合、スクリプトはMicrosoft Graph PowerShellクライアントとその同意済みスコープを使用します。 AgentUser操作には、Agent ID Administratorのような適切な役割が必要です。 背景情報については、「Microsoft Graph PowerShell認証コマンドの使用」を参照してください。

CSV ファイルを準備する

sample-bulk-onboarding.csv を起動します。 行に当てはまらなくても、すべてのヘッダーをサンプル内に残してください。 該当しない値は空欄にしてください。

サンプルには、サポートされているすべてのオブジェクトタイプを表す行が含まれています。 例として挙げられているドメイン、ID、所有者、スポンサー、管理者、ライセンスの値を、ご利用のテナントの値に置き換えてください。

リレーションシップを定義する

最初の4列はオブジェクトグラフを定義します:

既存のブループリントの下でエージェントIDを作成するには、Blueprint がブループリントアプリケーションIDである ExistingId アンカー行を追加します。 新しいAgentIdentity行ごとに、アンカー行のParentKeyに一致するKeyを付けます。

各オブジェクトタイプの値を設定する

オンボーディング計画の検証

テナント オブジェクトを作成する前に、CSV ファイル全体を -WhatIf で処理します:

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -WhatIf

スクリプトはMicrosoft Graphリクエストを出す前にCSV全体を検証します。 検出されたすべての構造的誤りをまとめて報告します。以下を含みます:

• ヘッダーの欠落または不明。
• 必要な値が欠けている。
• 重複したキー。
• サポートされていないオブジェクトタイプ。
• 無効なGUID、UPN、ブール値、またはJSONの値。
• 無効な ParentKey または ExistingId の組み合わせ。
• オブジェクトの親の型が不正です。
• 依存関係の循環。
• 行のオブジェクトタイプに適用されない列の値

検証が成功すると、コマンドは依存関係のプランを出力します。 -WhatIfでは、スクリプトはMicrosoft Graphにonboarding rowを送りません。

検証に成功すれば、CSVが構造的チェックに合格していることが確認されます。 これは、テナント オブジェクトが解決可能であること、あるいはアプリケーションがそれらを作成するために必要なアクセス許可を持っていることを保証するものではありません。

一括オンボーディングを実行

-WhatIf プランに問題がないことを確認したら、オンボーディングを実行し、ログと集計レポートを保存します。

.\A365-BulkOnboarding.ps1 `
    -CsvPath .\sample-bulk-onboarding.csv `
    @authParameters `
    -LogPath .\logs `
    -OutputJsonPath .\bulk-onboarding-result.json

スクリプトは、無関係な行の間でCSVの順序を保持しつつ、子より先に親を処理します。 1 行の処理が失敗した場合:

• このスクリプトは、その子要素を SkippedDependency としてマークし、Microsoft Graph には送信しません。
• 独立した依存関係ツリーは引き続き存在します。
• このコマンドは終了前にコンソールの要約と集計レポートを書き込みます。
• いずれかの行が Failed または SkippedDependency の場合、このコマンドは 0 以外の終了コードを返します。

結果の確認

最終行のステータスは以下の通りです:

-OutputJsonPathパラメータは、実行全体に対して1つのA365BulkProvisioningRunReportを作成します。 以下について報告書をレビューしてください:

• 各行の状態と解決済み ID。
• 失敗した手順とエラーの詳細。
• 未処理の管理者承認アクション。
• ブループリント、ID、ユーザー、登録識別子を作成しました。

バルクスクリプト、オーケストレーター、子スクリプトのログは、同じ -LogPathを使う場合、同じ相関IDを共有します。

レポートには、明示的に -IncludeBlueprintSecretsInOutput を使用する場合を除き、Blueprint クライアントのシークレットは含まれません。 報告書には認証入力、アクセストークン、証明書パスワードは一切含まれていません。

オンボーディングを確認する

実行後:

• 各行の状態と結果として得られるオブジェクトIDを確認しましょう。
• Agent 365 管理画面に期待される登録が表示されていることを確認してください。
• 割り当てられたスポンサーやオーナーを確認してください。
• エージェントユーザーやライセンスをリクエストした場合は、その割り当てを確認してください。
• 未処理の管理者承認アクションを確認し、完了してください。

部分的な実行からの復旧

ExistingId のアンカー行を通じて、既存のブループリントやエージェント ID を参照できます。 このオプションは、エージェント ユーザー行や登録行ではサポートされていません。

失敗を修正し、成功した行を盲目的に再実行するのではなく、観察されたテナントの状態に基づいてレビュー済みの再試行バッチを準備しましょう。

Troubleshooting

以下の表を使って、よくあるオンボーディングの問題を解決してください。

一般的な製品およびCLIの問題については、 Agent 365トラブルシューティングガイドをご覧ください。 これらのスクリプトの問題を報告するには、Agent 365 DevTools の Issuesを使ってください。

次のステップ

エージェントのオンボーディングが完了した後:

• Agent 365との統合を検証してください。
• Microsoft 365 管理センターにエージェントを公開します。
• Agent 365 ID の詳細を確認する。