Persoonlijke toegangstokens (PAT's) beheren met behulp van REST API

Artikel
10/24/2024

Azure DevOps Services

Wanneer u te maken hebt met een grote set persoonlijke toegangstokens (PAT's) waarvan u eigenaar bent, kan het complex worden om het onderhoud van deze tokens alleen te beheren met behulp van de gebruikersinterface.

Met de PAT Lifecycle Management-API kunt u eenvoudig de PAT's beheren die aan uw organisaties zijn gekoppeld met behulp van geautomatiseerde processen. Met deze uitgebreide set API's kunt u uw PAW's beheren, zodat u nieuwe PAT's kunt maken en bestaande PAW's kunt vernieuwen of laten verlopen.

In dit artikel wordt uitgelegd hoe u een toepassing configureert die wordt geverifieerd met een Azure Microsoft Entra-token aanroepen uitvoert met de PAT Lifecycle-API. Als u alleen de volledige lijst met beschikbare eindpunten wilt zien, bekijkt u hier de API-verwijzing.

Vereisten

Machtigingen: afhankelijk van het beveiligingsbeleid van uw tenant heeft uw toepassing mogelijk machtigingen nodig voor toegang tot resources in de organisatie. Op dit moment is het alleen mogelijk om door te gaan met het gebruik van deze app in deze tenant door een beheerder te vragen om toestemming te verlenen aan de app voordat u deze kunt gebruiken.

Verificatie:
- Als u de API wilt gebruiken, moet u zich verifiëren met een Microsoft Entra-token via Microsoft Entra ID OAuth. Zie de sectie Verificatie voor meer informatie.
- Een Microsoft Entra-tenant met een actief Azure-abonnement hebben.

Notitie

U kunt geen service-principals of beheerde identiteiten gebruiken om PAW's te maken of in te trekken.

Verifiëren met Microsoft Entra-tokens

In tegenstelling tot andere Azure DevOps Services-API's moeten gebruikers een Microsoft Entra-toegangstoken opgeven om deze API te gebruiken in plaats van een PAT. Microsoft Entra-tokens zijn een veiliger verificatiemechanisme dan het gebruik van PAW's. Gezien de mogelijkheid van deze API om PAW's te maken en in te trekken, willen we ervoor zorgen dat dergelijke krachtige functionaliteit alleen aan toegestane gebruikers wordt verleend.

Voer de volgende taken uit om Microsoft Entra-toegangstokens te verkrijgen en te vernieuwen:

Belangrijk

'On-behalf-of-application'-oplossingen (zoals de stroom voor clientreferenties) en elke verificatiestroom die geen Microsoft Entra-toegangstoken geeft, is niet geldig voor gebruik met deze API. Als meervoudige verificatie is ingeschakeld in uw Microsoft Entra-tenant, moet u zeker de stroom autorisatiecode gebruiken.

Zodra u een toepassing hebt met een werkende verificatiestroom voor het verwerken van Microsoft Entra-tokens, kunt u deze tokens gebruiken om aanroepen te doen naar de PAT Lifecycle Management-API.

Als u de API rechtstreeks wilt aanroepen, geeft u een Microsoft Entra-toegangstoken op als een Bearer token in Authorization de header van uw aanvraag. Zie de PAT API-verwijzing voor meer informatie en een volledige lijst met beschikbare aanvragen.

In de volgende sectie laten we zien hoe u een app maakt waarmee een gebruiker wordt geverifieerd met een Microsoft Entra-toegangstoken. De app maakt gebruik van de MSAL-bibliotheek (Microsoft Authentication Library) en roept onze PAT Lifecycle Management-API aan.

De MSAL bevat meerdere compatibele verificatiestromen die u in uw app kunt gebruiken voor het verkrijgen en vernieuwen van Microsoft Entra-tokens. Een volledige lijst met MSAL-stromen vindt u in de documentatie over verificatiestromen van Microsoft Authentication Library. Een handleiding voor het kiezen van de juiste verificatiemethode voor uw toepassing vindt u onder Het kiezen van de juiste verificatiemethode voor Azure DevOps.

Zie een van de volgende voorbeelden om aan de slag te gaan:

Kloon onze Python Flask-voorbeeld-app en configureer deze met uw tenant en ADO-organisatie
Genereer een voorbeeldtoepassing in Azure Portal voor uw keuzetaal en configureer deze voor de PAT Lifecycle Management-API

Onze Python Flask-web-app klonen

We hebben u een voorbeeld van een Python Flask-webtoepassing voor deze API geleverd die u kunt downloaden op GitHub en kunt configureren voor gebruik met uw Microsoft Entra-tenant en Azure DevOps-organisatie. De voorbeeldtoepassing maakt gebruik van de MSAL-verificatiecodestroom om een Microsoft Entra-toegangstoken te verkrijgen.

Belangrijk

We raden u aan om aan de slag te gaan met de Python Flask-webtoepassing op GitHub, maar als u liever een andere taal of toepassingstype gebruikt, gebruikt u de quickstart-optie om een equivalente testtoepassing opnieuw te maken.

Zodra u de voorbeeld-app hebt gekloond, volgt u de instructies in het LEESMIJ-bestand van de opslagplaats. In readme wordt uitgelegd hoe u een toepassing registreert in uw Microsoft Entra-tenant, het voorbeeld configureert voor het gebruik van uw Microsoft Entra-tenant en hoe u uw gekloonde app uitvoert.

Een Quickstart-toepassing in De Azure-portal genereren

In plaats daarvan kunt u een voorbeeld-app genereren met de gegenereerde MSAL-code met behulp van de quickstartoptie op de pagina van de toepassing in Azure Portal. De quickstart-testtoepassing volgt de autorisatiecodestroom, maar doet dit met een Microsoft Graph API-eindpunt. Gebruikers moeten de configuratie van de toepassing bijwerken om te verwijzen naar het eindpunt voor de PAT Lifecycle Management-API.

Als u deze aanpak wilt volgen, volgt u de quickstarts-instructies voor het toepassingstype van uw keuze op de startpagina van Microsoft Entra ID Develop docs. We doorlopen het volgende voorbeeld met een Python Flask-quickstart-app.

Voorbeeld: Aan de slag met een Python Flask-snelstarttoepassing

Nadat u uw toepassing hebt geregistreerd in een Microsoft Entra-tenant met een actief Azure-abonnement, gaat u naar uw geregistreerde toepassing onder Microsoft Entra ID ->App-registraties in de Azure-portal.
Selecteer uw toepassing en navigeer naar API-machtigingen.
Selecteer Een machtiging toevoegen en selecteer Azure DevOps -> controleer user_impersonation -> selecteer Machtigingen toevoegen.
Selecteer Quickstart.
Selecteer uw toepassingstype: selecteer voor Python Flask de webtoepassing.
Selecteer uw toepassingsplatform. Voor deze zelfstudie selecteert u Python.
Zorg ervoor dat u voldoet aan de vereiste vereisten en sta vervolgens Azure Portal toe om de benodigde wijzigingen aan te brengen om uw toepassing te configureren. De antwoord-URL is de omleidings-URL die is ingesteld bij het maken van de toepassing + /getAToken.
Download de quickstart-toepassing en pak de bestanden uit.
Installeer de toepassingsvereisten en voer de toepassing uit om ervoor te zorgen dat u alle benodigde afhankelijkheden hebt. De toepassing is in eerste instantie geconfigureerd om een eindpunt in de Microsoft Graph API te bereiken. Meer informatie over het wijzigen van dit eindpunt in het basiseindpunt van de PAT Lifecycle Management-API door de configuratie-instructies in de volgende sectie te volgen.

Een quickstart-toepassing configureren

Zodra de gebruiker de quickstart-toepassing downloadt en installeert, wordt deze geconfigureerd voor het gebruik van een test-API-eindpunt van Microsoft Graph. Wijzig het gegenereerde configuratiebestand zodat het in plaats daarvan de PAT Lifecycle Management-API aanroept.

Tip

We gebruiken verzameling en organisatie door elkaar in deze documenten. Als een configuratievariabele een verzamelingsnaam nodig heeft, vervangt u deze door de naam van uw organisatie.

Ga als volgt te werk:

De eindpuntconfiguratievariabele bijwerken naar https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview de PAT Lifecycle Management-API's
Werk de scope-configuratievariabele bij naar '499b84ac-1321-427f-aa17-267ca6975798/.default' om te verwijzen naar de Azure DevOps-resource en alle bijbehorende bereiken.

In het volgende voorbeeld ziet u hoe we deze configuratie hebben uitgevoerd voor de Python Flask-toepassing quickstart die we in de vorige sectie hebben gegenereerd via Azure Portal.

Zorg ervoor dat u de instructies volgt om uw clientgeheim te beveiligen. Dit wordt in eerste instantie ingevoegd in tekst zonder opmaak in het configuratiebestand van de toepassing. Als best practice verwijdert u de variabele zonder opmaak uit het configuratiebestand en gebruikt u een omgevingsvariabele of Azure KeyVault om het geheim van de toepassing te beveiligen.

In plaats daarvan kunt u ervoor kiezen om een certificaat te gebruiken in plaats van een clientgeheim. Het gebruik van certificaten is de aanbevolen optie als de toepassing wordt gebruikt in productie. De instructies voor het gebruik van een certificaat vindt u in de laatste stap van de installatie van de quickstart-toepassing.

Let op

Laat nooit een clientgeheim zonder opmaak achter in de code van de productietoepassing.

Voorbeeld: Een Python Flask-quickstarttoepassing configureren voor de API voor levenscyclusbeheer van PAT

Nadat u de quickstart-toepassing hebt gedownload, installeert u de bijbehorende afhankelijkheden en test u of deze wordt uitgevoerd in uw omgeving, opent u het app_config.py bestand in de gewenste editor. Het bestand moet lijken op het volgende codefragment; Ter duidelijkheid zijn opmerkingen die verwijzen naar de standaardconfiguratie van De Microsoft Graph API verwijderd:

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

Werk de client-id of het clientgeheim bij naar uw toepassing met de client-id en het clientgeheim van uw app-registratie. Wanneer u in productie bent, moet u ervoor zorgen dat u het clientgeheim beveiligt met behulp van een omgevingsvariabele, Azure KeyVault of door over te schakelen naar een certificaat.
```
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.
```

Wijzig de variabele in de ENDPOINT URL van uw Azure DevOps-verzameling en API-eindpunt. Voor een verzameling met de naam 'testCollection' is de waarde bijvoorbeeld:

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

Voor een verzameling met de naam testCollection is dit eindpunt:

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

Wijzig de SCOPE variabele om te verwijzen naar de Azure DevOps-API-resource. De tekenreeks is de resource-id voor de Azure DevOps-API en het .default bereik verwijst naar alle bereiken voor die resource-id.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Als uw toepassing is geconfigureerd voor een specifieke tenant (in plaats van de configuratie met meerdere tenants), gebruikt u de alternatieve waarde voor de AUTHORITY variabele, waarbij u de specifieke tenantnaam toevoegt in '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"
```

Controleer of het uiteindelijke app_config.py bestand overeenkomt met het volgende, met uw CLIENT_ID, tenant-id en verzamelings-URL. Zorg er om veiligheidsredenen voor dat de CLIENT_SECRET is verplaatst naar een omgevingsvariabele, Azure KeyVault of is gewisseld met een certificaat voor uw geregistreerde toepassing:

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

Voer de toepassing opnieuw uit om te testen of u alle PAT-tokens voor de aanvragende gebruiker kunt ophalen. Zodra dit is geverifieerd, kunt u de inhoud van 'app.py' en de 'ms-identity-python-webapp-master\templates' directory wijzigen ter ondersteuning van het verzenden van aanvragen naar de rest van de API-eindpunten voor levenscyclusbeheer van PAT. Zie deze voorbeeldopslagplaats op GitHub voor een voorbeeld van een Python Flask-quickstarttoepassing die is gewijzigd ter ondersteuning van aanvragen voor alle API-eindpunten voor levenscyclusbeheer van PAT.

Automatisch een Microsoft Entra-toegangstoken vernieuwen

Zodra de toepassing correct is geconfigureerd en de gebruiker een toegangstoken heeft verkregen, kan het token maximaal een uur worden gebruikt. De MSAL-code in beide vorige voorbeelden vernieuwt het token automatisch zodra het is verlopen. Als u het token vernieuwt, voorkomt u dat de gebruiker zich opnieuw moet aanmelden en een nieuwe autorisatiecode moet verkrijgen. Gebruikers moeten zich echter mogelijk na 90 dagen opnieuw aanmelden zodra hun vernieuwingstoken is verlopen.

PAT Lifecycle Management API's verkennen

In de vorige GitHub-voorbeeldtoepassing en Quickstart-toepassingen is de toepassing vooraf geconfigureerd om aanvragen te doen met de Microsoft Entra-tokens die u hebt verkregen. Zie de API-referentiedocumenten voor meer informatie.

Veelgestelde vragen (FAQ's)

V: Waarom moet ik me verifiëren met een Microsoft Entra-token? Waarom is een PAT niet genoeg?

A: Met deze PAT Lifecycle Management-API hebben we de mogelijkheid geopend om nieuwe PAT's te maken en bestaande PAT's in te trekken. In de verkeerde handen kunnen kwaadwillende actoren deze API gebruiken om meerdere toegangspunten te maken in de Azure DevOps-resources van uw organisatie. Door Microsoft Entra-verificatie af te dwingen, hopen we dat deze krachtige API veiliger is tegen dit niet-geautoriseerde gebruik.

V: Moet ik een Microsoft Entra-tenant met een actief Azure-abonnement hebben om deze API te kunnen gebruiken?

A: Helaas is deze API alleen beschikbaar voor gebruikers die deel uitmaken van een Microsoft Entra-tenant met een actief Azure-abonnement.

V: Kan ik een voorbeeld krijgen van deze voorbeeldtoepassing voor een andere taal/framework/toepassingstype?

A: We houden ervan dat u de API in uw gewenste taal wilt gebruiken. Als u een voorbeeldaanvraag hebt, gaat u naar onze Dev Community om te zien of iemand anders een voorbeeld heeft om te delen. Als u een voorbeeldtoepassing hebt die u wilt delen met de grotere Azure DevOps-doelgroep, laat het ons dan weten en we kunnen de toepassing op deze documenten breder verspreiden.

V: Wat is het verschil tussen deze token-API en de tokenbeheerders-API?

A: Deze token-API en de tokenbeheerders-API, terwijl vergelijkbare, verschillende use cases en doelgroepen dienen:

Deze token-API is grotendeels bedoeld voor gebruikers die de PAW's willen beheren die ze bezitten in een geautomatiseerde pijplijn. Met deze API is dit toegestaan. Het biedt u de mogelijkheid om nieuwe tokens te maken en bestaande tokens bij te werken.
De tokenbeheerders-API is bedoeld voor organisatiebeheerders. Beheerders kunnen deze API gebruiken om OAuth-autorisaties op te halen en in te trekken, waaronder persoonlijke toegangstokens (PAT's) en zelfbeschrijfde sessietokens, van gebruikers in hun organisaties.

V: Hoe kan ik PAT's opnieuw genereren/draaien via de API? Ik zag die optie in de gebruikersinterface, maar ik zie geen vergelijkbare methode in de API.

A: Geweldige vraag! De functionaliteit 'Opnieuw genereren' die beschikbaar is in de gebruikersinterface, voert een aantal acties uit, die volledig repliceerbaar zijn via de API.

Voer de volgende stappen uit om uw PAT te draaien:

Inzicht krijgen in de metagegevens van de PAT met behulp van een GET-aanroep .
Maak een nieuwe PAT met de metagegevens van de oude PAT met behulp van een POST-aanroep .
De oude PAT intrekken met behulp van een DELETE-aanroep

V: Ik zie het pop-upvenster 'Beheerdersgoedkeuring nodig' wanneer ik probeer door te gaan met het gebruik van deze app. Hoe kan ik deze app gebruiken zonder goedkeuring van de beheerder?

A: Het lijkt erop dat uw tenant beveiligingsbeleid heeft, waarvoor uw toepassing machtigingen moet krijgen voor toegang tot resources in de organisatie. Op dit moment is het alleen mogelijk om door te gaan met het gebruik van deze app in deze tenant door een beheerder te vragen om toestemming te verlenen aan de app voordat u deze kunt gebruiken.

V: Waarom krijg ik een foutmelding zoals 'Service-principals mogen deze actie niet uitvoeren' wanneer ik de PAT Lifecycle Management-API probeer aan te roepen met behulp van een service-principal of beheerde identiteit?

A: Service-principals en beheerde identiteiten zijn niet toegestaan. Gezien de mogelijkheid van deze API om PAW's te maken en in te trekken, willen we ervoor zorgen dat dergelijke krachtige functionaliteit alleen aan toegestane gebruikers wordt verleend.

Volgende stappen

Meer informatie over de API-eindpunten voor pat-levenscyclusbeheer

Delen via