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

文章
10/25/2024

Azure DevOps Services

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

透過 PAT 生命週期管理 API，您可以輕鬆地使用自動化程序來管理與組織相關聯的 PAT。這組豐富的 API 可讓您管理您的 PAT，讓您建立新的 PAT 並更新或過期現有的 PAT。

在本文中，我們會示範如何設定應用程式，使其透過 Microsoft Entra 權杖進行驗證，並使用 PAT 生命週期 API 呼叫。如果您只要查看可用端點的完整清單，請在這裡檢視 API 參考。

必要條件

許可權： 視租使用者的安全策略而定，您的應用程式可能需要許可權才能存取組織中的資源。目前，在此租用戶中繼續使用此應用程式的唯一方式是要求系統管理員授與應用程式許可權，才能使用它。

驗證：
- 若要使用 API，請透過 Microsoft Entra ID OAuth 向 Microsoft Entra 令牌進行驗證。如需詳細資訊，請參閱驗證一節。
- 具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者。

注意

您無法使用服務主體或受控識別來建立或撤銷 PAT。

使用 Microsoft Entra 令牌進行驗證

不同於其他 Azure DevOps Services API，用戶必須提供 Microsoft Entra 存取令牌，才能使用此 API，而不是 PAT。 Microsoft Entra 令牌是比使用 PAT 更安全的驗證機制。鑒於此 API 能夠建立和撤銷 PAT，我們想要確保只有允許的使用者提供這類強大的功能。

若要取得並重新整理Microsoft Entra 存取令牌，請執行下列工作：

重要

「代理應用程式」解決方案（例如「用戶端認證」流程）和未發出Microsoft Entra 存取令牌的任何驗證流程，都不適用於此 API。如果您的Microsoft Entra 租使用者中已啟用多重要素驗證，您一定要使用「授權碼」流程。

當您有一個應用程式具有可處理Microsoft Entra 令牌的工作驗證流程之後，您就可以使用這些令牌來呼叫 PAT 生命週期管理 API。

若要直接呼叫 API，請在要求的標頭中Authorization提供 Microsoft Entra 存取令牌作為Bearer令牌。如需詳細資訊和可用要求的完整清單，請參閱 PAT API 參考。

在下一節中，我們將示範如何建立應用程式，以Microsoft Entra 存取令牌來驗證使用者。應用程式會使用 Microsoft 驗證連結庫（MSAL）連結庫，並呼叫我們的 PAT 生命週期管理 API。

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 Develop docs 首頁上所選應用程式類型的快速入門指示。我們會使用 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圖形 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 參考檔。

常見問題集 (FAQ)

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

答：使用此 PAT 生命週期管理 API，我們開啟了建立新的 PAT 並撤銷現有 PAT 的能力。在錯誤的手中，惡意執行者可以使用此 API，在組織的 Azure DevOps 資源中建立多個進入點。藉由強制執行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 時，為何會看到「不允許服務主體執行此動作」之類的錯誤？

答：不允許服務主體和受控識別。鑒於此 API 能夠建立和撤銷 PAT，我們想要確保只有允許的使用者提供這類強大的功能。

下一步

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

分享方式：

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

必要條件

使用 Microsoft Entra 令牌進行驗證

複製 Python Flask Web 應用程式

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

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

設定快速入門應用程式

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

自動重新整理Microsoft Entra 存取令牌

探索 PAT 生命週期管理 API

常見問題集 (FAQ)

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

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

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

問：此令牌 API 與令牌管理員 API 有何差異？

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

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

問：當我嘗試使用服務主體或受控識別呼叫 PAT 生命週期管理 API 時，為何會看到「不允許服務主體執行此動作」之類的錯誤？

下一步

意見反映

更多資源

分享方式：

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

必要條件

使用 Microsoft Entra 令牌進行驗證

複製 Python Flask Web 應用程式

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

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

設定快速入門應用程式

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

自動重新整理Microsoft Entra 存取令牌

探索 PAT 生命週期管理 API

常見問題集 (FAQ)

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

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

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

問：此令牌 API 與令牌管理員 API 有何差異？

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

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

問：當我嘗試使用服務主體或受控識別呼叫 PAT 生命週期管理 API 時，為何會看到「不允許服務主體執行此動作」之類的錯誤？

下一步

意見反映

更多資源

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

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

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

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

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