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

Azure DevOps Services

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

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

在本文中，我們會示範如何設定 使用 Microsoft Entra 令牌進行驗證的應用程式，並使用 PAT 生命週期 API 進行呼叫。

必要條件

不同於其他 Azure DevOps Services API，用戶必須提供 Microsoft Entra 存取令牌 才能使用此 API。 鑒於此 API 建立和撤銷 PAT 的能力，我們想要確保這類強大的功能只能 更安全 Microsoft 的 entra 令牌。

若要取得並重新整理Microsoft Entra 存取令牌，您必須執行下列動作：

• 具有作用中 Azure 訂用帳戶的 Microsoft Entra 租使用者
• 在其Microsoft Entra 租用戶中註冊應用程式
• 將 Azure DevOps 許可權新增至應用程式
• 從租用戶系統管理員取得同意：視租使用者的安全策略而定，您的應用程式可能需要許可權才能存取組織中的資源。 請租戶管理員授予應用程式許可權，以便在您的租戶中使用它。

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

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

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

複製 Python Flask Web 應用程式

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

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

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

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

若要遵循此方法，請遵循 Microsoft Entra ID Develop docs 首頁上所選應用程式類型的快速入門指示。 我們會使用 Python Flask 快速入門應用程式逐步解說下列範例。

1. 一旦您在具有有效 Azure 訂用帳戶的 Microsoft Entra 租戶中註冊應用程式之後，請前往 Azure 入口網站，流覽至您在 Microsoft Entra ID ->應用程式註冊 中的 項目。

   

2. 選取您的應用程式並流覽至 [API 許可權]。

   

3. 選取 新增許可權，然後選取 Azure DevOps ，然後選取您需要的適當範圍>。 在此情況下，PAT 生命週期管理 API 僅支援 user_impersonation，但其他 API 可能會要求不同的 細微範圍， 您可以在每個 API 的個別參考頁面 找到。 選取所有範圍之後，請按 [新增權限]。

   

4. 選取 [快速入門]。

5. 選取您的應用程式類型：針對 Python Flask，選取 [Web 應用程式]。

6. 選取您的應用程式平臺。 在本教學課程中，選取 [Python]。

7. 請確定您符合必要的必要條件，然後允許 Azure 入口網站 進行必要的變更來設定您的應用程式。 回復 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 入口網站 產生的快速入門 Python Flask 應用程式執行此設定。

請確定您遵循指示來保護用戶端密碼，該密碼一開始會以純文本插入應用程式組態檔。 最佳做法是從組態檔中移除純文本變數，並使用環境變數或 Azure KeyVault 來保護其應用程式的秘密。

相反地，您可以選擇使用憑證，而不是客戶端密碼。 如果應用程式用於生產環境，則使用憑證是建議的選項。 您可以在快速入門應用程式設定的最後一個步驟中找到使用憑證的指示。

1. 下載快速入門應用程式之後，請安裝其相依性，並測試它在環境中執行，請在您選擇的編輯器中開啟 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
   

2. 使用應用程式註冊的用戶端識別碼和客戶端密碼，將用戶端識別碼或客戶端密碼更新至您的應用程式。 在生產環境中時，請務必使用環境變數、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 的資源識別符，而.default範圍則參考該資源識別碼的所有範圍。

   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、租使用者標識碼和集合 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
   

7. 重新執行應用程式以測試您可以取得要求使用者的所有 PAT 令牌。 驗證之後，您可以修改 和 'app.py' 目錄的內容'ms-identity-python-webapp-master\templates'，以支援將要求傳送至 PAT 生命週期管理 API 端點的其餘部分。 如需已修改以支援所有 PAT 生命週期管理 API 端點要求之 Python Flask 快速入門應用程式的範例， 請參閱 GitHub 上的此範例存放庫。

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

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

常見問題集 (FAQ)

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

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

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

此 令牌 API 與 令牌管理員 API雖然相似，但針對不同的使用案例和受眾：

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

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

UI 中提供的「重新產生」功能實際上會完成一些可透過 API 完整複寫的動作。

若要輪替 PAT，請執行下列步驟：

1. 使用 GET 呼叫瞭解 PAT 的元數據，
2. 使用 POST 呼叫建立具有舊 PAT 元數據的新 PAT，
3. 使用 DELETE 呼叫撤銷舊的 PAT

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

您的租戶似乎有某些安全政策，這些政策需要為您的應用程式授予權限，以存取組織內的資源。 目前，在此租使用者中使用此應用程式的唯一方式是要求系統管理員授與應用程式許可權，才能使用它。

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

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