Freigeben über

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

  • Artikel

Azure DevOps Services

Wenn Sie sich mit einer großen Gruppe von persönlichen Zugriffstoken (PERSONAL Access Tokens, PATs) befassen, die Sie besitzen, kann es komplex werden, die Wartung 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 Ihre PATs verwalten, sodass Sie neue PATs erstellen und vorhandene PATs erneuern oder ablaufen können.

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

Voraussetzungen

  • Berechtigungen: Abhängig von den Sicherheitsrichtlinien Ihres Mandanten benötigt Ihre Anwendung möglicherweise Berechtigungen für den Zugriff auf Ressourcen in der Organisation. Derzeit besteht die einzige Möglichkeit, mit der Verwendung dieser App in diesem Mandanten fortzufahren, darin, einen Administrator aufzufordern, die Berechtigung für die App zu erteilen, bevor Sie sie verwenden können.

Hinweis

Sie können keine Dienstprinzipale oder verwalteten Identitäten verwenden, um PATs zu erstellen oder zu widerrufen.

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

Führen Sie die folgenden Aufgaben aus, um Microsoft Entra-Zugriffstoken zu erwerben und zu aktualisieren:

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.

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, stellen Sie ein Microsoft Entra-Zugriffstoken als Bearer Token in Authorization der Kopfzeile Ihrer Anforderung bereit. Weitere Informationen und eine vollständige Liste der verfügbaren Anforderungen finden Sie in der PAT-API-Referenz.

Im folgenden Abschnitt wird gezeigt, wie Sie eine App erstellen, die einen Benutzer mit einem Microsoft Entra-Zugriffstoken authentifiziert. Die App verwendet die Microsoft Authentication Library (MSAL)-Bibliothek und ruft unsere PAT-Lifecycle-Verwaltungs-API auf.

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 zu Authentifizierungsflüssen der Microsoft-Authentifizierungsbibliothek. Eine Anleitung zum Auswählen der richtigen Authentifizierungsmethode für Ihre Anwendung finden Sie unter Auswählen der richtigen Authentifizierungsmethode für Azure DevOps.

Informationen zu den ersten Schritten finden Sie in einem der folgenden Beispiele:

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 und für die Verwendung mit Ihrem Microsoft Entra-Mandanten und Ihrer Azure DevOps-Organisation konfigurieren 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 führen das folgende Beispiel mit einer Python Flask Schnellstart-App durch.

Beispiel: Erste Schritte mit einer Python Flask-Schnellstartanwendung

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

    Screenshot zeigt geöffnete Microsoft Entra-ID, App-Registrierungen.

  2. Wählen Sie Ihre Anwendung aus, und navigieren Sie zu API-Berechtigungen.

    Screenshot zeigt die Auswahl einer Anwendung und navigieren zu API-Berechtigungen.

  3. Wählen Sie "Berechtigung hinzufügen" und dann "Azure DevOps" aus –> überprüfen Sie user_impersonation –> wählen Sie "Berechtigungen hinzufügen" aus.

    Screenshot: Hinzufügen der Azure DevOps-Berechtigung user_impersonation.

  4. Wählen Sie "Schnellstart" aus.

  5. Wählen Sie Ihren Anwendungstyp aus: Wählen Sie für Python Flask die Webanwendung aus.

  6. Wählen Sie Ihre Anwendungsplattform aus. Wählen Sie für dieses Tutorial die Option Python aus.

  7. Stellen Sie sicher, dass Sie die erforderlichen Voraussetzungen erfüllen, 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.

    Screenshot zeigt, wie der Azure-Portal die erforderlichen Änderungen vornehmen kann, um Ihre Anwendung zu konfigurieren.

  8. Laden Sie die Schnellstartanwendung herunter, und extrahieren Sie die Dateien.

    Screenshot des Downloads der Schnellstartanwendung und Extrahieren der Dateien.

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

    Der Screenshot zeigt die Installation der Anwendungsanforderungen und das Ausführen der Anwendung.

Konfigurieren einer Schnellstartanwendung

Sobald der Benutzer die Schnellstartanwendung herunterlädt und installiert hat, wird er für die Verwendung eines Api-Testendpunkts von Microsoft Graph konfiguriert. Ändern Sie die generierte Konfigurationsdatei so, dass sie stattdessen die PAT-Lifecycle-Verwaltungs-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.

Führen Sie die folgenden Aufgaben aus:

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

  1. Nachdem Sie Ihre Schnellstartanwendung heruntergeladen haben, installieren Sie die Abhängigkeiten, und testen Sie, 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

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

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

    Für eine 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'

  4. Ä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 .default Bereich bezieht sich auf alle Bereiche für diese Ressourcen-ID.

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

  5. Wenn Ihre Anwendung für einen bestimmten Mandanten (anstelle der multitenanten Konfiguration) 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"

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

  7. Führen Sie die Anwendung erneut aus, um zu testen, dass Sie alle PAT-Token für den anfordernden Benutzer abrufen können. Nach der Überprüfung können Sie den Inhalt 'app.py' und das 'ms-identity-python-webapp-master\templates' Verzeichnis ändern, um das Senden von Anforderungen 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 wurde und der Benutzer ein Zugriffstoken erworben hat, kann das Token bis zu einer Stunde verwendet werden. Der in beiden vorherigen Beispielen bereitgestellte MSAL-Code aktualisiert das Token automatisch, sobald es abläuft. Durch das Aktualisieren des Tokens wird verhindert, dass sich der Benutzer erneut anmeldet und einen neuen Autorisierungscode erhält. Benutzer müssen sich jedoch möglicherweise nach ablaufen des Aktualisierungstokens nach 90 Tagen erneut anmelden.

Erkunden von PAT Lifecycle Management-APIs

In der vorherigen GitHub-Beispielanwendung und Schnellstartanwendungen ist die Anwendung vorkonfiguriert, um Anforderungen mit den von Ihnen erworbenen Microsoft Entra-Token zu stellen. Weitere Informationen finden Sie in den API-Referenzdokumenten.

Häufig gestellte Fragen (FAQs)

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 geöffnet, neue PATs zu erstellen und vorhandene PATs zu widerrufen. In den falschen Händen könnten böswillige Akteure diese API verwenden, um mehrere Einstiegspunkte in die Azure DevOps-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"-Funktionalität führt tatsächlich einige Aktionen durch, die vollständig replizierbar über die API sind.

Führen Sie die folgenden Schritte aus, um Ihren PAT zu drehen:

  1. Grundlegendes zu den Metadaten des PAT mithilfe eines GET-Aufrufs
  2. Erstellen Eines neuen PAT mit den Metadaten des alten PAT mithilfe eines POST-Aufrufs
  3. 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 Über Sicherheitsrichtlinien verfügt, 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.

F: Warum wird ein Fehler wie "Dienstprinzipale dürfen diese Aktion nicht ausführen" angezeigt werden, wenn ich versuche, die PAT Lifecycle Management-API mit einem Dienstprinzipal oder einer verwalteten Identität aufzurufen?

A: Dienstprinzipale und verwaltete Identitäten sind nicht zulässig. 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.

Nächste Schritte

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