Entra IDのアプリをMicrosoft GraphとMSALへ移行する手順｜Azure AD Graph廃止後の実装

Microsoft Entra ID（旧Azure AD）を相手にするアプリのうち、graph.windows.net を叩いているものと、ADAL（Azure Active Directory Authentication Library）でトークンを取っているものは、どちらもすでに提供終了の期限を過ぎています。Azure AD Graph は2025年8月31日に拡張アクセスが終了して完全廃止、ADAL はセキュリティ修正を含むサポートが2023年6月30日に終了しました。それでも動いているアプリは社内に残ります。夜間バッチや退職者の棚卸しのように、誰も触っていないコードほど旧APIを掴んだままです。この記事では、そうしたアプリを探し出し、エンドポイントとアクセス許可を読み替え、MSAL と Microsoft Graph へ書き換えるまでを、実行できるコマンドつきで並べます。Entra ID の定義や料金プランはMicrosoft Entra ID（旧Azure AD）とは？読み方・Azure AD/Active Directoryとの違い・機能・料金で扱っているため、本記事は移行作業だけに絞ります。

まとめ：Entra IDのアプリをMicrosoft Graphへ移す判断

• 期限はすべて経過済み。Azure AD Graph は2025年8月31日で完全廃止、ADAL は2023年6月30日でサポート終了。今から取る手は「間に合わせる計画」ではなく「壊れた分の復旧と残りの棚卸し」です。
• 探し方は3系統を併用する。Entra管理センターの推奨事項（aadGraphDeprecationApplication と aadGraphDeprecationServicePrincipal）、サインインブック、リポジトリ全文検索。どれか1つでは漏れます。
• 書き換えの大半はエンドポイントとアクセス許可の読み替えで済む。公式も「多くの場合、エンドポイント、バージョン、リソース名を更新するだけで期待どおりに機能する」としています。工数が膨らむのはプロパティ名と応答形式の差、マニフェスト属性の再配置でした。
• 他社製アプリは自社では直せない。サービスプリンシパル側に出たものは別テナント登録のアプリで、ベンダーへ更新版を要求する交渉が実作業になります。自社のコード修正と同じ列で管理すると期日が崩れがちです。
• AD FS 2016以前が残るとMSAL移行は進まない。MSAL がトークンを取得できるのは AD FS 2019 以降で、基盤側の更新が前提工程になります。

Azure AD GraphとADALの廃止日を確認して期限超過を把握する

まず、期限をどれだけ超過しているかを日付で確定させます。「そのうち止まる」ではなく「すでに保証の外」という前提へ切り替えないと優先順位が付きません。

Azure AD Graphが完全廃止された日付と拡張アクセスの終了時期

Microsoft Learn のAzure AD Graph から Microsoft Graph に移行するには、廃止のタイムラインが日付で並んでいます。2019年に非推奨が告知され、廃止予定は2023年6月30日。同日に3年間の通知期間が終わり、廃止サイクルに入りました。2024年8月31日以降に作成された新しいアプリは拡張アクセスを明示的にオプトインしない限り使えなくなり、2025年2月1日からは既存アプリを含む全アプリにオプトインが必須とされました。そして2025年8月31日、拡張アクセスの終了とともに完全に廃止されています。

同ページには「Azure AD Graph API には、セキュリティ関連の修正プログラムを超える SLA またはメンテナンスコミットメントがありません」と明記されており、延命の交渉余地はありません。オプトインのフラグ自体は authenticationBehaviors リソースとして Microsoft Graph 側に定義が残っています（authenticationBehaviors リソースの種類）。

ADALのサポートが終了した日と、今も動いているアプリが抱えるリスク

MSAL への移行によれば、ADAL に対する Microsoft のサポートと開発は、セキュリティ修正プログラムを含めて2023年6月30日に終了しました。新機能の追加は2020年6月30日で止まっています。同ページの警告は「ADAL を使用している既存のアプリは引き続き機能しますが、Microsoft は今後 ADAL のセキュリティ修正プログラムをリリースしません」という書き方で、動作の停止ではなく脆弱性の放置がリスクだと示しています。

機能面の差も無視できません。MSAL には継続的アクセス評価（CAE）への対応があり、ポリシー変更に応じてトークンを事前更新・取り消しできます。ADAL は Microsoft アカウント（MSA）、Azure AD B2C アカウント、認証ブローカー、トークン保護のいずれにも対応しません。条件付きアクセスを強めるほど、ADAL を残した箇所だけ制御が効かなくなります。

テナント内でAzure AD GraphとADALを呼ぶアプリを洗い出す

期限の話より先に手を動かすべきは対象の特定です。テナント側の記録とコード側の記述、両方から挟み込みます。

Entra管理センターの推奨事項からアプリとサービスプリンシパルを一覧する

Entra ID には Azure AD Graph 廃止専用の推奨事項が2つあります。Microsoft Graph API への移行に関する推奨事項によると、recommendations API 上の名前は aadGraphDeprecationApplication と aadGraphDeprecationServicePrincipal。前者は自テナント登録で Azure AD Graph を呼ぶアプリ（アプリの登録）、後者は他テナント登録で自テナントが同意しているアプリ（エンタープライズアプリケーション）を並べます。

「影響を受けたリソース」から詳細リンクを開くと、操作名（アプリケーションの一覧表示、ユーザーの作成、グループの削除など）、直近30日間の要求数、最後の要求日時が出ます。要求数が多く最終要求日が直近のものから潰せば、影響の大きい順に片付きます。閲覧はレポートビューワー、セキュリティリーダー、グローバルリーダーのいずれかで足り、API経由なら DirectoryRecommendations.Read.All です。

この推奨事項は、Azure AD Graph の呼び出しが30日間途絶えると自動で「完了」に変わります。移行の成否を申告ではなくテナントの実測で判定できるため、進捗管理の指標に使えます。

サインインブックでADALのバージョンとサインイン回数を突き合わせる

ADAL 側は別の経路で調べます。テナントで ADAL を使用しているすべてのアプリの一覧を取得するの手順では、まず Entra ID のサインインイベントを Azure Monitor へ送る設定が要ります。診断設定で SignInLogs を有効にしていない場合、設定より前のサインインはブックに出てきません。ここを飛ばして「該当なし」と判断する事故が起きやすい箇所でした。

設定後、Entra管理センターで Entra ID の Monitoring & health から Workbooks を開き、使用法セクションのサインインブックを表示します。ページ下部のテーブルに過去30日間にアクティブだった ADAL アプリが並び、エクスポートも可能です。列はアプリケーションID、表示名、SigninCount、ADALバージョン、IPアドレス、場所、デバイスのOS。公式は SigninCount が多くバージョンが古いものを優先せよと明記しています。

ソースコードとIaCからgraph.windows.netを機械的に検索する

テナント側のログは、直近に動いたものしか映しません。年次でしか回らないバッチや障害時にだけ叩くスクリプトは漏れるため、リポジトリ全体を文字列で検索して拾い切ります。

# 旧エンドポイントと旧ライブラリの痕跡をまとめて検索する
rg -n --hidden -g '!.git' \
  -e 'graph\.windows\.net' \
  -e 'AuthenticationContext' \
  -e 'Microsoft\.IdentityModel\.Clients\.ActiveDirectory' \
  -e 'adal-node' \
  -e 'adal\.js' \
  -e 'Connect-AzureAD' \
  -e 'Connect-MsolService' \
  .

検索対象はアプリのコードだけではありません。ARM／Bicep テンプレート、Terraform、CI の定義、タスクスケジューラから呼ばれる .ps1、Excel の VBA まで含めます。Azure AD Graph API アプリの使用状況を調べるの観点と突き合わせ、ログのアプリIDとコード側のヒットが1対1で結び付いたら棚卸しは完了です。

エンドポイントとアクセス許可をMicrosoft Graphへ読み替える

対象が確定したら書き換えに入ります。移行チェックリストは、APIの違いを確認し、使用中のAPIを調べ、アプリの登録と認証ライブラリを見直し、デプロイしてテストする4段構えです。

リクエストURLとバージョン表記を書き換えて最初に直す差分箇所

公式が「多くの場合、コード内のエンドポイント、バージョン、およびリソース名を更新するだけで、期待どおりに機能する」と書いているとおり、最初の一手は文字列の置換になります。Azure AD Graph はテナント識別子をパスに含めてバージョンをクエリ文字列で渡していましたが、Microsoft Graph はバージョンをパスに持ち、テナントはトークン側で解決します。

# 旧：Azure AD Graph（2025年8月31日に完全廃止）
GET https://graph.windows.net/{tenantId}/users?api-version=1.6

# 新：Microsoft Graph v1.0
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName

# トークン取得側の指定も書き換える
# 旧：resource=https://graph.windows.net
# 新：scope=https://graph.microsoft.com/.default

応答の形も変わります。ユーザーを一覧表示するのとおり Microsoft Graph は既定で返すプロパティを絞るため、旧実装で参照していたフィールドが黙って欠落します。$select での明示が移行時の安全側です。

Azure AD Graphのアクセス許可をMicrosoft Graphへ対応付ける

アクセス許可は名前が一致しません。Azure AD Graph と Microsoft Graph のアクセス許可の違いとアクセス許可のリファレンスを突き合わせ、旧アプリが持っていた requiredResourceAccess を新しいリソースIDとスコープIDへ置き換えます。

ここで効くのが最小権限への絞り込みです。旧アプリは Directory.Read.All のような広い許可を取っている例が多く、そのまま移すと不要な範囲まで読める管理同意を与えてしまいます。実際に呼ぶ操作から逆算して User.Read.All や Group.Read.All の単位まで落としましょう。権限設計の考え方はIDaaSとは？SSO・IdPとの違いとSAML・OIDC・SCIM連携で整理しています。

アプリマニフェスト属性の再配置と改名で書き換えが必要になる箇所

アプリの登録側も形式が変わりました。アプリ マニフェスト（Azure AD Graph 形式）の廃止によると、2024年6月13日から9月16日にかけて両形式を扱えるタブ付き画面が提供され、2025年1月7日以降は Entra管理センターのマニフェストページで Azure AD Graph 形式の表示・保存・アップロード・ダウンロードができません。旧形式のマニフェストJSONを保管している場合、そのままでは投入できない状態です。

手元のマニフェストは属性で判別でき、replyUrlsWithType があれば Azure AD Graph 形式、implicitGrantSettings があれば Microsoft Graph 形式です。影響が大きい変更を挙げます。

• name は displayName へ改名
• allowPublicClient は isFallbackPublicClient へ改名
• replyUrlsWithType は web、spa、publicClient それぞれの redirectUris へ分割
• oauth2Permissions は api 配下の oauth2PermissionScopes へ移動
• accessTokenAcceptedVersion は api 配下の requestedAccessTokenVersion へ移動
• oauth2AllowImplicitFlow は web の implicitGrantSettings 配下へ移動
• errorUrl は非推奨のため破棄

なお個人用の Microsoft アカウントに登録されたアプリはこの廃止の対象外で、追って通知があるまで旧形式の管理が続きます。

ADALからMSALへ書き換えるコードと疎通確認のコマンド手順

エンドポイントを直しても、トークンを取る層が ADAL のままなら移行は終わりません。アプリ認証ライブラリの変更を確認するが示すとおり、リソースURLの差し替えとライブラリの入れ替えは2段階に分けられます。先にエンドポイントを Microsoft Graph へ向け、動作を確認してから MSAL に移すと切り分けが楽です。

クライアント資格情報フローでトークンを取得するPythonの実装

デーモンやバッチはクライアント資格情報フローを使います。MSAL for Python の最小構成は次のとおりで、ADAL 版の AuthenticationContext.acquire_token_with_client_credentials() に相当します。

import msal
import requests

TENANT_ID = "<tenant-id>"
CLIENT_ID = "<application-client-id>"
CLIENT_SECRET = "<client-secret>"

app = msal.ConfidentialClientApplication(
    client_id=CLIENT_ID,
    client_credential=CLIENT_SECRET,
    authority=f"https://login.microsoftonline.com/{TENANT_ID}",
)

# 旧ADALのresource指定ではなく、.defaultスコープで要求する
result = app.acquire_token_for_client(
    scopes=["https://graph.microsoft.com/.default"]
)
if "access_token" not in result:
    raise SystemExit(result.get("error_description", result))

res = requests.get(
    "https://graph.microsoft.com/v1.0/users"
    "?$select=id,displayName,userPrincipalName&$top=5",
    headers={"Authorization": "Bearer " + result["access_token"]},
    timeout=30,
)
print(res.status_code)
for u in res.json().get("value", []):
    print(u["id"], u["displayName"], u["userPrincipalName"])

差分の要点は3つです。リソースの指定が resource から .default 付きスコープへ変わること、トークンキャッシュが MSAL 側で管理されるため自前実装を捨てられること、失敗時に error_description が返るので同意漏れとシークレット期限切れを切り分けられること。詳細は ADAL から MSAL への移行ガイド（Python）にあります。対話型アプリなら、フロー設計を認可コードフローとは？認可リクエストからトークン交換までの実装手順で確認してから着手すると手戻りが減るでしょう。

curlでトークンとユーザー一覧を取得して疎通を確かめる手順

アプリを書き換える前に、アプリの登録と管理同意が正しいかをコマンドだけで確認します。ここが通らないうちにコードを直すと、原因の切り分けができません。

TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
CLIENT_SECRET='********'

TOKEN=$(curl -s -X POST \
  "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=https://graph.microsoft.com/.default" \
  -d "grant_type=client_credentials" | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://graph.microsoft.com/v1.0/users?\$top=3" | jq '.value[].userPrincipalName'

403 が返る場合はアプリケーションのアクセス許可に管理同意が付いていません。401 ならシークレットか証明書の期限、あるいはテナントIDの指定を疑います。旧アプリのシークレットは期限が切れている例が多く、最初に確認しておくと早いでしょう。

Azure AD PowerShellのスクリプトをMgコマンドレットへ書き換える

運用スクリプトの移行も同じ期限に含まれます。Azure AD PowerShell から Microsoft Graph PowerShell への移行では、AzureAD、AzureAD Preview、MSOnline の3モジュールが非推奨と明記されています。命名規則は単純で、AzureAD や AzureADMS の代わりに Mg を使い、Get-AzureADUser の相当は Get-MgUser です。

Install-Module Microsoft.Graph -Scope CurrentUser

# 旧: Connect-AzureAD、Connect-MsolService
Connect-MgGraph -Scopes 'User.Read.All'

# 旧: Get-AzureADUser でのあいまい検索に相当する書き方
Get-MgUser -ConsistencyLevel eventual -Count userCount `
  -Filter "startsWith(DisplayName, 'a')" -Top 1

# そのコマンドレットに必要なアクセス許可と呼び出し先APIを調べる
Find-MgGraphCommand -Command Get-MgUser |
  Select-Object -ExpandProperty Permissions

置換で済まない差分もあります。Microsoft Graph PowerShell のアクセス許可は事前承認されていないため、必要な権限を都度要求する設計になりました。あいまい検索のパラメーターは名前が変わり、-ConsistencyLevel eventual との併用か -Filter での置き換えが要ります。入れ子のパラメーターはハッシュテーブルで渡します。出力オブジェクトの構造も変わるため、パイプ先でプロパティ名を直に参照するスクリプトは Get-Member で形を確かめてから直しましょう。

移行作業で詰まりやすい箇所と本番切り替え前に検証する項目一覧

置換より前提条件と検証で時間を取られます。着手前に潰す順に挙げます。

AD FS 2016以前が残っている場合に先へ進めなくなる前提条件

MSAL.NET、MSAL Java、MSAL.js、MSAL Python がトークンを取得できるのは AD FS 2019 以降で、AD FS 2016 を含む以前のバージョンは対象外です。フェデレーション構成を維持したまま MSAL へ移るなら、AD FS の更新がアプリ改修より前に来ます。見落とすと、コード修正を終えてから基盤側の停止調整をやり直す羽目になるでしょう。信頼設計はフェデレーション認証とは？IdPとSPの信頼設計と属性連携で扱っています。

プロパティ名と応答形式の違いで静かに壊れる箇所の見つけ方と対策

移行チェックリストは、リクエスト構文、機能（ディレクトリ拡張、バッチ処理、差分クエリ）、リソース名、プロパティ、メソッド、アクセス許可の6領域で差分を探すよう指示しています。厄介なのは例外を出さずに壊れる型で、既定で返らなくなったプロパティが None のまま後段へ流れ、集計だけが狂います。

対策は2つです。1つは $select で必要なプロパティを列挙し、欠けたら落ちるように検証を入れること。もう1つは Graph エクスプローラーでテストユーザーとしてサインインし、実応答を見てから実装することで、公式もテストテナントの資格情報を使うよう推奨しています。

移行の完了を推奨事項とサインインブックで確認するための判定条件

「直したつもり」を排除する判定条件を先に決めます。テナント側の指標は明確で、Azure AD Graph のアクティビティが30日間なければ推奨事項が「完了」に変わります。ADAL 側はサインインブックの一覧から対象アプリが消えることが条件です。どちらも30日の観測窓があるため、切り替え当日ではなく1か月後に確認する運用を組みましょう。

切り替え前の検証には、同じ入力で旧実装と新実装を並走させ、返るユーザー数とプロパティの値が一致するかを突き合わせる方法が有効です。読み取り系から先に切り替え、書き込み系を後に回すと、差分が出たときの巻き戻しが軽くなりました。

移行を先送りした場合の損失と自社実装か外部委託かを分ける条件

ここは判断を言い切ります。Azure AD Graph と ADAL の移行は、コストを比較して決める投資ではありません。期限が過ぎた以上、残っている分は「未完了の障害対応」です。それでも着手順と体制は選べます。

自社で進めてよい条件は、対象が自テナント登録のアプリで、コードが手元にあり、呼ぶ操作がユーザーとグループの読み取り中心で、AD FS が絡んでいない場合です。この範囲なら、エンドポイントの置換とMSALへの差し替え、スコープの取り直しで完結します。

外部に出すべき条件は次のいずれかです。サービスプリンシパル側の推奨事項に他社製アプリが並び、ベンダー交渉と更新版の検証が主作業になる場合。差分クエリやディレクトリ拡張、バッチ処理を使っており単純な置換では等価にならない場合。AD FS 2016以前が残り、基盤更新とアプリ改修の停止計画を同時に引く必要がある場合。旧アプリが広い管理同意を持ち、権限設計をやり直す判断が要る場合です。

見送ってよい場面もあります。対象アプリが年内に廃止予定で代替への移行が確定しているなら、旧アプリの連携を止めて代替側で新規に実装するほうが総工数は減ります。分かれ目は「移行後も2年以上使われるか」でした。

外部に出すなら、依頼の単位は「Entra IDの移行」ではなく「Microsoft Graph API連携の再実装」で切ると見積もりが具体になります。当社ではMicrosoft 365・Copilot導入支援の一環として、Microsoft Graph連携の実装と廃止APIからの切り替えを請けています。推奨事項の一覧とエクスポートを渡せる状態まで用意しておくと、初回の見積もり精度が上がるはずです。

よくある質問（Entra IDのGraph移行とMSAL対応）

Azure AD Graphは今も呼び出せますか？

公式のタイムラインでは2025年8月31日に拡張アクセスが終了し、Azure AD Graph は完全に廃止されています。通るかどうかにかかわらず、SLAとメンテナンスの対象外です。

ADALのまま動いているアプリは、すぐ止まりますか？

ドキュメントは「既存のアプリは引き続き機能します」としており、即時停止ではありません。ただしセキュリティ修正が出ないため、脆弱性が見つかっても修正版はありません。継続的アクセス評価やトークン保護も使えないままです。

移行対象のアプリを一覧する一番早い方法は何ですか？

Entra管理センターの推奨事項です。aadGraphDeprecationApplication と aadGraphDeprecationServicePrincipal を開けば、アプリの登録とエンタープライズアプリケーションが直近30日の要求数つきで並びます。ADAL 側は診断設定で SignInLogs を有効化したうえでサインインブックを使います。

Azure AD PowerShellのスクリプトはそのまま動きますか？

動きません。AzureAD、AzureAD Preview、MSOnline は非推奨で、コマンドレット名が Mg 接頭辞へ変わります。パラメーター、フィルター構文、出力オブジェクトの構造も変わるため、Find-MgGraphCommand で必要なアクセス許可と呼び出し先APIを確認しながら進めましょう。

AD FS 2016の環境でMSALへ移行できますか？

できません。MSAL がトークンを取得できるのは AD FS 2019 以降です。AD FS を使い続けるなら、アプリを MSAL へ更新する前に AD FS 2019 以降へアップグレードする必要があります。

関連記事

• Microsoft Entra ID（旧Azure AD）とは？読み方・Azure AD/Active Directoryとの違い・機能・料金を解説
• シングルサインオン（SSO）とは？4つの実現方式とIDトークン検証・IdP選定を実装手順で解説
• IDaaSとは？SSO・IdPとの違いとSAML・OIDC・SCIM連携を実装視点で解説
• 認可コードフローとは？認可リクエストからトークン交換までの実装手順と検証設計を解説
• GitHub SSOの設定手順｜SAML連携・PAT/SSH認可の落とし穴