Azure DevOps REST APIのOAuth 2.0認証は何が変わる?Entra ID移行の確認ポイント

Azure DevOps REST API の認証をこれから実装・見直しするなら、結論は明確です。新規アプリは Azure DevOps OAuth ではなく、Microsoft Entra ID OAuth を前提に設計するべきです。Microsoft Learn では、Azure DevOps OAuth 2.0 は非推奨で新規登録を受け付けておらず、既存アプリも 2026 年中の廃止に備えて Microsoft Entra ID OAuth へ移行する必要があると案内されています。(Microsoft Learn)

この記事では、Azure DevOps REST API の OAuth 2.0 認証について、何が変わるのか、どのアプリが影響を受けるのか、管理者・開発者が確認すべき設定、移行時に失敗しやすいポイントを実務目線で整理します。ここで扱う「Azure REST API」は、特に Azure DevOps Services の REST API を指します。Azure DevOps Server などオンプレミス環境では、OAuth 2.0 と Microsoft Entra ID 認証は対象外で、.NET クライアントライブラリ、Windows 認証、個人用アクセス トークンなどを使う前提です。(Microsoft Learn)

目次

Azure DevOps REST API の OAuth 2.0 認証で何が変わるのか

今回のポイントは、単なる認証手順の更新ではありません。Azure DevOps REST API を外部アプリや自動化処理から呼び出す際の認証方式が、Azure DevOps 独自の OAuth から Microsoft Entra ID ベースの OAuth へ移行していく流れになっています。

公式情報で押さえるべき変更点は次のとおりです。

項目これまで今後の推奨
新規アプリの認証方式Azure DevOps OAuth を選ぶケースがあったMicrosoft Entra ID OAuth を使用
Azure DevOps OAuth の新規登録以前は可能2025年4月以降、新規登録は受け付け停止
既存の Azure DevOps OAuth アプリ当面は利用可能2026年の廃止に備えて移行が必要
エンタープライズ制御Azure DevOps OAuth 側の制約が中心条件付きアクセス、多要素認証、Entra ID 管理と連携
対象サービスAzure DevOps ServicesAzure DevOps Services。Azure DevOps Server は対象外

Microsoft Learn の「Microsoft Entra OAuth アプリと Azure DevOps の統合」関連ドキュメントは 2026年5月8日に更新されており、Azure DevOps のリソース識別子、リソース URI、.default スコープ、MSA ユーザー対応の注意点など、移行時に確認すべき実装情報が整理されています。(Microsoft Learn)

影響を受ける対象者

影響を受けるのは、Azure DevOps REST API を使っている開発者だけではありません。Azure DevOps 組織の管理者、セキュリティ担当、CI/CD の運用担当、社内ツールの保守担当も確認が必要です。

新規に Azure DevOps REST API 連携を作る開発者

これから Web アプリ、社内ポータル、SaaS 連携、CLI ツールなどを作る場合、旧来の Azure DevOps OAuth を選ぶべきではありません。新規アプリでは Microsoft Entra ID OAuth を使う方針が示されています。(Microsoft Learn)

特に、ユーザーがサインインして自分の Azure DevOps リソースを操作するアプリでは、Microsoft Entra ID の委任フローを検討します。一方、ユーザー操作なしで動くバックグラウンド処理では、サービス プリンシパルやマネージド ID が候補になります。

既存の Azure DevOps OAuth アプリを運用しているチーム

既存の Azure DevOps OAuth アプリは、廃止までの間は動作する可能性があります。ただし、Microsoft は 2026年の削除予定を明記しており、移行計画、テスト、関係者への周知、切り替え作業を早めに進める必要があります。(Microsoft Learn)

既存アプリでは、以下を必ず洗い出してください。

  • どのアプリが Azure DevOps OAuth を使っているか
  • どのスコープを要求しているか
  • どのコールバック URL を登録しているか
  • refresh token をどこに保存しているか
  • シークレットの期限・ローテーション運用があるか
  • ユーザー ID や組織情報をトークンの中身から読んでいないか

個人用アクセス トークンを使っているスクリプト運用者

PAT を使った PowerShell、curl、社内バッチは、今回の OAuth 廃止と同じものではありません。ただし、Microsoft の認証ガイダンスでは、PAT は個人用スクリプトや一時的な用途に限定し、本番アプリケーションでは Microsoft Entra ID 認証を使うことが推奨されています。(Microsoft Learn)

「OAuth の話だから PAT は関係ない」と見落とすのは危険です。長期運用する API 連携や CI/CD では、PAT 依存もあわせて見直すと、セキュリティと保守性を同時に改善できます。

Azure DevOps Server を使っている組織

Azure DevOps Server はオンプレミス製品であり、今回の Microsoft Entra ID OAuth 推奨の対象とは分けて考える必要があります。公式ドキュメントでも、OAuth 2.0 と Microsoft Entra ID 認証は Azure DevOps Services 向けであり、オンプレミスでは .NET クライアントライブラリ、Windows 認証、PAT などを使用すると説明されています。(Microsoft Learn)

Microsoft Entra ID OAuth が推奨される理由

Microsoft Entra ID OAuth が推奨される理由は、単に「新しいから」ではありません。企業の ID 管理、セキュリティポリシー、監査、条件付きアクセスと連携しやすくなるためです。

Microsoft Learn では、Microsoft Entra ID OAuth の利点として、Microsoft Entra ID インフラとの統合、条件付きアクセス、多要素認証、Microsoft サービス全体でのシングルサインオン、将来的なサポートを挙げています。(Microsoft Learn)

実務上のメリットは次のように整理できます。

観点Microsoft Entra ID OAuth を使うメリット
セキュリティ条件付きアクセス、多要素認証、短命トークンなどを組織ポリシーと連携しやすい
運用アプリ登録、同意、アクセス制御を Microsoft Entra 管理センター側で統制しやすい
開発MSAL などの認証ライブラリを利用しやすい
監査企業 ID として認証・アクセスを追跡しやすい
将来性Azure DevOps OAuth 廃止後も継続利用しやすい

ただし、Microsoft Entra ID OAuth に移れば自動的にすべて解決するわけではありません。Azure DevOps は独自の権限モデルを持っているため、Entra ID 側でアプリを登録しただけでは不十分です。サービス プリンシパルやマネージド ID を使う場合も、Azure DevOps 組織に ID を追加し、Azure DevOps 側で必要なアクセスレベルや権限を付与する必要があります。(Microsoft Learn)

認証方式の選び方

Azure DevOps REST API の認証方式は、アプリの種類で選ぶと判断しやすくなります。

利用シーン推奨される考え方例
ユーザーが画面からサインインして操作するMicrosoft Entra ID OAuth の委任フロー社内ポータル、React アプリ、デスクトップアプリ
ユーザー操作なしで定期実行するサービス プリンシパルまたはマネージド IDAzure Functions、バックグラウンドサービス
Azure 上のリソースから API を呼ぶマネージド ID を優先検討App Service、Functions、VM
CI/CD から Azure DevOps にアクセスするサービス接続やワークロード ID を検討Azure Pipelines、GitHub Actions 連携
個人の一時的な検証PAT を限定的に使用手元の curl、短期の検証スクリプト
Azure DevOps Server 連携Windows 認証、.NET クライアントライブラリ、PATオンプレミス統合

重要なのは、「とりあえず PAT」「とりあえず user_impersonation」ではなく、処理の主体が人間か、アプリか、パイプラインかを先に決めることです。Microsoft の認証ガイダンスでも、新規アプリでは Microsoft Entra ID 認証を使い、PAT は Microsoft Entra ID が使えない場合に限定する考え方が示されています。(Microsoft Learn)

開発者が確認すべき実装ポイント

Azure DevOps のリソース情報を正しく使う

Microsoft Entra ID OAuth で Azure DevOps REST API 用のトークンを取得する場合、Azure DevOps のリソース情報を正しく指定する必要があります。公式ドキュメントでは、Azure DevOps のリソース識別子は 499b84ac-1321-427f-aa17-267ca6975798、リソース URI は https://app.vssps.visualstudio.com とされています。また、アプリに許可されたスコープでトークンを要求する場合は .default スコープを使用します。(Microsoft Learn)

サービス プリンシパルでトークンを取得する例では、スコープに次のような値を指定します。

https://app.vssps.visualstudio.com/.default

REST API 呼び出し時は、取得したアクセストークンを Bearer トークンとして送信します。

GET https://dev.azure.com/{organization}/_apis/projects?api-version=7.2
Authorization: Bearer {access_token}

この部分は旧 Azure DevOps OAuth でも Microsoft Entra ID OAuth でも似ていますが、トークンの取得元、アプリ登録、同意、権限管理の考え方が変わる点に注意してください。

スコープは最小権限で選ぶ

Azure DevOps REST API の OAuth スコープは、アプリがアクセスできるリソースを定義します。公式ドキュメントでは、Microsoft Entra ID OAuth と Azure DevOps OAuth は同じスコープ定義を使うと説明されています。(Microsoft Learn)

実務では、次のように考えると過剰権限を避けやすくなります。

やりたいこと検討するスコープの例注意点
プロジェクトやチームを読むvso.project読み取りだけで足りるか確認
作業項目を読むvso.work更新しないなら write 系は不要
作業項目を作成・更新するvso.work_write更新対象のプロジェクト権限も必要
リポジトリを読むvso.code書き込み不要なら write/manage を避ける
リポジトリを書き換えるvso.code_writeブランチ保護やレビュー運用と合わせて確認
サービス接続を管理するvso.serviceendpoint_manage高権限のため管理者レビューが必要
すべてに近い権限を要求するuser_impersonation非常に強力なため安易に使わない

スコープには継承関係があります。たとえば vso.code_manage は vso.code_write を含みます。つまり「大きいスコープを付ければ安心」ではなく、「大きいスコープほど漏えい時の影響が大きい」と考えるべきです。(Microsoft Learn)

トークンの中身を読まない

移行時に見落とされやすいのが、アクセストークンをデコードしてユーザー ID や組織情報を取得している実装です。Microsoft の認証ガイダンスでは、トークンは不透明なものとして扱い、認可ヘッダーに渡すだけにし、クレームをデータ取得手段として使わないよう案内されています。さらに、2025年夏以降、Azure DevOps は認証トークンの暗号化を進め、トークンのペイロードを読めない形にしていくと説明されています。(Microsoft Learn)

ユーザー情報や組織情報が必要な場合は、トークンを解析するのではなく、Azure DevOps REST API の安定したエンドポイントから取得してください。

旧 Azure DevOps OAuth のコールバック URL とシークレットを確認する

既存の Azure DevOps OAuth アプリを残している間は、コールバック URL、シークレット、refresh token の扱いに注意が必要です。旧 Azure DevOps OAuth では、登録済みの callback URL と一致しないとトークン交換で失敗します。また、アプリケーションシークレットは期限管理とローテーションが必要で、公式ドキュメントでは 60日ごとの期限やローテーションの重要性にも触れられています。(Microsoft Learn)

移行中は、旧方式と新方式が一時的に並行稼働することがあります。その場合は、次のように管理表を作ると事故を減らせます。

確認項目旧 Azure DevOps OAuthMicrosoft Entra ID OAuth
アプリ登録場所Visual Studio プロファイル側Microsoft Entra 管理センター
トークン取得先app.vssps.visualstudio.com/oauth2/tokenlogin.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
コールバック URL登録値と完全一致が必要アプリ登録のリダイレクト URI を確認
シークレット期限・ローテーション管理が必要証明書認証やシークレット管理を検討
権限Azure DevOps OAuth スコープEntra 側の同意と Azure DevOps 側の権限を両方確認
廃止リスク2026年削除予定新規・移行先として推奨

管理者が確認すべき設定と権限

組織内の OAuth アプリを棚卸しする

最初に行うべきことは、Azure DevOps OAuth を使っているアプリの棚卸しです。Microsoft Learn の移行チェックリストでも、組織内で Azure DevOps OAuth を使用しているすべてのアプリを識別し、十分なテスト期間を含む移行タイムラインを計画することが示されています。(Microsoft Learn)

棚卸しでは、少なくとも次の情報を記録します。

項目確認内容
アプリ名社内名だけでなく登録名も記録
利用部門利用者・責任者・問い合わせ先
認証方式Azure DevOps OAuth、PAT、Entra OAuth、サービス プリンシパルなど
利用 APIWork Items、Git、Build、Release、Graph など
要求スコープread/write/manage の違いまで確認
実行頻度常時、日次、手動、CI/CD など
障害時の影響開発停止、デプロイ停止、監査不可など
移行期限2026年の廃止前に余裕を持って設定

特に、退職者が作った社内ツール、古い Jenkins ジョブ、長年使っている PowerShell スクリプト、外部 SaaS 連携は見落とされやすい領域です。

「OAuth 経由のサードパーティ アプリ アクセス」ポリシーを確認する

Azure DevOps 組織では、OAuth 経由のサードパーティ アプリ アクセスに関するポリシーが影響することがあります。公式 FAQ では、この設定が無効な場合、OAuth の承認フロー自体は進んでも、API 呼び出しで TF400813 を含む 401 エラーが返るケースが説明されています。(Microsoft Learn)

確認先は次の形式です。

https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

開発者が「トークンは取れているのに API が 401 になる」と報告してきた場合、コードだけでなく組織ポリシーも確認してください。

サービス プリンシパルとマネージド ID の権限を Azure DevOps 側で付与する

サービス プリンシパルやマネージド ID を使う場合、Microsoft Entra ID にアプリを作成しただけでは Azure DevOps リソースへアクセスできません。Azure DevOps 組織に ID を追加し、アクセスレベル、プロジェクト、リポジトリ、パイプラインなどの権限を付与する必要があります。(Microsoft Learn)

特に注意したいのは、Azure DevOps に追加するときに使う ID です。公式ドキュメントでは、アプリ登録のオブジェクト ID ではなく、Enterprise applications 側にあるサービス プリンシパルのオブジェクト ID を使う必要があると説明されています。(Microsoft Learn)

よくある失敗は次のとおりです。

失敗例原因対処
サービス プリンシパルを追加できないアプリ登録のオブジェクト ID を使っているEnterprise applications 側のオブジェクト ID を確認
API が 401 になるAzure DevOps 組織に ID が追加されていないOrganization settings > Users で追加
Git リポジトリにアクセスできないライセンスやプロジェクト権限が不足Basic 以上のアクセスレベルやリポジトリ権限を確認
Entra 側の権限だけ設定しているAzure DevOps は独自の権限モデルを使うAzure DevOps 側の権限も設定
グループルールでライセンスが付くと思っているサービス プリンシパルでは直接割り当てが必要な場合があるアクセスレベルを個別に確認

移行手順:既存アプリを Microsoft Entra ID OAuth へ移す流れ

Azure DevOps OAuth から Microsoft Entra ID OAuth への移行は、単純なエンドポイント差し替えではありません。認証の主体、同意、権限、ユーザー ID の扱い、トークン保存方法まで見直す必要があります。

まず認証方式を分類する

既存アプリをすべて同じ方式に移すのではなく、処理の種類ごとに分けます。

分類移行先の候補判断基準
ユーザーが画面から操作するアプリMicrosoft Entra ID OAuthユーザーごとの権限で API を呼びたい
バックエンドの定期処理サービス プリンシパルAzure 外でも動く、明示的な資格情報管理が必要
Azure 上の自動化マネージド IDAzure Functions や App Service で動く
パイプライン処理Azure DevOps サービス接続、ワークロード IDCI/CD から安全に呼びたい
一時的な個人スクリプトPAT を短期・限定スコープで使用本番運用にしない

この分類をせずに「旧 OAuth を Entra OAuth に置き換える」だけで進めると、バックグラウンド処理にユーザー委任フローを使ってしまったり、本来はマネージド ID で済む処理に長期シークレットを置いたりする失敗が起きます。

Microsoft Entra アプリを登録する

ユーザー委任のアプリでは、Microsoft Entra 管理センターでアプリ登録を作成し、Azure DevOps リソースへの委任アクセス許可を追加します。Microsoft Learn では、Microsoft Graph ではなくリソース一覧から Azure DevOps を選ぶこと、.default スコープの意味、同意の扱いを確認することが案内されています。(Microsoft Learn)

サービス間連携では、サービス プリンシパルやマネージド ID を使います。サービス プリンシパルでは証明書認証が推奨され、クライアントシークレットを使う場合は定期的なローテーションが必要です。(Microsoft Learn)

Azure DevOps 側に ID と権限を付与する

Microsoft Entra 側でトークンを取得できても、Azure DevOps 側の権限がなければ API は失敗します。サービス プリンシパルやマネージド ID は、Azure DevOps の Organization settings > Users から追加し、アクセスレベルとプロジェクトアクセスを設定します。(Microsoft Learn)

権限設計では、次の順序で確認してください。

  1. Azure DevOps 組織に ID が存在するか
  2. 適切なアクセスレベルが割り当てられているか
  3. 対象プロジェクトにアクセスできるか
  4. 対象リポジトリ、作業項目、パイプライン、サービス接続などに必要な権限があるか
  5. API 側で要求するスコープが過剰または不足していないか

ユーザー ID の扱いを見直す

旧 Azure DevOps OAuth アプリでは、Azure DevOps 側のユーザー識別子を使っていた可能性があります。Microsoft Entra ID へ移行すると、同じユーザーでも識別子の体系が変わることがあります。Microsoft Learn では、移行時に ReadIdentities API を使って、各 ID プロバイダーで使われる異なる ID を解決・照合することが案内されています。(Microsoft Learn)

特に、次のような実装は要注意です。

  • トークン内の claim からユーザー ID を読んでいる
  • Azure DevOps の ID を社内 DB の主キーとして保存している
  • メールアドレスだけでユーザーを突合している
  • MSA ユーザーと Entra ID ユーザーが混在している
  • 外部テナントのユーザーを想定している

非運用環境で API 単位にテストする

移行テストは、ログインできるかだけで終わらせないでください。Azure DevOps REST API は、Work Items、Git、Build、Release、Graph、Service Endpoint など、API ごとに必要なスコープや権限が異なります。

テストでは、次の観点を API ごとに確認します。

テスト観点確認内容
認証トークン取得に成功するか
認可対象プロジェクト・リソースへアクセスできるか
最小権限不要な write/manage 権限を付けていないか
更新処理作業項目作成、PR 更新、Build queue などが成功するか
エラー処理401、403、400、同意拒否、トークン期限切れに対応できるか
監査どの ID が操作したかログで追えるか
ロールバック切り替え失敗時に旧方式へ戻せるか

MSA ユーザーを含むアプリは特に注意

Microsoft Entra OAuth への移行で注意したいのが、Microsoft アカウント、いわゆる MSA ユーザーです。Microsoft Learn では、Microsoft Entra アプリは Azure DevOps リソースに対して MSA ユーザーをネイティブにサポートしていないと説明されています。MSA ユーザー、または Microsoft Entra と MSA の両方をサポートする必要があるアプリでは、移行設計に追加の検討が必要です。(Microsoft Learn)

これは、外部顧客向け SaaS、複数テナントの Azure DevOps 組織を扱うツール、個人 Microsoft アカウントで Azure DevOps を使っているユーザーを対象にするアプリで問題になりやすいポイントです。

既存の Azure DevOps OAuth アプリで MSA ユーザーを扱っている場合は、次の確認を行ってください。

  • 対象ユーザーが Entra ID アカウントか MSA か
  • 顧客テナントをまたぐ利用があるか
  • ユーザー同意と管理者同意のどちらが必要か
  • MSA ユーザーを除外できる業務要件か
  • Microsoft の今後の MSA サポート更新を追跡する体制があるか

よくあるトラブルと確認ポイント

トークンは取得できるが API が 401 になる

トークン取得に成功していても、Azure DevOps 側で権限がなければ API は失敗します。特にサービス プリンシパルやマネージド ID では、Azure DevOps 組織への追加、アクセスレベル、プロジェクト権限、リポジトリ権限を確認してください。(Microsoft Learn)

また、OAuth 経由のサードパーティ アプリ アクセスが無効になっている場合も、承認フローは通るのに API で 401 になることがあります。(Microsoft Learn)

HTTP 400 でトークン交換に失敗する

旧 Azure DevOps OAuth では、トークン要求時の Content-Type、要求本文の形式、期限切れまたは無効な authorization code、callback URL の不一致などが HTTP 400 の原因になります。(Microsoft Learn)

移行時は、旧方式と新方式のパラメーターを混在させないことが重要です。app.vssps.visualstudio.com/oauth2/token 向けのリクエストと、login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token 向けのリクエストでは前提が異なります。

user_impersonation を安易に使ってしまう

user_impersonation は非常に強力なスコープです。公式ドキュメントでも Visual Studio Team Services REST API へのフルアクセスを許可する強力なスコープとして注意が示されています。(Microsoft Learn)

社内ツールで「動かないから全部権限を付ける」という対応をすると、情報漏えい時の影響範囲が広がります。まず API リファレンスで必要スコープを確認し、読み取りだけなら read 系、更新が必要な場合だけ write 系、管理操作が必要な場合だけ manage 系を使ってください。

モバイルアプリで旧 Azure DevOps OAuth を使おうとする

旧 Azure DevOps OAuth は Web サーバーフローのみをサポートし、クライアントシークレットを安全に保存する必要があるため、モバイルアプリには適していないと説明されています。(Microsoft Learn)

モバイルやネイティブアプリで Azure DevOps REST API を使う場合は、旧 Azure DevOps OAuth の流用ではなく、Microsoft Entra ID と MSAL の対応フローを前提に再設計するのが現実的です。

アプリ登録を削除して本番連携を止めてしまう

既存の Azure DevOps OAuth アプリ登録を削除すると、その登録を使っているアプリケーションと関連トークンは直ちに動作しなくなります。(Microsoft Learn)

移行完了前に削除しないよう、削除作業には次の条件を設けてください。

  • 新方式で本番 API が正常に動作している
  • 利用者への周知が完了している
  • 監査ログで新しい ID の操作を確認できている
  • 旧トークンへのアクセスが不要になっている
  • ロールバック不要と判断できる期間を経過している

移行計画の実務チェックリスト

Azure DevOps REST API の OAuth 2.0 認証を見直す場合は、次の順番で進めると抜け漏れを防ぎやすくなります。

フェーズやること完了条件
棚卸しOAuth、PAT、サービスアカウント、パイプライン連携を一覧化すべての API 利用元が分かっている
分類ユーザー委任、サービス間、自動化、個人スクリプトに分ける移行先の認証方式が決まっている
設計Entra アプリ、サービス プリンシパル、マネージド ID を設計スコープと Azure DevOps 権限が最小権限になっている
実装トークン取得処理と API 呼び出し処理を更新Bearer トークンで対象 API を呼べる
ID 移行ユーザー ID、組織 ID、保存済み ID を見直すトークン claim 依存がない
テスト非運用環境で API 単位に検証401、403、400、期限切れ時の動作を確認済み
展開段階的に本番切り替え監査ログと利用者影響を確認済み
廃止旧 OAuth アプリ、不要 PAT、古いシークレットを無効化旧認証への依存が残っていない

管理者・開発者が今すぐやるべきこと

最初にやるべきことは、新しいコードを書くことではなく、今どの認証方式で Azure DevOps REST API を呼んでいるかを可視化することです。特に、Azure DevOps OAuth アプリ、長期 PAT、退職者に紐づくサービスアカウント、古い CI/CD ジョブは優先的に確認してください。

新規開発では、Azure DevOps OAuth を選ばず、Microsoft Entra ID OAuth、サービス プリンシパル、マネージド ID、ワークロード ID など、用途に合った先進認証を選びます。既存アプリでは、2026年の廃止予定を前提に、棚卸し、移行方式の選定、非運用環境での検証、本番切り替え、旧認証の無効化までを計画に入れて進める必要があります。

Azure DevOps REST API の認証は、単なる実装部品ではなく、組織のセキュリティ境界そのものです。今回の変更を機に、過剰スコープ、長期トークン、個人アカウント依存、トークン claim 依存を見直せば、廃止対応だけでなく、運用全体の安全性も高められます。

この記事を書いた人

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows/Office(Teams・Excel)からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

コメント

コメントする

目次