使用 REST API 管理個人存取權杖（PAT）

發行項
10/23/2023

Azure DevOps Services

當您處理您擁有的大量個人存取權杖（PAT）時，單獨使用 UI 管理這些權杖的維護可能會變得很複雜。

透過 PAT 生命週期管理 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，使用者必須提供 Microsoft Entra 存取權杖，才能使用此 API，而不是 PAT 權杖。 Microsoft Entra 權杖是比使用 PAT 更安全的驗證機制。鑒於此 API 能夠建立和撤銷 PAT，我們想要確保只有允許的使用者提供這類強大的功能。

若要取得並重新整理 Microsoft Entra 存取權杖，您必須：

重要

「代理應用程式」解決方案（例如「用戶端認證」流程，以及未發出 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 權杖。您可以在 Microsoft 驗證程式庫「驗證流程」檔中找到 MSAL 流程的完整清單。在為 Azure DevOps 選擇正確的驗證方法底下，可以找到為應用程式選擇正確驗證方法的指南。

請遵循這兩個範例的其中一個來開始使用：

複製我們的範例 Python Flask 應用程式，並使用您的租使用者和 ADO 組織進行設定
針對您選擇的語言，在Azure 入口網站中產生範例應用程式，並針對 PAT 生命週期管理 API 進行設定

複製 Python Flask Web 應用程式

我們為您提供此 API 的範例 Python Flask Web 應用程式，您可以在 GitHub 上下載，並可設定為與您的 Microsoft Entra 租使用者和 Azure DevOps 組織搭配使用。範例應用程式會使用 MSAL 驗證程式代碼流程來取得 Microsoft Entra 存取權杖。

重要

建議您開始使用 GitHub 上的範例 Python Flask Web 應用程式，但如果您想要使用不同的語言或應用程式類型，請使用快速入門選項來重新建立對等的測試應用程式。

複製範例應用程式之後，請遵循存放庫讀我檔案中的指示。讀我檔案說明如何在 Microsoft Entra 租使用者中註冊應用程式、設定範例以使用您的 Microsoft Entra 租使用者，以及執行複製的應用程式。

產生快速入門Azure 入口網站應用程式

相反地，您可以使用 Azure 入口網站中應用程式頁面上的 [快速入門 ] 選項，產生具有所產生 MSAL 程式碼 的範例應用程式。快速入門測試應用程式會遵循授權碼流程，但會使用 Microsoft Graph API 端點執行此動作。使用者必須更新應用程式的組態，以指向 PAT 生命週期管理 API 的端點。

若要遵循此方法，請遵循 Microsoft Entra ID 開發檔首頁上所選應用程式類型的快速入門 指示。我們將逐步解說我們已針對 Python Flask 快速入門應用程式完成此動作的範例。

範例：開始使用 Python Flask 快速入門應用程式

在具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者中註冊應用程式之後，請在Azure 入口網站的 Microsoft Entra ID - > App Registrations 下 流覽至已註冊的應用程式。
選取您的應用程式並流覽至 [API 許可權 ]。
選取 [新增許可權 ]，然後選取 [Azure DevOps - > 檢查 user_impersonation - > 選取 [ 新增許可權 ]。
從左側導覽面板中選取 [快速入門 ]。
選取您的應用程式類型：針對 Python Flask，選取 [Web 應用程式 ]。
選取您的應用程式平臺。在本教學課程中，選取 [Python]。
請確定您已符合必要的必要條件，然後允許Azure 入口網站進行必要的變更來設定您的應用程式。回復 URL 將會是應用程式建立時所設定的重新導向 URL + 「/getAToken」。
下載快速入門應用程式並擷取檔案。
安裝應用程式需求並執行應用程式，以確保您擁有所有必要的相依性。應用程式一開始設定為在 Microsoft Graph API 中叫用端點。遵循下一節中的設定指示，瞭解如何將此端點變更為 PAT 生命週期管理 API 基底端點。

設定快速入門應用程式

使用者下載並安裝快速入門應用程式之後，將會設定為使用來自 Microsoft Graph 的測試 API 端點。我們必須修改產生的組態檔，使其改為呼叫 PAT 生命週期管理 API。

提示

我們會在這些檔中交替使用集合和組織。如果組態變數需要集合名稱，請將它取代為您的組織名稱。

若要這樣做，我們需要執行一些動作：

將 PAT 生命週期管理 API 的 ENDPOINT 組態變數更新為 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 入口網站產生的快速入門 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

使用應用程式註冊的用戶端識別碼和用戶端密碼，將用戶端識別碼或用戶端密碼更新至您的應用程式。在生產環境中時，請務必使用環境變數、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 的資源識別碼，而「.default」範圍是指該資源識別碼的所有範圍。
```
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、租使用者識別碼和集合 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 權杖。確認您擁有之後，請隨意修改和 'ms-identity-python-webapp-master\templates' 目錄的內容 'app.py' ，以支援將要求傳送至 PAT 生命週期管理 API 端點的其餘部分。如需已修改以支援所有 PAT 生命週期管理 API 端點要求之 Python Flask 快速入門應用程式的範例，請參閱 GitHub 上的此範例存放庫。

自動重新整理 Microsoft Entra 存取權杖

一旦應用程式正確設定且使用者已取得存取權杖，權杖最多可以使用一小時。上述兩個範例中提供的 MSAL 程式碼會在權杖到期後自動重新整理。重新整理權杖可防止使用者再次登入，並取得新的授權碼。不過，使用者可能需要在重新整理權杖到期 90 天后再次登入。

探索 PAT 生命週期管理 API 的

在上述 GitHub 範例應用程式和快速入門應用程式中，應用程式已預先設定為使用您取得的 Microsoft Entra 權杖提出要求。若要深入瞭解端點、他們接受的參數，以及回應中傳回的參數，請參閱 API 參考檔。

常見問題

問：為什麼我需要向 Microsoft Entra 權杖進行驗證？為什麼 PAT 不夠？

答：使用此 PAT 生命週期管理 API，我們已開啟建立新的 PAT 並撤銷現有 PAT 的能力。在錯誤的手中，惡意執行者可以使用此 API，在組織的 ADO 資源中建立多個進入點。藉由強制執行 Microsoft Entra 驗證，我們希望讓這個強大的 API 更安全，以防止此未經授權的使用。

問：我需要有具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者才能使用此 API 嗎？

答：不幸的是，此 API 僅適用于具有作用中 Azure 訂用帳戶之 Microsoft Entra 租使用者的使用者。

問：我可以取得另一個語言/架構/應用程式類型的此範例應用程式範例嗎？

答：我們喜歡您想要以您選擇的語言使用 API！如果您有範例的要求，請前往我們的開發社群，查看其他人是否有要共用的範例。如果您有想要與較大型 Azure DevOps 物件共用的範例應用程式，請讓我們知道，我們可以更廣泛地探討將這些檔散發！

問：此權杖 API 與權杖管理員 API 有何差異？

答：此權杖 API 和權杖管理員 API 雖然類似，但會提供不同的使用案例和物件：

此權杖 API 主要適用于想要在自動化管線中管理其擁有之 PAT 的使用者。此 API 允許。它可讓您建立新的權杖並更新現有的權杖。
權杖管理員 API 適用于組織系統管理員。管理員可以使用此 API 來擷取和撤銷 OAuth 授權，包括組織使用者的個人存取權杖（PAT）和自我描述會話權杖。

問：如何透過 API 重新產生/輪替 PAT？我在 UI 中看到該選項，但我在 API 中看不到類似的方法。

答：偉大的問題！ UI 中提供的「重新產生」功能實際上會完成一些動作，這些動作可透過 API 完全複寫。

若要旋轉 PAT，您需要：

使用 GET 呼叫瞭解 PAT 的中繼資料，
使用 POST 呼叫建立具有舊 PAT 中繼資料的新 PAT，
使用 DELETE 呼叫撤銷舊的 PAT

問：當我嘗試使用此應用程式時，我會看到「需要系統管理員核准」快顯視窗。如何在未經系統管理員核准的情況下使用此應用程式？

答：您的租使用者似乎已設定安全性原則，要求您的應用程式獲授與存取組織資源的許可權。目前，在此租使用者中使用此應用程式的唯一方式是要求系統管理員授與應用程式許可權，才能使用它。

下一步

瞭解 PAT 生命週期管理 API 端點

使用 REST API 管理個人存取權杖（PAT）

必要條件

使用 Microsoft Entra 權杖進行驗證

複製 Python Flask Web 應用程式

產生快速入門Azure 入口網站應用程式

範例：開始使用 Python Flask 快速入門應用程式

設定快速入門應用程式

範例：設定 PAT 生命週期管理 API 的 Python Flask 快速入門應用程式

自動重新整理 Microsoft Entra 存取權杖

探索 PAT 生命週期管理 API 的

常見問題

問：為什麼我需要向 Microsoft Entra 權杖進行驗證？為什麼 PAT 不夠？

問：我需要有具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者才能使用此 API 嗎？

問：我可以取得另一個語言/架構/應用程式類型的此範例應用程式範例嗎？

問：此權杖 API 與權杖管理員 API 有何差異？

問：如何透過 API 重新產生/輪替 PAT？我在 UI 中看到該選項，但我在 API 中看不到類似的方法。

問：當我嘗試使用此應用程式時，我會看到「需要系統管理員核准」快顯視窗。如何在未經系統管理員核准的情況下使用此應用程式？

下一步

意見反應

意見反應

其他資源

使用 REST API 管理個人存取權杖 （PAT）

必要條件

使用 Microsoft Entra 權杖進行驗證

複製 Python Flask Web 應用程式

產生快速入門Azure 入口網站應用程式

範例：開始使用 Python Flask 快速入門應用程式

設定快速入門應用程式

範例：設定 PAT 生命週期管理 API 的 Python Flask 快速入門應用程式

自動重新整理 Microsoft Entra 存取權杖

探索 PAT 生命週期管理 API 的

常見問題

問：為什麼我需要向 Microsoft Entra 權杖進行驗證？ 為什麼 PAT 不夠？

問：我需要有具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者才能使用此 API 嗎？

問：我可以取得另一個語言/架構/應用程式類型的此範例應用程式範例嗎？

問：此權杖 API 與權杖管理員 API 有何差異？

問：如何透過 API 重新產生/輪替 PAT？ 我在 UI 中看到該選項，但我在 API 中看不到類似的方法。

問：當我嘗試使用此應用程式時，我會看到「需要系統管理員核准」快顯視窗。 如何在未經系統管理員核准的情況下使用此應用程式？

下一步

意見反應

意見反應

其他資源

使用 REST API 管理個人存取權杖（PAT）

問：為什麼我需要向 Microsoft Entra 權杖進行驗證？為什麼 PAT 不夠？

問：如何透過 API 重新產生/輪替 PAT？我在 UI 中看到該選項，但我在 API 中看不到類似的方法。

問：當我嘗試使用此應用程式時，我會看到「需要系統管理員核准」快顯視窗。如何在未經系統管理員核准的情況下使用此應用程式？