Hantera personliga åtkomsttoken (PAT) med hjälp av REST API

Artikel
10/23/2023

Azure DevOps Services

När du har att göra med en stor uppsättning personliga åtkomsttoken (PAT) som du äger kan det bli komplicerat att hantera underhållet av dessa token enbart med hjälp av användargränssnittet.

Med API:et för livscykelhantering av personliga åtkomsttokens kan du enkelt hantera de som är associerade med dina organisationer med hjälp av automatiserade processer. Med den här omfattande uppsättningen API:er kan du hantera de PAT:er som du äger, så att du kan skapa nya personliga åtkomsttoken och förnya eller förfalla befintliga personliga åtkomsttoken.

I den här artikeln visar vi hur du konfigurerar ett program som autentiserar med en Microsoft Entra-token och gör anrop med PAT-livscykel-API:et. Om du bara vill se hela listan med tillgängliga slutpunkter kan du läsa API-referensen här.

Förutsättningar

Om du vill använda API:et måste du autentisera med en Microsoft Entra-token, vilket kan göras via Microsoft Entra ID OAuth. Läs mer om hur du gör detta i följande autentiseringsavsnitt.

För att kunna göra det måste några förutsättningar uppfyllas:

Du måste ha en Microsoft Entra-klientorganisation med en aktiv Azure-prenumeration.
Beroende på klientorganisationens säkerhetsprinciper kan programmet behöva beviljas behörighet för att få åtkomst till resurser i organisationen. För närvarande är det enda sättet att fortsätta med att använda den här appen i den här klientorganisationen att be en administratör att bevilja behörighet till appen innan du kan använda den.

Autentisera med Microsoft Entra-token

Till skillnad från andra API:er för Azure DevOps Services måste användarna ange en Microsoft Entra-åtkomsttoken för att kunna använda det här API:et i stället för en PAT-token. Microsoft Entra-token är en säkrare autentiseringsmekanism än att använda PAT. Med tanke på det här API:ets möjlighet att skapa och återkalla PAT:er vill vi se till att sådana kraftfulla funktioner endast ges till tillåtna användare.

För att kunna hämta och uppdatera Microsoft Entra-åtkomsttoken måste du:

Viktigt!

Lösningar för programmets räkning (till exempel flödet "klientautentiseringsuppgifter" och alla autentiseringsflöden som inte utfärdar en Microsoft Entra-åtkomsttoken är inte giltiga för användning med det här API:et. Om multifaktorautentisering är aktiverat i din Microsoft Entra-klientorganisation måste du definitivt använda flödet "auktoriseringskod".

Varning

Att ha en Microsoft Entra-klientorganisation med en aktiv Azure-prenumeration är en förutsättning för att använda det här API:et.

När du har ett program med ett fungerande autentiseringsflöde för hantering av Microsoft Entra-token kan du använda dessa token för att göra anrop till API:et för hantering av pat-livscykel.

För att kunna anropa API:et direkt måste du ange en Microsoft Entra-åtkomsttoken som en Bearer token i rubriken för Authorization din begäran. Om du vill se exemplen och en fullständig lista över tillgängliga begäranden läser du PAT API-referensen

I följande avsnitt visar vi hur du skapar en app som autentiserar en användare med en Microsoft Entra-åtkomsttoken med hjälp av MSAL-biblioteket och anropar vårt API för PAT Lifecycle Management.

Microsoft Authentication Library (MSAL) innehåller flera kompatibla autentiseringsflöden som du kan använda i din app för att hämta och uppdatera Microsoft Entra-token. En fullständig lista över MSAL-flöden finns i dokumentationen "autentiseringsflöden" i Microsoft Authentication Library. En guide för att välja rätt autentiseringsmetod för ditt program finns under Välja rätt autentiseringsmetod för Azure DevOps.

Följ något av de två exemplen för att komma igång:

Klona python Flask-exempelappen och konfigurera den med din klientorganisation och ADO-organisation
Generera ett exempelprogram i Azure-portalen för valfritt språk och konfigurera det för API:et för PAT Lifecycle Management

Klona vår Python Flask-webbapp

Vi har försett dig med ett Python Flask-exempelwebbprogram för det här API:et som du kan ladda ned på GitHub och som kan konfigureras att användas med din Microsoft Entra-klientorganisation och Azure DevOps-organisation. Exempelprogrammet använder MSAL-autentiseringskodflödet för att hämta en Microsoft Entra-åtkomsttoken.

Viktigt!

Vi rekommenderar att du kommer igång med python Flask-exempelwebbprogrammet på GitHub, men om du föredrar att använda ett annat språk eller en annan programtyp använder du snabbstartsalternativet för att återskapa ett motsvarande testprogram.

När du har klonat exempelappen följer du anvisningarna i lagringsplatsens README. README förklarar hur du registrerar ett program i din Microsoft Entra-klientorganisation, konfigurerar exemplet för att använda din Microsoft Entra-klientorganisation och kör din klonade app.

Skapa ett Azure-portalprogram för snabbstart

I stället kan du generera en exempelapp med den genererade MSAL-koden med hjälp av snabbstartsalternativet på programmets sida i Azure-portalen. Snabbstartstestprogrammet följer auktoriseringskodflödet, men gör det med en Microsoft Graph API-slutpunkt. Användarna måste uppdatera programmets konfiguration så att den pekar på slutpunkten för API:et för PAT-livscykelhantering.

Följ snabbstartsinstruktionerna för den programtyp du väljer på startsidan för Microsoft Entra ID Utveckla dokument för att följa den här metoden. Vi går igenom ett exempel där vi har gjort detta för en Snabbstartsapp för Python Flask.

Exempel: Kom igång med ett Snabbstartsprogram för Python Flask

När du har registrerat ditt program i en Microsoft Entra-klientorganisation som har en aktiv Azure-prenumeration går du till ditt registrerade program under Microsoft Entra-ID –>Appregistreringar i Azure-portalen.
Välj ditt program och gå till API-behörigheter.
Välj Lägg till en behörighet och välj Azure DevOps –> kontrollera user_impersonation –> välj Lägg till behörigheter.
Välj Snabbstart i den vänstra navigeringspanelen.
Välj din programtyp: För Python Flask väljer du Webbprogram.
Välj din programplattform. I den här självstudien väljer du "Python".
Kontrollera att du uppfyller de nödvändiga kraven och tillåt sedan att Azure-portalen gör de ändringar som krävs för att konfigurera programmet. Svars-URL :en är den omdirigerings-URL som angavs när programmet skapades + "/getAToken".
Ladda ned snabbstartsprogrammet och extrahera filerna.
Installera programkraven och kör programmet för att säkerställa att du har alla nödvändiga beroenden. Programmet är ursprungligen konfigurerat för att träffa en slutpunkt i Microsoft Graph API. Lär dig hur du ändrar den här slutpunkten till API-basslutpunkten för PAT Lifecycle Management genom att följa konfigurationsanvisningarna i följande avsnitt.

Konfigurera ett snabbstartsprogram

När användaren har laddat ned och installerat snabbstartsprogrammet konfigureras det att använda en test-API-slutpunkt från Microsoft Graph. Vi måste ändra den genererade konfigurationsfilen så att den anropar API:et för PAT-livscykelhantering i stället.

Dricks

Vi använder samling och organisation omväxlande i dessa dokument. Om en konfigurationsvariabel behöver ett samlingsnamn ersätter du den med ditt organisationsnamn.

För att göra det måste vi göra några saker:

Uppdatera konfigurationsvariabeln ENDPOINT till https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview för API:erna för PAT-livscykelhantering
Uppdatera omfångskonfigurationsvariabeln till "499b84ac-1321-427f-aa17-267ca6975798/.default" för att referera till Azure DevOps-resursen och alla dess omfång.

I följande exempel visas hur vi gjorde den här konfigurationen för det Python Flask-snabbstartsprogram som vi genererade via Azure-portalen i föregående avsnitt.

Se till att du följer anvisningarna för att skydda klienthemligheten, som ursprungligen infogas i oformaterad text i programkonfigurationsfilen. Vi rekommenderar att du tar bort variabeln oformaterad text från konfigurationsfilen och använder en miljövariabel eller Azure KeyVault för att skydda programmets hemlighet.

I stället kan du välja att använda ett certifikat i stället för en klienthemlighet. Att använda certifikat är det rekommenderade alternativet om programmet så småningom ska användas i produktion. Anvisningarna för att använda ett certifikat finns i det sista steget i konfigurationen av snabbstartsprogrammet.

Varning

Lämna aldrig en klartextklienthemlighet i produktionsprogramkoden.

Exempel: Konfigurera ett Python Flask-snabbstartsprogram för API:et för livscykelhantering för PAT

När du har laddat ned snabbstartsprogrammet, installerat dess beroenden och testat att det körs i din miljö öppnar app_config.py du filen i valfri redigerare. Filen bör likna följande kodfragment. För tydlighetens skull har kommentarer som refererar till standardkonfigurationen för Microsoft Graph API tagits bort:

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

Uppdatera klient-ID:t eller klienthemligheten till ditt program med appregistreringens klient-ID och klienthemlighet. När du är i produktion måste du skydda klienthemligheten med hjälp av en miljövariabel, Azure KeyVault eller genom att växla till ett certifikat.
```
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.
```

Ändra variabeln ENDPOINT till din URL för Azure DevOps-samlingen och API-slutpunkten. För en samling med namnet "testCollection" skulle värdet till exempel vara:

# 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'

För en samling med namnet "testCollection" skulle den här slutpunkten vara:

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

Ändra variabeln SCOPE så att den refererar till Azure DevOps API-resursen. Teckensträngen är resurs-ID:t för Azure DevOps-API:et, och omfånget ".default" refererar till alla omfång för resurs-ID:t.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Om ditt program har konfigurerats för en specifik klientorganisation (i stället för konfigurationen för flera klientorganisationer) använder du det alternativa värdet för variabeln AUTHORITY och lägger till det specifika klientnamnet i "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"
```

Kontrollera att den sista app_config.py filen matchar följande, med din CLIENT_ID, klientorganisations-ID och samlingens URL. Av säkerhetsskäl kontrollerar du att CLIENT_SECRET har flyttats till en miljövariabel, Azure KeyVault eller växlats med ett certifikat för ditt registrerade program:

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

Kör programmet igen för att testa att du kan hämta alla PAT-token för den begärande användaren. När du har verifierat att du har gjort det kan du ändra innehållet i 'app.py' och 'ms-identity-python-webapp-master\templates' katalogen så att den stöder sändning av begäranden till resten av API-slutpunkterna för LIVSCYKELHANTERING FÖR PAT. Ett exempel på ett Python Flask-snabbstartsprogram som har ändrats för att stödja begäranden till alla API-slutpunkter för livscykelhantering för PAT finns i den här exempelrepoen på GitHub.

Uppdatera automatiskt en Microsoft Entra-åtkomsttoken

När programmet har konfigurerats korrekt och användaren har skaffat en åtkomsttoken kan token användas i upp till en timme. MSAL-koden som anges i båda exemplen ovan uppdaterar automatiskt token när den upphör att gälla. Om du uppdaterar token hindrar du användaren från att behöva logga in igen och hämta en ny auktoriseringskod. Användare kan dock behöva logga in igen efter 90 dagar när deras uppdateringstoken upphör att gälla.

Utforska API:et för PAT Lifecycle Management

I github-exempelprogrammet ovan och snabbstartsprogram har programmet förkonfigurerats för att göra begäranden med de Microsoft Entra-token som du har skaffat. Mer information om slutpunkterna, vilka parametrar de accepterar och vad som returneras i svar finns i API-referensdokumenten.

Vanliga frågor

F: Varför behöver jag autentisera med en Microsoft Entra-token? Varför räcker det inte med en PAT?

S: Med det här API:et för PAT Lifecycle Management har vi öppnat möjligheten att skapa nya PAT:er och återkalla befintliga PAT:er. I fel händer kan det här API:et användas av skadliga aktörer för att skapa flera startpunkter i organisationens ADO-resurser. Genom att framtvinga Microsoft Entra-autentisering hoppas vi att det här kraftfulla API:et ska vara säkrare mot den här obehöriga användningen.

F: Behöver jag ha en Microsoft Entra-klientorganisation med en aktiv Azure-prenumeration för att kunna använda det här API:et?

S: Tyvärr är det här API:et endast tillgängligt för användare som ingår i en Microsoft Entra-klientorganisation med en aktiv Azure-prenumeration.

F: Kan jag få ett exempel på det här exempelprogrammet för ett annat språk/ramverk/programtyp?

S: Vi älskar att du vill använda API:et på valfritt språk! Om du har en begäran om ett exempel går du till vår Dev Community för att se om någon annan har ett exempel att dela. Om du har ett exempelprogram som du vill dela till den större Azure DevOps-målgruppen kan du berätta för oss och vi kan titta närmare på hur vi cirkulerar det i dessa dokument i större utsträckning!

F: Vad är skillnaden mellan det här token-API:et och tokenadministratörs-API:et?

S: Det här token-API:et och tokenadministratörs-API:et, även om det är liknande, hanterar olika användningsfall och målgrupper:

Det här token-API:et är till stor del till för användare som vill hantera de PAT:er som de äger i en automatiserad pipeline. Det här API:et tillåter. Det ger dig möjlighet att skapa nya token och uppdatera befintliga.
API:et för tokenadministratör är avsett för organisationsadministratörer. Administratörer kan använda det här API:et för att hämta och återkalla OAuth-auktoriseringar, inklusive personliga åtkomsttoken (PAT) och självbeskrivande sessionstoken, för användare i deras organisationer.

F: Hur kan jag återskapa/rotera PAT via API:et? Jag såg det alternativet i användargränssnittet, men jag ser ingen liknande metod i API:et.

S: Bra fråga! Funktionen "Återskapa" som är tillgänglig i användargränssnittet utför faktiskt några åtgärder som är helt replikerbara via API:et.

Om du vill rotera din PAT måste du:

Förstå metadata för PAT med hjälp av ett GET-anrop ,
Skapa en ny PAT med den gamla PAT:ns metadata med hjälp av ett POST-anrop ,
Återkalla den gamla PAT med ett DELETE-anrop

F: Jag ser popup-fönstret "Behöver administratörsgodkännande" när jag försöker fortsätta med att använda den här appen. Hur kan jag använda den här appen utan administratörsgodkännande?

S: Det verkar som om din klientorganisation har angett säkerhetsprinciper som kräver att ditt program beviljas behörighet att komma åt resurser i organisationen. För närvarande är det enda sättet att fortsätta med att använda den här appen i den här klientorganisationen att be en administratör att bevilja behörighet till appen innan du kan använda den.

Nästa steg

Lär dig mer om API-slutpunkter för livscykelhantering för PAT