REST API を使用して個人用アクセストークン (PAT) を管理する

[アーティクル]
11/21/2024

Azure DevOps Services

所有する多数の個人用アクセストークン (AT) を処理する場合、UI のみを使用してこれらのトークンのメンテナンスを管理することが複雑になる可能性があります。

PAT Lifecycle Management API を使用すると、自動化されたプロセスを使用して、組織に関連付けられている PAT を簡単に管理できます。この豊富な API セットを使用すると、新しい AT を作成したり、既存の PAT を更新または期限切れにしたりできるように、AT を管理できます。

この記事は、Microsoft Entra トークンで認証し、PAT Lifecycle API を使用して呼び出しを行うアプリケーションを構成する方法について説明しています。使用可能なエンドポイントの一覧を表示するだけの場合は、こちらの API リファレンスを参照してください。

前提条件

アクセス許可: テナントのセキュリティポリシーによっては、組織内のリソースにアクセスするためのアクセス許可がアプリケーションに必要な場合があります。現時点では、このテナントでこのアプリの使用を続行する唯一の方法は、アプリを使用する前に、アプリにアクセス許可を付与するように管理者に依頼することです。

認証:
- API を使用するには、 Microsoft Entra ID OAuth を使用して Microsoft Entra トークンで認証します。詳細については、「認証」セクションを参照してください。
- アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントがある。

Note

サービスプリンシパルまたはマネージド ID を使用して、AT を作成または取り消すことはできません。

Microsoft Entra トークンを使用して認証する

他の Azure DevOps Services API とは異なり、ユーザーは PAT ではなくこの API を使用するためにMicrosoft Entra アクセストークンを提供する必要があります。 Microsoft Entra トークンは、AT を使用するよりも安全な認証メカニズムです。この API の AT の作成と取り消しの機能を考えると、このような強力な機能が許可されたユーザーのみに与えられるようにする必要があります。

Microsoft Entra アクセストークンを取得して更新するには、次のタスクを実行します。

重要

"アプリケーションの代理" ソリューション ("クライアント資格情報" フローなど) と、Microsoft Entra アクセストークンを発行しない認証フローは、この API で使用することはできません。 Microsoft Entra テナントで多要素認証が有効になっている場合は、 "承認コード" フローを確実に使用する必要があります。

Microsoft Entra トークンを処理するための動作する認証フローを持つアプリケーションを作成したら、これらのトークンを使用して PAT ライフサイクル管理 API を呼び出すことができます。

API を直接呼び出すには、要求のヘッダーに Bearer トークンとして Microsoft Entra アクセストークン Authorization 指定します。使用可能な要求の詳細と完全な一覧については、 PAT API リファレンスを参照してください。

次のセクションでは、Microsoft Entra アクセストークンを使用してユーザーを認証するアプリを作成する方法について説明します。アプリは Microsoft Authentication Library (MSAL) ライブラリを使用し、PAT ライフサイクル管理 API を呼び出します。

MSAL には、Microsoft Entra トークンを取得および更新するためにアプリ内で使用できる複数の準拠認証フローが含まれています。 MSAL フローの完全な一覧については、Microsoft 認証ライブラリの認証フローのドキュメント参照してください。アプリケーションに適した認証方法の選択に関するガイドについては、「 Azure DevOps の適切な認証方法を調べる」を参照してください。

開始するには、次のいずれかの例を参照してください。

サンプルの Python Flask アプリを複製しテナントと ADO 組織で構成します
Azure portal で任意の言語のサンプルアプリケーションを生成し、PAT ライフサイクル管理 API 用に構成します

Python Flask Web アプリを複製する

この API 用のサンプル Python Flask Web アプリケーションを提供しました。このアプリケーションは、GitHub でダウンロードし Microsoft Entra テナントと Azure DevOps 組織で使用するように構成できます。サンプルアプリケーションでは、MSAL 認証コードフローを使用して Microsoft Entra アクセストークンを取得します。

重要

GitHub でサンプル Python Flask Web アプリケーションを使用することをお勧めしますが、別の言語またはアプリケーションの種類を使用する場合は、 Quickstart オプションを使用して同等のテストアプリケーションを再作成してください。

サンプルアプリを複製したら、リポジトリの README の指示に従います。 README では、Microsoft Entra テナントにアプリケーションを登録し、Microsoft Entra テナントを使用するようにサンプルを構成し、複製されたアプリを実行する方法について説明します。

クイックスタートの Azure portal アプリケーションを生成する

代わりに、Azure ポータルのアプリケーションのページにある Quickstart オプションを使用して、生成された MSAL コードを使用してサンプルアプリを生成。クイックスタートテストアプリケーションは承認コードフローに従いますが、Microsoft Graph API エンドポイントを使用して行います。ユーザーは、PAT ライフサイクル管理 API のエンドポイントを指すアプリケーションの構成を更新する必要があります。

このアプローチに従うには、 Microsoft Entra ID Develop docs ホームページで 任意のアプリケーションの種類の Quickstartsの手順に従います。次の例では、 Python Flask クイックスタートアプリを使用して説明します。

例: Python Flask クイックスタートアプリケーションの概要

アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントにアプリケーションを登録したら、Azure ポータルの Microsoft Entra ID ->App Registrations で登録済みのアプリケーションに移動。
アプリケーションを選択し、 API のアクセス許可に移動します。
[アクセス許可の追加] を選択しazure DevOps 選択します。->user_impersonationチェック >アクセス許可の追加選択します。
[ Quickstart を選択します。
アプリケーションの種類を選択します。Python Flask の場合は、 Web アプリケーションを選択します。
アプリケーションプラットフォームを選択します。このチュートリアルでは、[Python] を選択します。
必要な前提条件を満たしていることを確認し、Azure portal でアプリケーションを構成するために必要な変更を加えることを許可します。 reply URL は、アプリケーションの作成時に設定されたリダイレクト URL + "/getAToken" です。
クイックスタートアプリケーションをダウンロードし、ファイルを抽出します。
アプリケーションの要件をインストールし、アプリケーションを実行して、必要なすべての依存関係があることを確認します。アプリケーションは、最初は Microsoft Graph API のエンドポイントにヒットするように構成されています。次のセクションの構成手順に従って、このエンドポイントを PAT ライフサイクル管理 API ベースエンドポイントに変更する方法について説明します。

クイックスタートアプリケーションを構成する

ユーザーがクイックスタートアプリケーションをダウンロードしてインストールすると、Microsoft Graph からテスト API エンドポイントを使用するように構成されます。生成された構成ファイルを変更して、代わりに PAT ライフサイクル管理 API を呼び出すようにします。

ヒント

これらのドキュメントでは、コレクションと組織を同じ意味で使用します。構成変数にコレクション名が必要な場合は、それを組織名に置き換えてください。

次のタスクを実行します。

ENDPOINT 構成変数を PAT ライフサイクル管理 API のhttps://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-previewに更新します
SCOPE構成変数を "499b84ac-1321-427f-aa17-267ca6975798/.default"に更新して、Azure DevOps リソースとそのすべてのスコープを参照します。

次の例は、前のセクションで Azure portal を使用して生成したクイックスタート Python Flask アプリケーションに対してこの構成を行った方法を示しています。

手順に従ってクライアントシークレットをセキュリティで保護してください。クライアントシークレットは、最初はプレーンテキストでアプリケーション構成ファイルに挿入されます。ベストプラクティスとして、構成ファイルからプレーンテキスト変数を削除し、環境変数または Azure KeyVault を使用してアプリケーションのシークレットをセキュリティで保護します。

代わりに、クライアントシークレットの代わりに証明書を使用することもできます。アプリケーションが運用環境で使用される場合は、証明書の使用をお勧めします。証明書を使用する手順は、クイックスタートアプリケーションのセットアップの最後の手順で確認できます。

注意事項

運用環境のアプリケーションコードにプレーンテキストクライアントシークレットを残さないようにします。

例: PAT ライフサイクル管理 API 用に Python Flask クイックスタートアプリケーションを構成する

クイックスタートアプリケーションをダウンロードし、その依存関係をインストールし、環境で実行されていることをテストしたら、任意のエディターで app_config.py ファイルを開きます。ファイルは次のコードスニペットのようになります。わかりやすくするために、既定の Microsoft Graph API 構成を参照するコメントが削除されました。

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

アプリ登録のクライアント ID とクライアントシークレットを使用して、クライアント ID またはクライアントシークレットをアプリケーションに更新します。運用環境では、環境変数 Azure KeyVault を使用するか、証明書に切り替えて、クライアントシークレットをセキュリティで保護してください。
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```
ENDPOINT変数を Azure DevOps コレクション URL と API エンドポイントに変更します。たとえば、"testCollection" という名前のコレクションの場合、値は次のようになります。
```
# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'
```
"testCollection" という名前のコレクションの場合、このエンドポイントは次のようになります。
```
ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'
```
SCOPE変数を変更して Azure DevOps API リソースを参照します。文字列は Azure DevOps API のリソース ID であり、.default スコープはそのリソース ID のすべてのスコープを参照します。
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
アプリケーションが (マルチテナント構成ではなく) 特定のテナント用に構成されている場合は、 AUTHORITY 変数の代替値を使用し、"Enter_the_Tenant_Name_Here" に特定のテナント名を追加します。
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

最終的な app_config.py ファイルが、CLIENT_ID、テナント ID、およびコレクション URL と一致することを確認します。セキュリティ上の理由から、CLIENT_SECRETが環境変数、Azure KeyVault に移動されたか、登録されているアプリケーションの証明書とスワップされていることを確認します。

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

アプリケーションを再実行して、要求するユーザーのすべての PAT トークンを取得できることをテストします。検証が完了したら、pat ライフサイクル管理 API エンドポイントの残りの部分への要求の送信をサポートするように、 'app.py' と 'ms-identity-python-webapp-master\templates' ディレクトリの内容を変更できます。すべての PAT ライフサイクル管理 API エンドポイントへの要求をサポートするように変更された Python Flask クイックスタートアプリケーションの例については、GitHub のこのサンプルリポジトリ参照してください。

Microsoft Entra アクセストークンを自動的に更新する

アプリケーションが正しく構成され、ユーザーがアクセストークンを取得すると、トークンを最大 1 時間使用できます。前の両方の例で提供されている MSAL コードは、有効期限が切れるとトークンを自動的に更新します。トークンを更新すると、ユーザーはもう一度サインインして新しい承認コードを取得する必要がなくなります。ただし、更新トークンの有効期限が切れると、ユーザーは 90 日後にもう一度サインインする必要がある場合があります。

PAT ライフサイクル管理 API の詳細を確認する

前の GitHub サンプルアプリケーションとクイックスタートアプリケーションでは、取得した Microsoft Entra トークンを使用して要求を行うために、アプリケーションが事前に構成されています。詳細については、 API リファレンスドキュメントを参照してください。

よく寄せられる質問 (FAQ)

Q: Microsoft Entra トークンを使用して認証する必要がある理由 PAT では不十分な理由

A: この PAT ライフサイクル管理 API を使用して、新しい PAT を作成し、既存の PAT を取り消す機能を開きました。間違った手では、悪意のあるアクターがこの API を使用して、組織の Azure DevOps リソースに複数のエントリポイントを作成する可能性があります。 Microsoft Entra 認証を適用することで、この強力な API をこの不正使用に対してより安全にしたいと考えています。

Q: この API を使用するには、アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントが必要ですか?

A: 残念ながら、この API は、アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントの一部であるユーザーのみが使用できます。

Q: 別の言語/フレームワーク/アプリケーションの種類に対するこのサンプルアプリケーションの例を入手できますか。

A: お好みの言語で API を使用したいと考えています。例のリクエストがある場合は、 Dev Community にアクセスして、他のユーザーが共有する例を持っているかどうかを確認してください。より大規模な Azure DevOps の対象ユーザーと共有するサンプルアプリケーションがある場合は、お知らせくださいこれらのドキュメントでの循環について詳しく説明します。

Q: このトークン API とトークン管理者 API の違いは何ですか?

A: このトークン API とトークン管理 API 同様に、さまざまなユースケースと対象ユーザーに対応します。

このトークン API は、主に、自分が所有する AT を自動パイプラインで管理する必要があるユーザーを対象とします。この API は許可します。新しいトークンを作成し、既存のトークンを更新する機能を提供します。
トークン管理者 API は、組織の管理者を対象としています。管理者は、この API を使用して、組織内のユーザーの個人用アクセストークン (AT) や自己記述型セッショントークンなどの OAuth 承認を取得および取り消すことができます。

Q: API を使用して AT を再生成またはローテーションするにはどうすればよいですか? UI でそのオプションを見ましたが、API に同様のメソッドが表示されません。

A: 素晴らしい質問! UI で使用できる "再生成" 機能では、API を介して完全にレプリケートできるいくつかのアクションが実際に実行されます。

PAT を回転するには、次の手順を実行します。

GET 呼び出しを使用して PAT のメタデータを理解する
POST呼び出しを使用して、古い PAT のメタデータを含む新しい PAT を作成します。
DELETE 呼び出しを使用して古い PAT を取り消す

Q: このアプリの使用を続行しようとすると、[管理者の承認が必要です] ポップアップが表示されます。管理者の承認なしにこのアプリを使用するにはどうすればよいですか?

A: テナントにはセキュリティポリシーがあり、組織内のリソースにアクセスするためのアクセス許可をアプリケーションに付与する必要があるようです。現時点では、このテナントでこのアプリの使用を続行する唯一の方法は、アプリを使用する前に、アプリにアクセス許可を付与するように管理者に依頼することです。

Q: サービスプリンシパルまたはマネージド ID を使用して PAT ライフサイクル管理 API を呼び出そうとしたときに、"サービスプリンシパルはこのアクションを実行できません" のようなエラーが表示されるのはなぜですか。

A: サービスプリンシパルとマネージド ID は許可されません。この API の AT の作成と取り消しの機能を考えると、このような強力な機能が許可されたユーザーのみに与えられるようにする必要があります。

次のステップ

PAT ライフサイクル管理 API エンドポイントについて説明します

次の方法で共有

REST API を使用して個人用アクセストークン (PAT) を管理する

前提条件

Microsoft Entra トークンを使用して認証する

Python Flask Web アプリを複製する