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

Azure DevOps Services

Wenn Sie einen großen Satz persönlicher Zugriffstoken (PATs) besitzen, kann es komplex werden, die Wartung dieser Token allein über die 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 umfassenden Satz von APIs können Sie Ihre PATs verwalten, sodass Sie neue PATs erstellen und vorhandene PATs erneuern oder ablaufen können.

In diesem Artikel zeigen wir Ihnen, wie Sie eine Anwendung konfigurieren, die sich mit einem Microsoft Entra-Token authentifiziert und Aufrufe mit der PAT-Lebenszyklus-API tätigt.

Voraussetzungen

Um diese API zu verwenden, müssen Benutzer im Gegensatz zu anderen Azure DevOps Services-APIs ein Microsoft Entra-Zugriffstoken bereitstellen. Angesichts der Fähigkeit dieser API, PATs zu erstellen und zu widerrufen, möchten wir sicherstellen, dass solche leistungsstarken Funktionen nur für sicherere Microsoft Entra-Token verfügbar sind.

Um Microsoft Entra-Zugriffstoken zu erhalten und zu aktualisieren, müssen Sie Folgendes tun:

• Einen Microsoft Entra-Mandanten mit einem aktiven Azure-Abonnement haben
• Registrieren einer Anwendung in ihrem Microsoft Entra-Mandanten
• Hinzufügen von Azure DevOps-Berechtigungen zur Anwendung
• Holen Sie die Zustimmung vom Admin des Mandanten ein: Je nach den Sicherheitsrichtlinien Ihres Mandanten benötigt Ihre Anwendung möglicherweise Berechtigungen für den Zugriff auf Ressourcen in der Organisation. Fordern Sie einen Mandantenadministrator auf, der der App die Berechtigung erteilt, sie in Ihrem Mandanten zu 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) und ruft unsere PAT Lifecycle Management API auf.

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 Beispiel-App verwendet den MSAL-Autorisierungscode-Flow, um ein Microsoft Entra-Zugriffstoken zu erhalten.

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.

1. Sobald Sie Ihre App in einem Microsoft Entra-Mandant mit einem aktiven Azure-Abonnement registriert haben, navigieren Sie zu Ihrer registrierten App unter Microsoft Entra ID ->App Registrations im Azure-Portal.

   

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

   

3. Wählen Sie Berechtigung hinzufügen und Azure DevOps –> wählen Sie die gewünschten Bereiche aus. In diesem Fall unterstützen die PAT-Lebenszyklusverwaltung-APIs nur user_impersonation, andere APIs fordern jedoch möglicherweise unterschiedliche granulare Bereiche an, die Sie auf einzelnen Referenzseiten jeder API finden können. Nachdem alle Zugriffsbereiche ausgewählt wurden, klicken Sie auf Berechtigungen hinzufügen.

   

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.

   

8. Laden Sie die Schnellstartanwendung herunter, und extrahieren Sie die 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.

   

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.

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.

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.

Häufig gestellte Fragen (FAQs)

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

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?

Diese Token-API und die Token-Administrator-API, obwohl sie ähnlich sind, bedienen unterschiedliche Anwendungsfälle 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.

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?

Es scheint, dass Ihr Mandant Sicherheitsrichtlinien hat, die erfordern, dass Ihrer Anwendung die Berechtigungen für den Zugriff auf Ressourcen in Ihrer 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.

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.