Microsoft Graph PowerShell入門 ── AzureAD・MSOnline廃止後のMicrosoft 365運用

Microsoft 365の運用を自動化している現場にとって、2024年から2025年にかけての一番大きな変化はAzureADモジュールとMSOnlineモジュールの廃止でした。「退職者処理」「ライセンス棚卸し」「新入社員のアカウント作成」といった定型処理を Get-MsolUser や Get-AzureADUser で書いていた情シスは少なくないはずで、これらは順次動かなくなります。

移行先は Microsoft Graph PowerShell SDK です。ただし、単なるコマンド名の置き換えではありません。認証の考え方(スコープと同意)、データの取り方(OData のフィルターとページング)、無人実行の作り方(アプリ登録と証明書)まで、設計の前提が変わります。ここを理解せずに機械的に置き換えると、「動くけれど過剰な権限で動いている」「件数が多いテナントで途中までしか取れない」といった別の問題を抱え込みます。

この記事では、社内のMicrosoft 365運用をPowerShellで自動化している情シス担当者を対象に、廃止の経緯の整理、接続とスコープ設計、無人実行の構成、そして棚卸し・ライセンス集計・退職者処理という定番3レシピまでを、実務で使える形にまとめます。

1. まず結論

• MSOnlineとAzureADは2024年3月30日に非推奨となり、MSOnlineは2025年5月30日に提供終了、AzureADも2025年3月30日でサポート終了後に廃止されました。¹
• 移行先はMicrosoft Graph PowerShell SDK、またはその上のMicrosoft Entra PowerShell(2025年3月にGA)です。後者はシナリオ指向で、AzureADからの移行を助ける互換オプションも持ちます。²
• Microsoft.Graph はメタモジュールです。全部入れると重いので、実務では Microsoft.Graph.Authentication + 使うワークロードのサブモジュールだけを入れます。³
• 接続は Connect-MgGraph -Scopes から始めます。スコープは最小権限で。必要な権限は Find-MgGraphPermission、コマンドの所属モジュールは Find-MgGraphCommand で調べられます。⁴⁵
• 無人実行はアプリ登録+証明書によるアプリ専用認証です。-ClientId -TenantId -CertificateThumbprint で対話なしに接続します。クライアントシークレットより証明書を推奨します。⁴⁶
• 委任(Delegated)とアプリ専用(Application)では必要な権限が別物です。同じ操作でも要求するスコープが変わるので、無人実行に切り替える際は権限を付け直す必要があります。⁶
• 一覧取得は -All、絞り込みは -Filter、項目は -Property。クライアント側の Where-Object で絞ると、無駄な取得とスロットリングを招きます。⁷
• 大量アクセスは調整(スロットリング)されます。429応答では Retry-After に従って待つのが公式の指針です。⁸
• アプリ登録は用途ごとに分けます。「全部入りの1アプリ」は権限が肥大化し、事故時の影響範囲も広がります。

2. 廃止の経緯と、いま何を選ぶか

まず事実関係を整理します。¹

どちらを使うかの目安はこうです。Graph APIの構造をそのまま扱いたい・幅広いワークロード(Exchange、Teams、Intuneなど)に触れたいならGraph PowerShell SDK。Entra ID(旧Azure AD)のID管理が中心で、AzureADモジュールからの移行をなるべく楽にしたいならMicrosoft Entra PowerShellです。後者はGraph PowerShell SDKと相互運用でき、AzureADモジュールからの移行を支援する後方互換オプションも提供されています。²

本記事では、汎用性が高くドキュメントも豊富なGraph PowerShell SDKを軸に説明します。

3. インストール ── メタモジュールを丸ごと入れない

Microsoft.Graph は多数のサブモジュールを束ねたメタモジュールです。丸ごと入れるとインストールも読み込みも重く、実行環境によっては読み込みだけで数十秒かかることもあります。³

# 【重い】全ワークロードを入れる
Install-Module Microsoft.Graph -Scope CurrentUser

# 【実務】認証 + 使うワークロードだけを入れる
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser   # 必須
Install-Module Microsoft.Graph.Users          -Scope CurrentUser   # ユーザー
Install-Module Microsoft.Graph.Groups         -Scope CurrentUser   # グループ
Install-Module Microsoft.Graph.Identity.DirectoryManagement -Scope CurrentUser  # ライセンス等
Install-Module Microsoft.Graph.Users.Actions  -Scope CurrentUser   # ユーザーに対する操作
                                                                   # (Revoke-MgUserSignInSession など)

# どのコマンドがどのモジュールにあるか、必要な権限は何かを調べる
Find-MgGraphCommand -Command Get-MgUser | Select-Object Module, Permissions -First 1
Find-MgGraphPermission user.read -PermissionType Delegated

PowerShell 7での利用が推奨されます。Windows PowerShell 5.1でも動作しますが、性能面でも将来性の面でも7を選ぶ理由が大きい領域です(「Windows PowerShell 5.1とPowerShell 7の違い」)。³

4. 接続とスコープ ── 「とりあえずReadWrite.All」をやめる

対話的な接続は Connect-MgGraph -Scopes です。指定したスコープに対して同意画面が出て、同意結果はテナントに記録されます。⁴

# 読み取りだけの棚卸し用途。書き込み権限を要求しない
Connect-MgGraph -Scopes 'User.Read.All', 'Organization.Read.All' -NoWelcome

Get-MgContext | Format-List Account, TenantId, Scopes, AuthType   # 現在の接続を確認
Disconnect-MgGraph

ここが移行時に一番差が出るところです。Get-MsolUser 時代は「管理者アカウントでログインすれば全部できる」でしたが、Graphでは操作ごとに必要なスコープが定義されており、同意した範囲でしか動きません。これは制約ではなく安全装置です。棚卸しスクリプトが誤って書き込みを行う事故は、.Read.All しか同意していなければ起こりません。

原則は3つです。

• 読み取り用途に書き込みスコープを要求しない(User.Read.All で足りるなら User.ReadWrite.All を求めない)
• 用途ごとにアプリ登録を分ける(棚卸し用、アカウント作成用、ライセンス管理用)
• 同意は管理者が意識的に行う(一度与えた同意はテナントに残り続ける)

必要なスコープが分からないときは Find-MgGraphPermission で候補を探し、Find-MgGraphCommand でコマンドが要求する権限を確認します。⁵

5. 無人実行 ── アプリ登録+証明書

タスクスケジューラから毎晩動かすなら、対話ログインは使えません。アプリ登録(サービスプリンシパル)と証明書によるアプリ専用認証に切り替えます。⁶

手順の骨格は次のとおりです。

1. Microsoft Entra管理センターでアプリを登録する
2. アプリケーション許可(Application permissions) を必要最小限だけ追加し、管理者の同意を与える
3. 証明書を作成し、公開鍵をアプリ登録にアップロード、秘密鍵は実行アカウントの証明書ストアに置く
4. スクリプトから -CertificateThumbprint で接続する

# 無人実行用の接続(対話なし)
$connect = @{
    ClientId              = '11111111-2222-3333-4444-555555555555'
    TenantId              = '66666666-7777-8888-9999-000000000000'
    CertificateThumbprint = 'A1B2C3D4E5F6...'    # 実行アカウントのストアにある証明書
    NoWelcome             = $true
}
Connect-MgGraph @connect

try {
    # 業務処理
}
finally {
    Disconnect-MgGraph
}

注意点が2つあります。

(1) 委任とアプリ専用では必要な権限が別物です。対話的に -Scopes 'User.Read.All' で動いていたスクリプトを無人化するときは、アプリ登録側にアプリケーション許可として同じ種類の権限を付け直し、管理者同意が必要です。⁶

(2) 証明書には期限があります。期限切れの当日に夜間バッチが全滅する、というのは実際によくある事故です。有効期限をカレンダーに登録し、更新手順を文書化してください。資格情報の保管については「PowerShellでの資格情報の安全な扱い」もあわせて参照してください。クライアントシークレットでも接続はできますが、平文で持ち回るリスクと期限管理の煩雑さから、証明書を推奨します。

6. データの取り方 ── -All / -Filter / -Property

Graphはページングを前提としたAPIです。既定では1ページ分しか返らないため、全件が必要なら -All を付けます。⁷

# 【NG】ページングを考えず、クライアント側で絞る(遅い・取りすぎ・スロットリングの原因)
Get-MgUser | Where-Object { $_.Department -eq '営業部' }

# 【OK】サーバー側で絞り、必要な項目だけ、全ページを取得する
Get-MgUser -All -Filter "department eq '営業部'" `
           -Property Id, DisplayName, UserPrincipalName, AccountEnabled, Department |
    Select-Object DisplayName, UserPrincipalName, AccountEnabled

ポイントは3つです。

• -Filter はOData式で、サーバー側で絞り込みます。Where-Object はローカルで絞るため、全件取得してから捨てることになります
• -Property で列を絞ると応答が軽くなります。既定では返らないプロパティも、明示すれば返るものがあります
• -Property で取得した項目は Select-Object にも書く。取得と表示は別なので、片方だけだと空欄になります

startsWith や endsWith のような高度なクエリ、あるいは件数だけが欲しい場合は、-ConsistencyLevel eventual と -CountVariable を併用します。⁷

# 有効なユーザー数だけを数える(全件を取得せずカウントを得る)
Get-MgUser -Filter 'accountEnabled eq true' -ConsistencyLevel eventual -CountVariable total -Top 1 | Out-Null
"有効ユーザー: $total 件"

大量アクセスをすると調整(スロットリング) され、HTTP 429が返ります。公式の指針は「Retry-After ヘッダーの秒数に従って待ってから再試行する」ことです。⁸ SDKのコマンドレットはある程度の再試行を内部で行いますが、数千件規模のループを回すときは、そもそも取得回数を減らす(-Filter と -Property で絞る、1回で必要な情報を取る)ほうが確実です。リトライ設計そのものは「PowerShellのエラー処理と再実行設計」を参照してください。

7. 定番レシピ3つ

(1) ユーザー棚卸しをCSVに出す

# SignInActivity(最終サインイン日時)は User.Read.All だけでは取得できず、
# AuditLog.Read.All が別途必要。取らないなら -Property から外すこと
Connect-MgGraph -Scopes 'User.Read.All', 'AuditLog.Read.All' -NoWelcome

$users = Get-MgUser -All -Property Id, DisplayName, UserPrincipalName, AccountEnabled,
                              Department, JobTitle, CreatedDateTime, SignInActivity |
    Select-Object DisplayName, UserPrincipalName, Department, JobTitle, AccountEnabled,
                  @{ n = '作成日'; e = { $_.CreatedDateTime } },
                  # 休眠判定には「成功したサインイン」を使う。LastSignInDateTimeは
                  # 対話サインインの「試行」で、失敗も含み、非対話は含まない
                  @{ n = '最終サインイン成功'; e = { $_.SignInActivity.LastSuccessfulSignInDateTime } },
                  @{ n = '最終対話サインイン試行'; e = { $_.SignInActivity.LastSignInDateTime } },
                  @{ n = '最終非対話サインイン'; e = { $_.SignInActivity.LastNonInteractiveSignInDateTime } }

# 日本語を含むCSVはUTF-8(BOM付き)にするとExcelで開いても化けない。
# エンコーディング名はバージョンで違う: 7以降は utf8BOM、5.1は UTF8(BOM付き)
$enc = if ($PSVersionTable.PSVersion.Major -ge 6) { 'utf8BOM' } else { 'UTF8' }
$users | Export-Csv -Path "D:\棚卸\users_$(Get-Date -f yyyyMMdd).csv" -Encoding $enc -NoTypeInformation

SignInActivity は、休眠アカウントの洗い出しに効きます。ただしどのフィールドを見るかが重要です。LastSignInDateTime は対話サインインの試行(失敗も含む)を記録し、アプリやサービスによる非対話サインインを含みません。これだけで判定すると、攻撃者のログイン失敗で「使われている」ように見えたり、実際に動いているサービスアカウントが「休眠」に見えたりします。休眠判定には、成功した対話・非対話サインインを反映する LastSuccessfulSignInDateTime を使ってください。⁹ただしこのプロパティだけは User.Read.All では取得できず、AuditLog.Read.All が追加で必要です(加えてテナント側のライセンス要件もあります)。権限が足りないとエラーになるか値が空になるので、使わないなら -Property から外してください。必要な権限は Find-MgGraphPermission で確認できます。⁹CSVの文字コードの扱いは「PowerShellでExcel・CSV業務処理を自動化する」にまとめています。

(2) ライセンスの消費状況を集計する

Connect-MgGraph -Scopes 'Organization.Read.All' -NoWelcome

Get-MgSubscribedSku | Select-Object `
    SkuPartNumber,
    @{ n = '購入数';   e = { $_.PrepaidUnits.Enabled } },
    @{ n = '割当済み'; e = { $_.ConsumedUnits } },
    @{ n = '空き';     e = { $_.PrepaidUnits.Enabled - $_.ConsumedUnits } } |
    Sort-Object 空き

「余っているライセンスがあるのに追加購入していた」「退職者のライセンスが解放されていない」は、月次で回すだけで防げます。

(3) 退職者処理(サインインブロックとセッション失効)

# 書き込みを伴うので、専用のアプリ登録・専用スコープで実行する。
# -ClientId を省略するとSDK既定の共有アプリで接続され、同意した権限が
# そのアプリ(組織で共有)に積み上がってしまう。退職者処理のような
# 破壊的な操作こそ、専用のアプリ登録に権限を隔離する
#
# 操作ごとに必要な権限が違うため、両方の操作分をまとめて要求する
#   accountEnabled の変更 → User.EnableDisableAccount.All(最小権限)
#   サインインセッションの失効 → User.RevokeSessions.All(最小権限)
# いずれも User.ReadWrite.All でも実行できるが、権限が広くなる
$connect = @{
    ClientId  = '99999999-aaaa-bbbb-cccc-dddddddddddd'   # 退職者処理専用のアプリ登録
    TenantId  = '66666666-7777-8888-9999-000000000000'
    Scopes    = 'User.Read.All', 'User.EnableDisableAccount.All', 'User.RevokeSessions.All'
    NoWelcome = $true
}
Connect-MgGraph @connect

# Revoke-MgUserSignInSession は Microsoft.Graph.Users.Actions が必要
Import-Module Microsoft.Graph.Users.Actions

$upn = 'taro.yamada@example.co.jp'
$user = Get-MgUser -UserId $upn -Property Id, DisplayName, AccountEnabled

# 1. サインインをブロック(削除は猶予期間を置いてから)
Update-MgUser -UserId $user.Id -AccountEnabled:$false

# 2. 更新トークンとブラウザーのセッションCookieを失効させる
#    注意: 発行済みのアクセストークンは有効期限まで使える場合がある(後述)
Revoke-MgUserSignInSession -UserId $user.Id

Write-Host "$($user.DisplayName) のサインインを停止しました"

ここで押さえるべき点が3つあります。ひとつは接続先のアプリ登録です。-ClientId を省略するとMicrosoft Graph PowerShell SDKの既定アプリで接続され、同意した権限は組織で共有されるそのアプリに記録されます。「用途ごとにアプリ登録を分ける」という4章の原則を実現するには、-ClientId で自社のアプリ登録を明示する必要があります。⁴

もうひとつはスコープです。Graphでは操作ごとに必要な権限が定義されており、「ユーザーを書き込めるから何でもできる」わけではありません。accountEnabled の変更とサインインセッションの失効はそれぞれ専用の最小権限を持つため、片方だけ同意して実行すると、接続には成功しても途中のコマンドで権限不足エラーになります。各操作に必要な権限は Find-MgGraphPermission と、対応するGraph APIリファレンスの権限表で確認してください。¹⁰¹¹

そして3つ目に、委任実行ではスコープだけでは足りません。上のように利用者本人としてサインインして実行する場合、accountEnabled の変更にはMicrosoft Entraの管理者ロールも必要です。委任の権限は「アプリがそのユーザーの代わりに何をできるか」を決めるだけで、サインインしたユーザー自身の権限を引き上げはしないためです。権限に同意していてもロールがなければ、実行時に403で失敗します。ドキュメントは、テナント内のすべての管理者に対してこのプロパティを更新できる最小のロールを Privileged Authentication Administrator とし、一般には「対象より上位の管理者ロールが必要」と定めています。¹⁰ 退職者処理の対象が一般利用者か管理者かで必要なロールが変わるため、運用担当のアカウントに何を割り当てるかは事前に決めておいてください。証明書によるアプリ専用実行でも、対象が管理者の場合はアプリ自体への上位ロールの割り当てが必要です。¹⁰

Revoke-MgUserSignInSession の効果範囲も正確に理解しておく必要があります。このコマンドが無効化するのは更新トークンとブラウザーのセッションCookieであり、すでに発行済みのアクセストークンは、その有効期限が切れるまで使える場合があります。¹¹ 即時遮断を求めるなら、継続的アクセス評価(CAE)に対応したアプリケーション・リソースであることが前提になります。「revokeしたから即座に全アクセスが止まる」と考えず、重要なケースではアカウント無効化と併用し、反映までの時間差を織り込んでください。

アカウントの即時削除は避け、まずサインインを止めるのが実務の定石です。メールボックスやOneDriveの引き継ぎが終わる前に削除すると復旧に手間がかかります。この種の「取り返しがつかない操作」は、-WhatIf に対応した自作関数でラップし、対象一覧を先に出力して確認してから実行する形にしておくと安全です(「PowerShellの引数設計とモジュール化」)。

8. 実務の定石(判断表)

9. まとめ

• MSOnlineとAzureADは廃止済みです。移行先はMicrosoft Graph PowerShell SDK、またはその上のMicrosoft Entra PowerShellです。
• Microsoft.Graph はメタモジュールなので、実務では認証+使うワークロードのサブモジュールだけを入れます。
• 接続はスコープの最小化が原則です。棚卸し用途に書き込み権限を要求せず、用途ごとにアプリ登録を分けます。
• 無人実行はアプリ登録+証明書。委任とアプリ専用では必要な権限が別物である点、証明書に期限がある点が事故の元です。
• データ取得は -All(ページング)、-Filter(サーバー側の絞り込み)、-Property(項目の限定)の3点セット。429は Retry-After に従います。
• 棚卸し・ライセンス集計・退職者処理の3つを月次で回すだけでも、ライセンスの無駄と放置アカウントというよくある2大リスクは大きく減らせます。

サンプルコードのダウンロード

この記事で扱ったコードは、そのまま動かせる形にまとめて配布しています。接続・休眠アカウント抽出・ライセンス集計・退職者処理が入っています。

サンプルコードをダウンロード(zip)

この記事のサンプルは、Windowsやテナントに依存するため実行検証はしていません。構文解析とPSScriptAnalyzerによる静的解析までは全ファイルに対して実施していますが、動作は必ずご自身の検証機で確認してください。

# 構文解析 + 静的解析(Windows以外でも実行できる)
./Invoke-SampleTests.ps1

設定値(パス、サーバー名、テナントIDなど)は例です。そのまま本番環境で実行せず、自社の環境に合わせて読み替えてください。

関連記事

• PowerShellでの資格情報の安全な扱い ── 平文パスワードをスクリプトから追放する
• Windows PowerShell 5.1とPowerShell 7の違い ── 社内スクリプト移行の実務ガイド
• PowerShellでExcel・CSV業務処理を自動化する ── 集計・突合・帳票出力の実務レシピ
• PowerShellのエラー処理と再実行設計 ── try/catchが効かない罠からexit code・リトライの定石まで
• WinForms / WPFアプリにMicrosoft Entra IDのログインを組み込む
• タスクスケジューラのタスクが実行されない・0x1で終わる ── 原因の切り分けと安全な運用設計

関連する相談領域

合同会社小村ソフトでは、Microsoft 365運用スクリプトのGraph移行、アプリ登録と権限設計のレビュー、棚卸し・退職者処理といった定型業務の自動化を扱っています。

• 技術相談・設計レビュー
• 既存資産の移行・活用
• 業務システム開発
• お問い合わせ

参考リンク

関連する記事

同じタグを共有する最新の記事です。さらに近い話題で知識を深められます。

関連トピック

このテーマと近いトピックページです。記事を起点に、関連するサービスや他の記事へ進めます。

よくある質問

この記事のテーマについて、相談時によくある質問をまとめています。

AzureADモジュールやMSOnlineモジュールは、もう使えないのですか？

はい、いずれも廃止済みです。MSOnlineとAzureADの両モジュールは2024年3月30日に非推奨(deprecated)となり、MSOnlineは2025年5月30日をもって提供終了、AzureADも2025年3月30日でサポートが終了し、その後に廃止されました。まだ動いているように見えるスクリプトがあっても、それはいつ止まってもおかしくない状態です。移行先はMicrosoft Graph PowerShell SDK、またはその上に構築されたMicrosoft Entra PowerShellモジュール(2025年3月にGA)です。

Microsoft.Graphモジュールをインストールすると重いのですが、軽くできますか？

できます。Microsoft.Graphはメタモジュールで、配下に多数のサブモジュールを持つため、全体を入れるとインストールにも読み込みにも時間がかかります。実務では、使うワークロードのサブモジュールだけを入れるのが現実的です。ユーザー管理ならMicrosoft.Graph.Users、グループならMicrosoft.Graph.Groups、認証は必須のMicrosoft.Graph.Authentication、といった具合です。どのコマンドがどのモジュールに属するかはFind-MgGraphCommandで調べられます。

タスクスケジューラから無人実行したいのですが、対話ログインが出てしまいます。

アプリ登録(サービスプリンシパル)と証明書によるアプリ専用認証に切り替えてください。Microsoft Entra IDでアプリを登録し、必要なアプリケーション許可(Application permissions)に管理者の同意を与えたうえで、Connect-MgGraphに-ClientId・-TenantId・-CertificateThumbprintを渡すと、対話なしで接続できます。クライアントシークレットより証明書のほうが安全で、有効期限管理も明確です。証明書は実行アカウントの証明書ストアに置き、期限切れ前に更新する運用を必ず決めてください。

Connect-MgGraphの-Scopesには何を指定すればよいですか？

実行したいコマンドが要求する最小の権限だけを指定します。何が必要かはFind-MgGraphPermissionやコマンドのドキュメントで確認でき、読み取りだけならUser.Read.Allのように.Read.系で足ります。棚卸しや監査が目的なら書き込み権限を要求しないでください。一度同意した権限はテナントに記録されるため、「とりあえずDirectory.ReadWrite.Allで同意」は将来のリスクになります。用途ごとにアプリ登録を分け、権限も分けるのが安全です。

Get-MgUserで件数の多いテナントを扱うと、途中までしか取れません。

Microsoft Graphの応答はページングされるためです。-Allを付けると全ページを自動的にたどって取得します。加えて、大量取得では調整(スロットリング)を受けて429応答が返ることがあるので、必要な項目だけを-Propertyで絞り、フィルターはクライアント側のWhere-ObjectではなくOData(-Filter)でサーバー側に押し付けるのが基本です。件数だけが欲しい場合は、-ConsistencyLevel eventualと-CountVariableの組み合わせでカウントだけ取得できます。

著者プロフィール

記事の著者プロフィールページです。

小村 豪

合同会社小村ソフト 代表

Windows ソフト開発、技術相談、不具合調査を中心に、既存資産が残る案件や原因が見えにくい障害調査に強みがあります。