Microsoft Entra PowerShellのインストールでまず押さえるべき結論は、Microsoft.Entra（GA/v1.0）を基本にし、検証用途やプレビュー機能だけ Microsoft.Entra.Beta を使うことです。単に Install-Module を実行するだけでなく、PowerShellのバージョン、実行ポリシー、権限同意、既存のAzure AD PowerShell／MSOnlineスクリプトの移行、Azure Automationなどの自動化環境への展開まで確認する必要があります。
Microsoft Entra PowerShellは、Microsoft Entra IDのユーザー、グループ、アプリ、ポリシーなどをPowerShellで管理・自動化するためのモジュールです。公式ドキュメントでは、Microsoft.Entra と Microsoft.Entra.Beta の2系統に分かれており、前者はMicrosoft Graph v1.0、後者はMicrosoft Graph Betaに対応すると説明されています。PowerShell 7以上の利用が推奨され、Windows、Linux、macOSで利用できます。(Microsoft Learn)
Microsoft Entra PowerShellのインストールで確認すべき変更点
Microsoft Entra PowerShellの導入で重要なのは、「新しいモジュールを入れる」ことよりも、従来のAzure AD PowerShell／MSOnline前提の運用を見直すことです。
Microsoft Entra PowerShellはMicrosoft Graph PowerShell SDKと相互運用できるモジュールであり、既存のMicrosoft Graph PowerShellを使っている場合に無理に置き換える必要はありません。一方で、Azure AD PowerShellやMSOnlineのスクリプトを使い続けている環境では、移行計画を立てるべきです。公式FAQでは、従来モジュールは非推奨であり、2025年3月30日以降に停止すると説明されています。(Microsoft Learn)
| 確認ポイント | 実務上の意味 | 管理者が取るべき対応 |
|---|---|---|
Microsoft.Entra と Microsoft.Entra.Beta の分離 | 安定版とプレビュー版を分けて管理できる | 本番は原則 Microsoft.Entra、検証のみ Beta を使う |
| PowerShell 7以上の推奨 | Windows以外の環境や自動化基盤でも扱いやすい | 管理端末と実行環境のPowerShellバージョンを確認する |
| サブモジュール単位のインストール | 自動化環境で不要な依存関係を減らせる | Azure AutomationやAzure Functionsでは必要な範囲だけ入れる |
| 権限が事前同意済みではない | 必要なGraph権限を明示して同意する必要がある | 最小権限でスコープを設計し、管理者同意の範囲を記録する |
| 互換モードの利用 | AzureAD系コマンドを最小変更で動かせる場合がある | Test-EntraScript で互換性を確認してから移行する |
インストール前に確認する前提条件
Windows環境で確認すること
Windowsでは、Windows PowerShell 5.1以上またはPowerShell 7以上で利用できます。ただし、公式情報では全プラットフォームでPowerShell 7以上が推奨されています。Windows環境では、PowerShellGetの更新、.NET Framework 4.7.2以降、実行ポリシーの確認も重要です。(Microsoft Learn)
まず、現在のPowerShellバージョンと既存モジュールの有無を確認します。
$PSVersionTable.PSVersion
Get-Module -Name Microsoft.Entra -ListAvailableWindows PowerShell 5.1を使う場合は、PowerShellGetが古いとインストール時にエラーが出ることがあります。管理者権限でWindows PowerShell 5.1を起動し、必要に応じて更新します。
Install-Module -Name PowerShellGet -Force -AllowClobber実行ポリシーも確認します。
Get-ExecutionPolicy -Listユーザー単位で RemoteSigned に設定する場合は、次のように実行します。
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser実行ポリシーは組織のセキュリティ方針と関係します。端末ごとに場当たり的に変更するのではなく、管理対象PC、管理者端末、サーバー、CI/CD環境でルールを分けて確認してください。
LinuxとmacOSで確認すること
LinuxとmacOSでは、PowerShell 7以上を導入し、ターミナルから pwsh を起動してインストールします。Linux環境では、必要に応じてMicrosoft Graph PowerShell SDKの依存関係も確認します。(Microsoft Learn)
pwshその後のインストールコマンドは、Windowsとほぼ同じです。OS差分よりも、プロキシ、証明書、PowerShell Galleryへの通信可否、実行ユーザーの権限のほうがトラブルになりやすい点に注意してください。
Microsoft.Entra と Microsoft.Entra.Beta の使い分け
Microsoft Entra PowerShellには、安定版の Microsoft.Entra とプレビュー版の Microsoft.Entra.Beta があります。名前が似ているため、特に自動化スクリプトでは混在に注意が必要です。
| モジュール | 用途 | 本番利用の判断 |
|---|---|---|
Microsoft.Entra | Microsoft Graph v1.0に対応するGA版 | 本番運用の基本にする |
Microsoft.Entra.Beta | Microsoft Graph Betaに対応するプレビュー版 | 検証、先行確認、Beta機能が必要な場合に限定する |
Microsoft.Entra.Users などのサブモジュール | 特定領域だけを導入 | 自動化環境や最小構成に向く |
Microsoft.Entra.Beta.Users などのBetaサブモジュール | Beta版の特定領域だけを導入 | 本番では影響範囲を明確にして使う |
本番環境では、まず Microsoft.Entra を標準にしてください。Beta は便利ですが、APIや出力の変更が起きる可能性を前提に、検証環境で動作確認してから使うべきです。
Microsoft Entra PowerShellの基本インストール手順
現在のユーザーにインストールする
管理者権限を使わず、現在のユーザーだけにインストールする場合は -Scope CurrentUser を指定します。管理端末で試す場合や、個人の検証環境ではこの方法が扱いやすいです。
Install-Module -Name Microsoft.Entra -Repository PSGallery -Scope CurrentUser -Force -AllowClobberBeta 版を入れる場合は、次のコマンドを使います。
Install-Module -Name Microsoft.Entra.Beta -Repository PSGallery -Scope CurrentUser -Force -AllowClobber公式ドキュメントでも、PowerShell Galleryから Install-Module を使ってインストールする手順が案内されています。-Scope AllUsers に変更する場合は管理者権限が必要です。(Microsoft Learn)
全ユーザーにインストールする
共有管理端末やサーバーに全ユーザー向けで導入する場合は、管理者権限でPowerShellを起動し、-Scope AllUsers を指定します。
Install-Module -Name Microsoft.Entra -Repository PSGallery -Scope AllUsers -Force -AllowClobberInstall-Module -Name Microsoft.Entra.Beta -Repository PSGallery -Scope AllUsers -Force -AllowClobber全ユーザー向けインストールは便利ですが、複数の管理者が同じ端末を使う場合、モジュール更新のタイミングでスクリプトの挙動が変わることがあります。本番運用では、インストール日、バージョン、更新担当者を記録しておくとトラブル時に切り分けしやすくなります。
必要なサブモジュールだけをインストールする
Azure Automation、Azure Functions、CI/CDパイプラインなどでは、全体モジュールではなく必要なサブモジュールだけを入れるほうが管理しやすい場合があります。公式ドキュメントでも、特定サブモジュールのインストールは自動化シナリオに適していると説明されています。(Microsoft Learn)
GA版のサブモジュールを探すには、次のように実行します。
Find-Module -Name "Microsoft.Entra*" -Repository PSGallery |
Where-Object { $_.Name -notmatch "beta" }たとえばユーザー管理だけに絞る場合は、次のようにインストールします。
Install-Module -Name Microsoft.Entra.Users -Repository PSGallery -Force -AllowClobberBeta版のサブモジュールを探す場合は、次のコマンドを使います。
Find-Module -Name "Microsoft.Entra*" -Repository PSGallery |
Where-Object { $_.Name -match "beta" }Beta版のユーザー管理サブモジュールを入れる例です。
Install-Module -Name Microsoft.Entra.Beta.Users -Repository PSGallery -Force -AllowClobberサブモジュール導入は軽量ですが、スクリプトで使うコマンドが別サブモジュールに含まれていると実行時に失敗します。導入前に、スクリプト内のコマンドを棚卸ししておきましょう。
インストール後に必ず確認すること
バージョンとインストール場所を確認する
インストール後は、モジュールがどこに入り、どのバージョンが使われるのかを確認します。
Get-InstalledModule -Name Microsoft.Entra* |
Where-Object { $_.Name -notmatch "Beta" } |
Format-Table Name, Version, InstalledLocation -AutoSize特定のサブモジュールだけ確認する場合は、次のように実行します。
Get-InstalledModule -Name Microsoft.Entra.UsersBeta版を確認する場合は、次のコマンドを使います。
Get-InstalledModule -Name Microsoft.Entra.Beta*公式ドキュメントでは、出力されたバージョンがPowerShell Gallery上の最新バージョンと一致するか確認するよう案内されています。PowerShell Gallery側のバージョンは更新されるため、記事や手順書に固定値を書きっぱなしにせず、運用時点で確認してください。(Microsoft Learn)
Microsoft Entra IDへ接続する
インストールできたら、Connect-Entra でMicrosoft Entra IDに接続します。たとえばユーザー情報を読み取る場合は、必要なスコープを指定します。
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "userPrincipalName eq '[email protected]'"Beta版コマンドを使う場合は、次のようになります。
Connect-Entra -Scopes 'User.Read.All'
Get-EntraBetaUser -Filter "userPrincipalName eq '[email protected]'"公式ドキュメントでは、新しいPowerShellセッションを開始するたびにサインインが必要だと説明されています。自動化環境では、対話型サインインに依存しない認証方式を別途設計してください。(Microsoft Learn)
管理者が確認すべきセキュリティ上の注意点
権限は「必要最小限」で設計する
Microsoft Entra PowerShellは、Azure AD PowerShellやMSOnlineのような事前同意済みモジュールではありません。必要な権限を明示し、ユーザーまたは管理者が同意する必要があります。公式FAQでは、この仕組みにより、アプリケーションに必要な権限だけを付与できると説明されています。(Microsoft Learn)
たとえば、ユーザーの読み取りだけでよいスクリプトに、アプリケーションやディレクトリ全体を書き換える権限を与えるべきではありません。実務では、次のように分けて考えると整理しやすくなります。
| 利用シーン | 推奨される考え方 |
|---|---|
| 管理者が手元で確認する | 委任権限を使い、必要なスコープだけ指定する |
| 定期レポートを自動生成する | アプリ登録を作成し、読み取り権限を最小限にする |
| ユーザーやグループを変更する | 変更対象、実行者、承認フローを明確にする |
| 複数部門で使う | 部門別・用途別にアプリ登録を分ける |
Microsoftのベストプラクティスでは、用途ごとにカスタムアプリを登録し、最小権限を適用すること、利用後に Disconnect-Entra で接続情報を削除することが推奨されています。(Microsoft Learn)
Connect-Entra -ClientId '<your-custom-app-id>' -TenantId '<your-tenant-id>'
Disconnect-Entra委任権限とアプリケーション権限を混在させない
対話型でサインインして使う場合は委任権限、バックグラウンドサービスやデーモンのようにサインインユーザーが存在しない場合はアプリケーション権限を使います。公式ベストプラクティスでは、同じアプリで委任権限とアプリケーション権限を安易に混在させないよう注意しています。(Microsoft Learn)
特に注意したいのは、管理者が手動実行するだけのスクリプトに強いアプリケーション権限を与えてしまうケースです。実行者の権限を超えて処理できる状態になるため、監査や承認の観点で問題になりやすくなります。
既存スクリプトの移行で確認するポイント
Azure AD PowerShellのスクリプトは互換モードで試せる
Azure AD PowerShellからMicrosoft Entra PowerShellへ移行する場合、Enable-EntraAzureADAlias を使うことで、既存のAzureAD系コマンドを最小限の変更で動かせる場合があります。公式ドキュメントでは、Microsoft Entra PowerShellはAzure AD PowerShellモジュールと98%以上の互換性があり、互換モードでは Enable-EntraAzureADAlias を使うと説明されています。(Microsoft Learn)
たとえば、従来のスクリプトが次のように始まっていたとします。
Connect-AzureAD
Get-AzureADApplication -All $trueMicrosoft Entra PowerShellでは、冒頭を次のように置き換えて試します。
Import-Module -Name Microsoft.Entra.Applications
Connect-Entra -Scopes 'Application.Read.All'
Enable-EntraAzureADAlias
Get-AzureADApplication -All $trueただし、互換モードは「移行を楽にするための手段」であり、永続的に古いコマンド名へ依存する設計は避けるべきです。長期的には Get-EntraApplication など、Microsoft Entra PowerShellのコマンドレットへ置き換えるほうが保守しやすくなります。
Test-EntraScript で事前検証する
既存スクリプトを移行する前に、Test-EntraScript で互換性を確認します。公式ドキュメントでは、このコマンドにより、Azure AD PowerShellコマンドを含むスクリプトがMicrosoft Entra PowerShellで動作するか確認でき、問題があれば行番号や問題種別などを表示すると説明されています。(Microsoft Learn)
移行時は、特に次の点を重点的に確認してください。
| 確認対象 | 注意点 |
|---|---|
-Filter | Azure AD PowerShell時代と同じ結果にならない可能性がある |
-SearchString | 期待した検索結果にならない場合がある |
| 出力オブジェクト | プロパティ名や構造の差で後続処理が失敗することがある |
| CSV出力 | 列名や空値の扱いが変わると業務レポートに影響する |
| 条件分岐 | $null 判定や件数判定が変わると誤処理につながる |
公式ドキュメントでも、移行時の既知の問題として -Filter、-SearchString、出力オブジェクトの差異が挙げられています。(Microsoft Learn)
自動化環境に展開する際の注意点
Azure Automationではモジュール更新を別管理する
ローカルPCでモジュールを更新しても、Azure Automationアカウント内のモジュールは自動的に更新されません。Microsoftのベストプラクティスでも、Azure AutomationでMicrosoft Entra PowerShellを使っている場合は、Automationアカウント側のモジュールも更新するよう案内されています。(Microsoft Learn)
運用では、次の流れで管理すると安全です。
| 手順 | 内容 |
|---|---|
| 検証環境で更新 | 新バージョンを入れて既存Runbookを実行する |
| 影響範囲を確認 | ユーザー、グループ、アプリ、ライセンス処理の結果を比較する |
| 本番へ反映 | 業務影響の少ない時間帯に更新する |
| 旧バージョンを整理 | 不要な古いバージョンを削除する |
| ロールバック手順を残す | 直前の動作バージョンを記録する |
閉域・プロキシ環境ではオフライン導入を検討する
PowerShell Galleryへ直接アクセスできない環境では、オフラインインストールの手順が必要です。公式のオフラインインストールドキュメントでは、インターネット接続が制限された環境、厳格なセキュリティポリシーがある組織、PowerShell Galleryへ直接アクセスできない環境での利用が想定されています。(Microsoft Learn)
オフライン導入では、主に次の作業が必要です。
| 作業 | 内容 |
|---|---|
| 依存関係の準備 | Microsoft Graph PowerShell関連モジュールを準備する |
| ローカルリポジトリ作成 | 社内で利用するPowerShellリポジトリを登録する |
| nupkg配置 | 承認済みのパッケージをローカルリポジトリに配置する |
| モジュール導入 | ローカルリポジトリから Install-Module する |
| 接続テスト | Connect-Entra と Get-EntraContext で確認する |
オフライン環境では、パッケージの入手元、ハッシュ値、承認フロー、保管場所を明確にしてください。特にID管理に関わるモジュールは、単なる便利ツールではなく管理権限を扱う部品として管理する必要があります。
更新とアンインストールの実務ポイント
最新版へ更新する
インストール済みのMicrosoft Entra PowerShellを更新するには、Update-Module を使います。
Update-Module -Name Microsoft.Entra -Force特定サブモジュールだけ更新する場合は、次のように指定します。
Update-Module -Name Microsoft.Entra.Users -ForceBeta版を更新する場合は、次のコマンドです。
Update-Module -Name Microsoft.Entra.Beta -ForceUpdate-Module -Name Microsoft.Entra.Beta.Users -Force公式ドキュメントでは、Update-Module で更新しても古いバージョンはシステムから削除されないと説明されています。更新後に古いバージョンが残ると、実行環境によって読み込まれるバージョンがずれることがあります。(Microsoft Learn)
不要なモジュールを削除する
全バージョンを削除する場合は、次のように実行します。
Uninstall-Module -Name Microsoft.Entra -AllVersions -Force特定サブモジュールを削除する場合は、次のように指定します。
Uninstall-Module -Name Microsoft.Entra.Users -AllVersions -ForceBeta版を削除する場合は、次のコマンドを使います。
Uninstall-Module -Name Microsoft.Entra.Beta -AllVersions -ForceUninstall-Module -Name Microsoft.Entra.Beta.Users -AllVersions -Force削除前には、対象端末や自動化環境でどのスクリプトがそのモジュールを使っているか確認してください。管理端末では問題なくても、Runbookやスケジュールタスクで突然失敗することがあります。
よくあるインストール失敗と対処法
Microsoft Entra PowerShellのインストールで失敗した場合は、エラーメッセージを見て原因を切り分けます。公式ドキュメントでは、古い Install-Module、依存モジュール不足、既存コマンドとの競合、v1.0とBetaの競合などが例として挙げられています。(Microsoft Learn)
| エラー・症状 | 主な原因 | 対処 |
|---|---|---|
AllowPrerelease が見つからない | Install-Module が古い | PowerShellGetを更新する |
| 依存モジュールがない | Microsoft Graph PowerShell関連の依存関係不足 | 依存モジュールを導入する |
| コマンドが既に存在する | 既存モジュールやコマンド名との競合 | -AllowClobber を付けてインストールする |
| v1.0とBetaで競合する | 片方のモジュールが既に入っている | 問題のあるバージョンをアンインストールして整理する |
| 更新後も古い動作になる | 古いバージョンが残っている | Get-InstalledModule で確認し、不要な版を削除する |
| 接続後に権限エラーになる | 必要なGraph権限に同意していない | Connect-Entra -Scopes の指定と管理者同意を確認する |
失敗しやすいのは、インストール自体ではなく「インストールは成功したが、接続後に権限不足で処理できない」ケースです。特にアプリ、条件付きアクセス、ロール、監査ログ、サインインログを扱う場合は、必要な権限を事前に確認してください。
展開前チェックリスト
本番環境へ展開する前に、次の項目を確認してください。
| チェック項目 | 確認コマンド・確認内容 |
|---|---|
| PowerShellバージョン | $PSVersionTable.PSVersion |
| 既存モジュール | Get-Module -Name Microsoft.Entra -ListAvailable |
| インストール済みバージョン | Get-InstalledModule -Name Microsoft.Entra* |
| GA版とBeta版の使い分け | 本番でBetaに依存していないか確認 |
| 必要なスコープ | Connect-Entra -Scopes の指定を確認 |
| 管理者同意 | 付与した権限と承認者を記録 |
| 既存スクリプト移行 | Test-EntraScript で互換性を確認 |
| 自動化環境 | Azure AutomationやCI/CD側にも同じモジュールを展開 |
| 旧バージョン整理 | 更新後に不要な古い版を削除 |
| ロールバック | 直前に動作していたモジュールバージョンを記録 |
このチェックリストを残しておくと、別の管理者が対応するときにも状況を追いやすくなります。Microsoft Entra IDは認証・認可の中核であり、PowerShell操作の失敗がユーザー管理やアプリ管理に直接影響するため、手順の属人化を避けることが重要です。
まず取るべき対応
Microsoft Entra PowerShellをこれから導入する場合は、まず検証端末で Microsoft.Entra を CurrentUser スコープにインストールし、Get-InstalledModule と Connect-Entra で動作確認してください。その後、既存のAzure AD PowerShell／MSOnlineスクリプトがある場合は、Test-EntraScript と互換モードで影響を確認し、長期的にはMicrosoft Entra PowerShellのコマンドレットへ置き換えていくのが安全です。
本番展開では、Beta に依存しない構成、最小権限のスコープ設計、Azure Automationなど自動化環境のモジュール更新、古いバージョンの整理まで含めて計画してください。インストール作業だけで終わらせず、権限・移行・運用更新までを1つの展開手順として管理することが、Microsoft Entra PowerShell導入で失敗しないための最短ルートです。
コメント