Verwalten von persönlichen Zugriffstoken (PATs) mithilfe der REST-API

Artikel
10/23/2023

Azure DevOps Services

Wenn Sie sich mit einer großen Gruppe von persönlichen Zugriffstoken (PERSONAL Access Tokens, PATs) beschäftigen, die Sie besitzen, kann es komplex werden, die Standard Tenanz dieser Token allein mithilfe der Benutzeroberfläche zu verwalten.

Mit der PAT-Lebenszyklusverwaltungs-API können Sie die PATs, die Ihren Organisationen zugeordnet sind, ganz einfach mithilfe automatisierter Prozesse verwalten. Mit diesem umfangreichen Satz von APIs können Sie die paTs verwalten, die Sie besitzen, sodass Sie neue persönliche Zugriffstoken erstellen und vorhandene persönliche Zugriffstoken erneuern oder ablaufen können.

In diesem Artikel erfahren Sie, wie Sie eine Anwendung konfigurieren, die sich mit einem Microsoft Entra-Token authentifiziert und Aufrufe mit der PAT-Lifecycle-API sendet. Wenn Sie nur die vollständige Liste der verfügbaren Endpunkte anzeigen möchten, sehen Sie sich hier die API-Referenz an.

Voraussetzungen

Um die API zu verwenden, müssen Sie sich mit einem Microsoft Entra-Token authentifizieren, das über Microsoft Entra ID OAuth erfolgen kann. Weitere Informationen hierzu finden Sie im folgenden Abschnitt zur Authentifizierung.

Dazu müssen einige Voraussetzungen erfüllt sein:

Sie müssen über einen Microsoft Entra-Mandanten mit einem aktiven Azure-Abonnement verfügen.
Je nach den Sicherheitsrichtlinien Ihres Mandanten muss Ihrer Anwendung möglicherweise Berechtigungen für den Zugriff auf Ressourcen in der Organisation erteilt werden. Derzeit besteht die einzige Möglichkeit, mit der Verwendung dieser App in diesem Mandanten fortzufahren, darin, einem Administrator die Berechtigung für die App zu erteilen, bevor Sie sie verwenden können.

Authentifizieren mit Microsoft Entra-Token

Im Gegensatz zu anderen Azure DevOps Services-APIs müssen Benutzer ein Microsoft Entra-Zugriffstoken bereitstellen, um diese API anstelle eines PAT-Tokens zu verwenden. Microsoft Entra-Token sind ein sichererer Authentifizierungsmechanismus als die Verwendung von PATs. Angesichts der Fähigkeit dieser API, PATs zu erstellen und zu widerrufen, möchten wir sicherstellen, dass solche leistungsstarken Funktionen nur Benutzern gewährt werden.

Um Microsoft Entra-Zugriffstoken zu erwerben und zu aktualisieren, müssen Sie:

Wichtig

Lösungen für "Im Auftrag von Anwendungen" (z. B. der Fluss "Clientanmeldeinformationen") und alle Authentifizierungsflüsse, die kein Microsoft Entra-Zugriffstoken ausgeben, sind für die Verwendung mit dieser API ungültig. Wenn die mehrstufige Authentifizierung in Ihrem Microsoft Entra-Mandanten aktiviert ist, müssen Sie unbedingt den Fluss "Autorisierungscode" verwenden.

Achtung

Ein Microsoft Entra-Mandant mit einem aktiven Azure-Abonnement ist eine Voraussetzung für die Verwendung dieser API.

Sobald Sie über eine Anwendung mit einem funktionierenden Authentifizierungsfluss für die Behandlung von Microsoft Entra-Token verfügen, können Sie diese Token verwenden, um Aufrufe an die PAT Lifecycle Management-API durchzuführen.

Um die API direkt aufzurufen, müssen Sie ein Microsoft Entra-Zugriffstoken als Bearer Token im Authorization Header Ihrer Anforderung bereitstellen. Die Beispiele und eine vollständige Liste der verfügbaren Anforderungen finden Sie in der PAT-API-Referenz.

Im folgenden Abschnitt zeigen wir Ihnen, wie Sie eine App erstellen, die einen Benutzer mit einem Microsoft Entra-Zugriffstoken mithilfe der MSAL-Bibliothek authentifiziert und unsere PAT Lifecycle Management-API aufruft.

Die Microsoft Authentication Library (MSAL) enthält mehrere kompatible Authentifizierungsflüsse, die Sie in Ihrer App zum Abrufen und Aktualisieren von Microsoft Entra-Token verwenden können. Eine vollständige Liste der MSAL-Flüsse finden Sie in der Dokumentation zur Microsoft-Authentifizierungsbibliothek "Authentifizierungsflüsse". Eine Anleitung zum Auswählen der richtigen Authentifizierungsmethode für Ihre Anwendung finden Sie unter Auswählen der richtigen Authentifizierungsmethode für Azure DevOps.

Folgen Sie einem der beiden Beispiele für die ersten Schritte:

Klonen Sie unsere Python Flask-Beispiel-App , und konfigurieren Sie sie mit Ihrem Mandanten und Ihrer ADO-Organisation.
Generieren Sie eine Beispielanwendung in der Azure-Portal für Ihre gewünschte Sprache, und konfigurieren Sie sie für die PAT Lifecycle Management-API.

Klonen sie unsere Python Flask Web App

Wir haben Ihnen eine Beispiel-Python Flask-Webanwendung für diese API bereitgestellt, die Sie auf GitHub herunterladen können und für die Verwendung mit Ihrem Microsoft Entra-Mandanten und Ihrer Azure DevOps-Organisation konfiguriert werden können. Die Beispielanwendung verwendet den MSAL-Authentifizierungscodefluss, um ein Microsoft Entra-Zugriffstoken abzurufen.

Wichtig

Es wird empfohlen, mit der Beispielwebanwendung Python Flask auf GitHub zu beginnen. Wenn Sie jedoch lieber eine andere Sprache oder einen anderen Anwendungstyp verwenden möchten, verwenden Sie die Schnellstartoption , um eine entsprechende Testanwendung neu zu erstellen.

Nachdem Sie die Beispiel-App geklont haben, folgen Sie den Anweisungen in der README-Datei des Repositorys. In README wird erläutert, wie Sie eine Anwendung in Ihrem Microsoft Entra-Mandanten registrieren, das Beispiel für die Verwendung Ihres Microsoft Entra-Mandanten konfigurieren und Ihre geklonte App ausführen.

Generieren einer Schnellstart-Azure-Portal-Anwendung

Stattdessen können Sie eine Beispiel-App mit dem generierten MSAL-Code mithilfe der Schnellstartoption auf der Seite der Anwendung in Azure-Portal generieren. Die Schnellstart-Testanwendung folgt dem Autorisierungscodefluss, jedoch mit einem Microsoft Graph-API-Endpunkt. Benutzer müssen die Konfiguration der Anwendung aktualisieren, um auf den Endpunkt für die PAT Lifecycle Management-API zu verweisen.

Um diesem Ansatz zu folgen, befolgen Sie die Schnellstartanleitungen für den Anwendungstyp Ihrer Wahl auf der Microsoft Entra ID Develop-Dokumentations-Homepage. Wir werden ein Beispiel durchgehen, in dem wir dies für eine Python Flask-Schnellstart-App getan haben.

Beispiel: Erste Schritte mit einer Python Flask-Schnellstartanwendung

Nachdem Sie Ihre Anwendung in einem Microsoft Entra-Mandanten registriert haben, der über ein aktives Azure-Abonnement verfügt, navigieren Sie zu Ihrer registrierten Anwendung unter Microsoft Entra ID ->App-Registrierungen im Azure-Portal.
Wählen Sie Ihre Anwendung aus, und navigieren Sie zu API-Berechtigungen.
Wählen Sie "Berechtigung hinzufügen" und dann "Azure DevOps" aus –> überprüfen Sie user_impersonation –> wählen Sie "Berechtigungen hinzufügen" aus.
Wählen Sie "Schnellstart " im linken Navigationsbereich aus.
Wählen Sie Ihren Anwendungstyp aus: Wählen Sie für Python Flask die Webanwendung aus.
Wählen Sie Ihre Anwendungsplattform aus. Wählen Sie für dieses Lernprogramm "Python" aus.
Stellen Sie sicher, dass Sie die erforderlichen Voraussetzungen erfüllt haben, und lassen Sie Azure-Portal die erforderlichen Änderungen vornehmen, um Ihre Anwendung zu konfigurieren. Die Antwort-URL ist die Umleitungs-URL, die bei der Anwendungserstellung + "/getAToken" festgelegt wurde.
Laden Sie die Schnellstartanwendung herunter, und extrahieren Sie die Dateien.
Installieren Sie die Anwendungsanforderungen, und führen Sie die Anwendung aus, um sicherzustellen, dass alle erforderlichen Abhängigkeiten vorhanden sind. Die Anwendung wird zunächst so konfiguriert, dass er auf einen Endpunkt in der Microsoft Graph-API trifft. Erfahren Sie, wie Sie diesen Endpunkt in den PAT Lifecycle Management API-Basisendpunkt ändern, indem Sie die Konfigurationsanweisungen im folgenden Abschnitt befolgen.

Konfigurieren einer Schnellstartanwendung

Nachdem der Benutzer die Schnellstartanwendung heruntergeladen und installiert hat, wird sie für die Verwendung eines Test-API-Endpunkts von Microsoft Graph konfiguriert. Wir müssen die generierte Konfigurationsdatei ändern, damit sie stattdessen die PAT Lifecycle Management-API aufruft.

Tipp

Wir verwenden Sammlung und Organisation austauschbar in diesen Dokumenten. Wenn eine Konfigurationsvariable einen Sammlungsnamen benötigt, ersetzen Sie sie bitte durch den Namen Ihrer Organisation.

Dazu müssen wir einige Dinge tun:

Aktualisieren der ENDPOINT-Konfigurationsvariable für https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview die PAT Lifecycle Management-APIs
Aktualisieren Sie die SCOPE-Konfigurationsvariable auf "499b84ac-1321-427f-aa17-267ca6975798/.default" , um auf die Azure DevOps-Ressource und alle zugehörigen Bereiche zu verweisen.

Im folgenden Beispiel wird gezeigt, wie wir diese Konfiguration für die Schnellstart-Python Flask-Anwendung ausgeführt haben, die wir über die Azure-Portal im vorherigen Abschnitt generiert haben.

Stellen Sie sicher, dass Sie die Anweisungen befolgen, um Ihren geheimen Clientschlüssel zu sichern, der anfänglich in nur-Text in die Anwendungskonfigurationsdatei eingefügt wird. Entfernen Sie als bewährte Methode die Nur-Text-Variable aus der Konfigurationsdatei, und verwenden Sie eine Umgebungsvariable oder Azure KeyVault, um den geheimen Schlüssel ihrer Anwendung zu sichern.

Stattdessen können Sie anstelle eines geheimen Clientschlüssels ein Zertifikat verwenden. Die Verwendung von Zertifikaten ist die empfohlene Option, wenn die Anwendung schließlich in der Produktion verwendet wird. Die Anweisungen für die Verwendung eines Zertifikats finden Sie im letzten Schritt der Schnellstartanwendungseinrichtung.

Achtung

Belassen Sie niemals einen Nur-Text-Clientschlüssel im Produktionsanwendungscode.

Beispiel: Konfigurieren einer Python Flask-Schnellstartanwendung für die PAT-Lifecycle-Verwaltungs-API

Nachdem Sie Ihre Schnellstartanwendung heruntergeladen, ihre Abhängigkeiten installiert und getestet haben, ob sie in Ihrer Umgebung ausgeführt wird, öffnen Sie die app_config.py Datei in Ihrem Editor der Wahl. Die Datei sollte dem folgenden Codeausschnitt ähneln. Aus Gründen der Übersichtlichkeit wurden Kommentare, die auf die Standardkonfiguration der Microsoft Graph-API verweisen, entfernt:

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

Aktualisieren Sie die Client-ID oder den geheimen Clientschlüssel ihrer Anwendung mit der Client-ID und dem geheimen Clientschlüssel Ihrer App-Registrierung. Achten Sie bei der Produktion darauf, den geheimen Clientschlüssel mithilfe einer Umgebungsvariablen, Azure KeyVault oder durch Wechseln zu einem Zertifikat zu sichern.
```
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.
```

Ändern Sie die ENDPOINT Variable in Ihre Azure DevOps-Sammlungs-URL und den API-Endpunkt. For example, for a collection named "testCollection", the value would be:

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

Bei einer Sammlung mit dem Namen "testCollection" lautet dieser Endpunkt wie folgt:

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

Ändern Sie die SCOPE Variable, um auf die Azure DevOps-API-Ressource zu verweisen. Die Zeichenfolge ist die Ressourcen-ID für die Azure DevOps-API, und der Bereich ".default" bezieht sich auf alle Bereiche für diese Ressourcen-ID.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Wenn Ihre Anwendung für einen bestimmten Mandanten (anstelle der Konfiguration mit mehreren Mandanten) konfiguriert ist, verwenden Sie den alternativen Wert für die AUTHORITY Variable, und fügen Sie den spezifischen Mandantennamen in "Enter_the_Tenant_Name_Here" hinzu.
```
# 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"
```

Stellen Sie sicher, dass die endgültige app_config.py Datei mit der folgenden Datei übereinstimmt, mit Ihrer CLIENT_ID, Mandanten-ID und Sammlungs-URL. Stellen Sie aus Sicherheitsgründen sicher, dass die CLIENT_SECRET in eine Umgebungsvariable, Azure KeyVault oder ein Zertifikat für Ihre registrierte Anwendung verschoben wurde:

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

Führen Sie die Anwendung erneut aus, um zu testen, dass Sie alle PAT-Token für den anfordernden Benutzer abrufen können. Nachdem Sie sich vergewissert haben, können Sie den Inhalt 'app.py' und das 'ms-identity-python-webapp-master\templates' Verzeichnis ändern, um das Senden von Anfragen an die restlichen PAT-Lifecycle-Verwaltungs-API-Endpunkte zu unterstützen. Ein Beispiel für eine Python Flask-Schnellstartanwendung, die geändert wurde, um Anforderungen an alle PAT-Lifecycle-Verwaltungs-API-Endpunkte zu unterstützen, finden Sie in diesem Beispiel-Repository auf GitHub.

Automatisches Aktualisieren eines Microsoft Entra-Zugriffstokens

Sobald die Anwendung ordnungsgemäß konfiguriert ist und der Benutzer ein Zugriffstoken erworben hat, kann das Token bis zu einer Stunde verwendet werden. Der in beiden Beispielen bereitgestellte MSAL-Code aktualisiert das Token automatisch, sobald es abläuft. Durch das Aktualisieren des Tokens wird verhindert, dass sich der Benutzer erneut anmelden muss und einen neuen Autorisierungscode erhält. Benutzer müssen sich jedoch möglicherweise nach ablaufen des Aktualisierungstokens nach ablaufen 90 Tagen erneut anmelden.

Erkunden der PAT Lifecycle Management-API

In der obigen GitHub-Beispielanwendung und Schnellstartanwendungen wurde die Anwendung vorkonfiguriert, um Anforderungen mit den von Ihnen erworbenen Microsoft Entra-Token zu stellen. Weitere Informationen zu den Endpunkten, zu welchen Parametern sie akzeptieren und was in Antworten zurückgegeben wird, finden Sie in den API-Referenzdokumenten.

Häufig gestellte Fragen

F: Warum muss ich mich mit einem Microsoft Entra-Token authentifizieren? Warum reicht ein PAT nicht aus?

A: Mit dieser PAT Lifecycle Management-API haben wir die Möglichkeit eröffnet, neue PATs zu erstellen und vorhandene PATs zu widerrufen. In den falschen Händen könnte diese API von böswilligen Akteuren verwendet werden, um mehrere Einstiegspunkte in die ADO-Ressourcen Ihrer Organisation zu erstellen. Durch die Erzwingung der Microsoft Entra-Authentifizierung hoffen wir, dass diese leistungsstarke API gegen diese nicht autorisierte Nutzung sicherer ist.

F: Muss ich über einen Microsoft Entra-Mandanten mit einem aktiven Azure-Abonnement verfügen, um diese API zu verwenden?

A: Leider ist diese API nur für Benutzer verfügbar, die Teil eines Microsoft Entra-Mandanten mit einem aktiven Azure-Abonnement sind.

F: Kann ich ein Beispiel für diese Beispielanwendung für einen anderen Sprach-/Framework-/Anwendungstyp erhalten?

A: Wir lieben es, dass Sie die API in Ihrer Wahlsprache verwenden möchten! Wenn Sie eine Anforderung für ein Beispiel haben, gehen Sie zu unserer Dev Community , um zu sehen, ob eine andere Person ein Beispiel für die Freigabe hat. Wenn Sie über eine Beispielanwendung verfügen, die Sie für die größere Azure DevOps-Zielgruppe freigeben möchten, teilen Sie uns diese mit, und wir können es in diesen Dokumenten weiterverbreiten!

F: Was ist der Unterschied zwischen dieser Token-API und der Tokenadministrator-API?

A: Diese Token-API und die Tokenadministrator-API dienen ähnlichen Anwendungsfällen und Zielgruppen:

Diese Token-API richtet sich weitgehend an Benutzer, die die PATs verwalten möchten, die sie in einer automatisierten Pipeline besitzen. Diese API lässt zu. Es bietet Ihnen die Möglichkeit, neue Token zu erstellen und vorhandene zu aktualisieren.
Die Token-Administrator-API ist für Organisationsadministratoren vorgesehen. Administratoren können diese API verwenden, um OAuth-Autorisierungen wie persönliche Zugriffstoken (PATs) und selbst beschreibende Sitzungstoken von Benutzern in ihren Organisationen abzurufen und zu widerrufen.

F: Wie kann ich PATs über die API neu generieren/drehen? Ich habe diese Option in der Benutzeroberfläche gesehen, aber ich sehe keine ähnliche Methode in der API.

A: Tolle Frage! Die in der Benutzeroberfläche verfügbare "Regenerate"-Funktion führt tatsächlich einige Aktionen durch, die vollständig replizierbar über die API sind.

Um Ihren PAT zu drehen, müssen Sie:

Grundlegendes zu den Metadaten des PAT mithilfe eines GET-Aufrufs
Erstellen Eines neuen PAT mit den Metadaten des alten PAT mithilfe eines POST-Aufrufs
Widerrufen des alten PAT mithilfe eines DELETE-Aufrufs

F: Ich sehe ein Popup "Administratorgenehmigung benötigen", wenn ich versuche, diese App zu verwenden. Wie kann ich diese App ohne Administratorgenehmigung verwenden?

A: Es scheint, dass Ihr Mandant Sicherheitsrichtlinien festgelegt hat, für die Ihre Anwendung Berechtigungen für den Zugriff auf Ressourcen in der Organisation erteilt werden muss. Derzeit besteht die einzige Möglichkeit, mit der Verwendung dieser App in diesem Mandanten fortzufahren, darin, einem Administrator die Berechtigung für die App zu erteilen, bevor Sie sie verwenden können.

Nächste Schritte

Informationen zu den PAT-Lifecycle-Verwaltungs-API-Endpunkten