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

Azure DevOps Services

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

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

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

前提条件

API を使用するには、Microsoft Entra トークンで認証する必要があります。これは Microsoft Entra ID OAuth を使用して行うことができます。 これを行う方法の詳細については、次 の認証セクションを参照してください。

そのためには、いくつかの前提条件を満たす必要があります。

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

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

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

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

• アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントを用意する
• Microsoft Entra テナントにアプリケーションを登録する
• アプリケーションに Azure DevOps アクセス許可を追加する

重要

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

注意事項

アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントを使用することは、この API を使用するための前提条件です。

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

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

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

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

2 つの例のいずれかに従って作業を開始します。

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

Python Flask Web アプリを複製する

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

重要

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

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

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

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

このアプローチに従うには、Microsoft Entra ID 開発ドキュメントのホーム ページで、選択したアプリケーションの種類に関するクイック スタートの手順に従います。 Python Flask クイック スタート アプリでこれを行った例について説明します。

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

1. アクティブな Azure サブスクリプションを持つ Microsoft Entra テナントにアプリケーションを登録したら、Azure portal の Microsoft Entra ID ->App Registrations で登録済みのアプリケーションに移動します。

   

2. アプリケーションを選択し、[API のアクセス許可] に 移動します。

   

3. [アクセス許可の追加] を選択し、[Azure DevOps -> チェック user_impersonation -> アクセス許可の追加] を選択します。

   

4. 左側のナビゲーション パネルから [クイック スタート] を選択します。

5. アプリケーションの種類を選択します。Python Flask の場合は、[Web アプリケーション] を選択します。

6. アプリケーション プラットフォームを選択します。 このチュートリアルでは、[Python] を選択します。

7. 必要な前提条件を満たしていることを確認し、Azure portal でアプリケーションを構成するために必要な変更を行うことを許可します。 応答 URL は、アプリケーションの作成時に設定されたリダイレクト URL + "/getAToken" になります。

   

8. クイック スタート アプリケーションをダウンロードし、ファイルを抽出します。

   

9. アプリケーションの要件をインストールし、アプリケーションを実行して、必要なすべての依存関係があることを確認します。 アプリケーションは、最初は Microsoft Graph API のエンドポイントにヒットするように構成されています。 次のセクションの構成手順に従って、このエンドポイントを PAT ライフサイクル管理 API ベース エンドポイントに変更する方法について説明します。

   

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

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

ヒント

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

そのためには、いくつかの操作を行う必要があります。

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

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

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

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

注意事項

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

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

1. クイック スタート アプリケーションをダウンロードし、その依存関係をインストールし、環境で実行されることをテストしたら、任意のエディターでファイルを開 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
   

2. アプリ登録のクライアント 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.
   

3. 変数を 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'
   

4. SCOPE Azure DevOps API リソースを参照するように変数を変更します。文字列は Azure DevOps API のリソース ID であり、".default" スコープは、そのリソース ID のすべてのスコープを参照します。

   SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
   

5. アプリケーションが (マルチテナント構成ではなく) 特定のテナント用に構成されている場合は、変数の代替値を 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"
   

6. 最終的な app_config.py ファイルが、CLIENT_ID、テナント ID、およびコレクション URL と一致することを確認します。 セキュリティ上の理由から、CLIENT_Standard Edition CRET が環境変数、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
   

7. アプリケーションを再実行して、要求するユーザーのすべての 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 リファレンス のドキュメントを参照してください。

よく寄せられる質問

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

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

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

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

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

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

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

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

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

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

A: 大きな質問です。 UI で使用できる "再生成" 機能は、API を通じて完全にレプリケートできるいくつかのアクションを実際に実行します。

PAT を回転するには、次の手順を実行する必要があります。

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

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

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

次のステップ

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