Dela via

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

  • Artikel

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 dina PAT:er så att du kan skapa nya PAT:er och förnya eller upphöra att gälla befintliga PAT:er.

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

Förutsättningar

  • Behörigheter: Beroende på klientorganisationens säkerhetsprinciper kan programmet behöva 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.

Kommentar

Du kan inte använda tjänstens huvudnamn eller hanterade identiteter för att skapa eller återkalla PAT:er.

Autentisera med Microsoft Entra-token

Till skillnad från andra API:er för Azure DevOps Services måste användarna tillhandahålla en Microsoft Entra-åtkomsttoken för att använda det här API:et i stället för en PAT. 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.

Utför följande uppgifter för att hämta och uppdatera Microsoft Entra-åtkomsttoken:

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".

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.

Om du vill anropa API:et direkt anger du en Microsoft Entra-åtkomsttoken som en Bearer token i rubriken för Authorization din begäran. Mer information och en fullständig lista över tillgängliga begäranden finns i PAT API-referensen .

I följande avsnitt visar vi hur du skapar en app som autentiserar en användare med en Microsoft Entra-åtkomsttoken. Appen använder MSAL-biblioteket (Microsoft Authentication Library) och anropar vårt API för PAT Lifecycle Management.

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 om autentiseringsflöden för 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.

Kom igång genom att se något av följande exempel:

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 konfigurera 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.

Generera en snabbstart Azure Portal program

I stället kan du generera en exempelapp med den genererade MSAL-koden med hjälp av snabbstartsalternativet på programmets sida i Azure Portal. 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 följande exempel med en Snabbstartsapp för Python Flask.

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

  1. 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 Portal.

    Skärmbild som visar öppnat Microsoft Entra-ID, appregistreringar.

  2. Välj ditt program och gå till API-behörigheter.

    Skärmbild som visar hur du väljer ett program och navigerar till API-behörigheter.

  3. Välj Lägg till en behörighet och välj Azure DevOps –> kontrollera user_impersonation –> välj Lägg till behörigheter.

    Skärmbild som visar hur du lägger till Behörigheten Azure DevOps user_impersonation.

  4. Välj Snabbstart.

  5. Välj din programtyp: För Python Flask väljer du Webbprogram.

  6. Välj din programplattform. I den här självstudien väljer du Python.

  7. Se till att du uppfyller de nödvändiga kraven och låt sedan Azure Portal göra de ändringar som krävs för att konfigurera programmet. Svars-URL :en är den omdirigerings-URL som angavs när programmet skapades + "/getAToken".

    Skärmbild som visar hur Azure Portal kan göra de ändringar som krävs för att konfigurera programmet.

  8. Ladda ned snabbstartsprogrammet och extrahera filerna.

    Skärmbild som visar hur du laddar ned snabbstartsprogrammet och extraherar filerna.

  9. 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.

    Skärmbild som visar hur du installerar programkraven och kör programmet.

Konfigurera ett snabbstartsprogram

När användaren laddar ned och installerar snabbstartsprogrammet konfigureras det att använda en test-API-slutpunkt från Microsoft Graph. Ändra den genererade konfigurationsfilen så att den anropar API:et för 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.

Utför följande uppgifter:

  1. 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
  2. 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 Portal 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 används 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

  1. När du har hämtat 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

  2. 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.

  3. Ä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'

  4. Ändra variabeln SCOPE så att den refererar till Azure DevOps API-resursen. Teckensträngen är resurs-ID:t för Azure DevOps API och omfånget .default refererar till alla omfång för resurs-ID:t.

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

  5. Om ditt program har konfigurerats för en specifik klientorganisation (i stället för konfigurationen för flera klienter) 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"

  6. 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

  7. 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 det kan du ändra innehållet i 'app.py' och katalogen så att det 'ms-identity-python-webapp-master\templates' stöder sändning av begäranden till resten av API-slutpunkterna för PAT-livscykelhantering. 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 föregående exempel 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 skaffa 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:er för PAT-livscykelhantering

I föregående GitHub-exempelprogram och snabbstartsprogram är programmet förkonfigurerat för att göra begäranden med De Microsoft Entra-token som du har köpt. Mer information finns i API-referensdokumenten.

Vanliga frågor (FAQ)

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-livscykelhantering öppnade vi möjligheten att skapa nya PAT:er och återkalla befintliga PAT:er. I fel händer kan skadliga aktörer använda det här API:et för att skapa flera startpunkter i organisationens Azure DevOps-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.

Gör följande för att rotera pat:en:

  1. Förstå metadata för PAT med hjälp av ett GET-anrop ,
  2. Skapa en ny PAT med den gamla PAT:ns metadata med hjälp av ett POST-anrop ,
  3. Å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 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.

F: Varför visas ett fel som "Tjänstens huvudnamn tillåts inte utföra den här åtgärden" när jag försöker anropa API:et för pat-livscykelhantering med hjälp av ett tjänsthuvudnamn eller en hanterad identitet?

S: Tjänstens huvudnamn och hanterade identiteter är inte tillåtna. 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.

Nästa steg

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