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) 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 ett program som autentiserar med en Microsoft Entra-token och gör anrop med PAT-livscykel-API:et.

Viktigt!

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

Förutsättningar

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. 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 är tillgängliga för säkrare Microsoft Entra-token.

Om du vill hämta och uppdatera Microsoft Entra-åtkomsttoken måste du göra följande:

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 Microsoft Authentication Library (MSAL) och anropar vårt API för pat-livscykelhantering.

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-auktoriseringskodflöde 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.

  1. När du har registrerat ditt program i en Microsoft Entra-klientorganisation med en aktiv Azure-prenumeration går du till ditt registrerade program under Microsoft Entra-ID –>appregistreringar i Azure-portalen.

    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 –> välja lämpliga omfång som du behöver. I det här fallet stöder API:erna för PAT-livscykelhantering endast user_impersonation, men andra API:er kan begära olika mer detaljerade omfång som du kan hitta på varje API:s enskilda referenssida. När alla omfång har valts klickar du på 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.

  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.

Vanliga frågor (FAQ)

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

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?

Det här token-API:et och tokenadministratörs-API:et, men 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.

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?

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.