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

[アーティクル]
12/30/2024

Azure DevOps Services

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

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

この記事では、Microsoft Entra トークンで認証し、PAT ライフサイクル API を使用して呼び出しを行うアプリケーションを構成する方法について説明します。

重要

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

前提条件

他の Azure DevOps Services API とは異なり、ユーザーは、この API を使用するために microsoft Entra アクセストークンを提供する必要があります。この API の PAT の作成と取り消しの機能を考慮すると、そのような強力な機能が、より安全な Microsoft Entra トークンのみに使用できるようにしたいと考えています。

Microsoft Entra アクセストークンを取得して更新するには、次の操作を行う必要があります。

アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントを用意する
Microsoft Entra テナントにアプリケーションを登録する
アプリケーションに Azure DevOps アクセス許可を追加する
テナント管理者から同意を得る: テナントのセキュリティポリシーによっては、組織内のリソースにアクセスするためのアクセス許可がアプリケーションに必要な場合があります。テナント内で使用するアクセス許可をアプリに付与するようにテナント管理者に要求します。

重要

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

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

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

次のセクションでは、Microsoft Entra アクセストークンを使用してユーザーを認証するアプリを作成する方法について説明します。アプリは、Microsoft Authentication Library (MSAL) を使用し、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 クイックスタートアプリを使用して説明します。

アクティブな Azure サブスクリプションを使用して Microsoft Entra テナントにアプリケーションを登録したら、Azure portalの [Microsoft Entra ID ->App Registrations で登録済みアプリケーションに移動します。
アプリケーションを選択し、 API のアクセス許可に移動します。
[アクセス許可の追加] を選択し、[Azure DevOps] -> 必要なスコープの順に選択します。この場合、PAT ライフサイクル管理 API では user_impersonation のみがサポートされますが、他の API ではより詳細なスコープが要求される場合があります (各 API のリファレンスページを参照してください)。すべてのスコープが選択されたら、[アクセス許可の追加]クリックします。
[ 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 を使用してアプリケーションのシークレットをセキュリティで保護します。

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

注意事項

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

クイックスタートアプリケーションをダウンロードし、その依存関係をインストールし、環境で実行されていることをテストしたら、任意のエディターで 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 日後にもう一度サインインする必要がある場合があります。

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

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

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

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

このトークン API とトークン管理者 APIは、同様に、さまざまなユースケースと対象ユーザーに提供されます。

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

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

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

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

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

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

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

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

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

次の方法で共有

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

前提条件

Python Flask Web アプリを複製する

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

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

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

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

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

前提条件

Python Flask Web アプリを複製する

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

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

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

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

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

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

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

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

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

フィードバック

その他のリソース

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

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

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

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

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

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

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