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

Azure DevOps Services

Wenn Sie mit einer großen Gruppe von persönlichen Zugriffstoken (PATs) arbeiten, die Sie besitzen, kann es komplex werden, die Wartung dieser Token mithilfe der Benutzeroberfläche allein zu verwalten.

Mit der PAT Lifecycle Management-API können Sie die paTs, die Mit Ihren Organisationen verbunden sind, ganz einfach mithilfe automatisierter Prozesse verwalten. Mit dieser umfangreichen Gruppe von APIs können Sie die paTs verwalten, die Sie besitzen, sodass Sie neue persönliche Zugriffstoken erstellen und vorhandene persönliche Zugriffstoken verlängern oder ablaufen können.

In diesem Artikel erfahren Sie, wie Sie eine Anwendung konfigurieren, die sich mit einem Azure Active Directory-Token (Azure AD) authentifiziert und Aufrufe mit der PAT-Lifecycle-API führt. Wenn Sie nur die vollständige Liste der verfügbaren Endpunkte anzeigen möchten, zeigen Sie hier die API-Referenz an.

Voraussetzungen

Um die API zu verwenden, müssen Sie sich mit einem Azure AD Token authentifizieren. Weitere Informationen dazu finden Sie im folgenden Abschnitt zur Authentifizierung.

Dazu müssen einige Voraussetzungen erfüllt werden:

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

Authentifizieren mit Azure Active Directory (Azure AD) Token

Im Gegensatz zu anderen Azure DevOps Services-APIs müssen Benutzer ein Azure AD Zugriffstoken bereitstellen, um diese API anstelle eines PAT-Tokens zu verwenden. Azure AD 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 Azure AD Zugriffstoken zu erwerben und zu aktualisieren, müssen Sie Folgendes ausführen:

Wichtig

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

Achtung

Ein Azure AD 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 Azure AD-Token verfügen, können Sie diese Token verwenden, um Aufrufe an die PAT Lifecycle Management-API zu tätigen.

Um die API direkt aufrufen zu können, müssen Sie ein Azure AD Zugriffstoken als Bearer Token in Authorization der Kopfzeile Ihrer Anforderung bereitstellen. Informationen zu den Beispielen und einer vollständigen 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 Azure AD 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 Azure AD-Token verwenden können. Eine vollständige Liste der MSAL-Flüsse finden Sie in der Dokumentation zur Microsoft-Authentifizierungsbibliothek "Authentifizierungsflüsse". Ein Leitfaden 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, um zu beginnen:

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 Azure AD Mandanten und Azure DevOps Organisation konfiguriert werden können. Die Beispielanwendung verwendet den MSAL-Authentifizierungscodefluss, um ein Azure AD Zugriffstoken abzurufen.

Wichtig

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

Nachdem Sie die Beispiel-App geklont haben, folgen Sie den Anweisungen in der README-Datei des Repo. Die README erläutert, wie Sie eine Anwendung in Ihrem Azure AD Mandanten registrieren, das Beispiel so konfigurieren, dass Ihr Azure AD-Mandant verwendet wird, und führen Sie Ihre geklonte App aus.

Generieren einer Schnellstartanwendung 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 Schnellstarttestanwendung 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-Verwaltungs-API zu verweisen.

Um diesem Ansatz zu folgen, folgen Sie den Schnellstartanweisungen für den Anwendungstyp Ihrer Wahl auf der Startseite Azure AD Entwickeln von Dokumenten. Wir werden ein Beispiel durchgehen, in dem wir dies für eine Python Flask Quickstart-App getan haben.

Beispiel: Erste Schritte mit einer Python Flask Quickstart-Anwendung

  1. Nachdem Sie Ihre Anwendung in einem Azure AD Mandanten registriert haben, der über ein aktives Azure-Abonnement verfügt, navigieren Sie zu Ihrer registrierten Anwendung unter Azure Active Directory -App-Registrierungen> im Azure-Portal.

    Open

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

    Select your application and navigate to

  3. Wählen Sie "Berechtigung hinzufügen" aus, und wählen Sie Azure DevOps aus,> und aktivieren Sie user_impersonation> , und wählen Sie "Berechtigungen hinzufügen" aus.

    Add the

  4. Wählen Sie "Schnellstart" aus dem linken Navigationsbereich 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 Lernprogramm "Python" aus.

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

    Allow the Azure portal to make the necessary changes to configure your application

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

    Download the Quickstart application and extract the files

  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 ein Endpunkt in der Microsoft-Graph-API erreicht wird. Erfahren Sie, wie Sie diesen Endpunkt in den PAT Lifecycle Management API-Basisendpunkt ändern, indem Sie den Konfigurationsanweisungen im folgenden Abschnitt folgen.

    Install the application requirements and run the application to ensure you have all necessary dependencies

Konfigurieren einer Schnellstartanwendung

Nachdem der Benutzer die Schnellstartanwendung heruntergeladen und installiert hat, wird er so konfiguriert, dass ein Test-API-Endpunkt von Microsoft Graph verwendet wird. Stattdessen müssen wir die generierte Konfigurationsdatei so ändern, dass 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 Ihren Organisationsnamen.

Dazu müssen wir einige Dinge tun:

  1. Aktualisieren der ENDPUNKT-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 seine 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 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 zur Verwendung eines Zertifikats finden Sie im letzten Schritt der Schnellstartanwendungseinrichtung.

Achtung

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

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

  1. Nachdem Sie Ihre Schnellstartanwendung heruntergeladen haben, dessen Abhängigkeiten installiert und getestet haben, dass 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; Für Klarheit wurden Kommentare, die auf die Standardmäßigkonfiguration von 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 Ihren Azure DevOps Sammlungs-URL und API-Endpunkt. Für eine Auflistung mit dem Namen "testCollection" wäre der Wert beispielsweise:

    # 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 Auflistung mit dem Namen "testCollection" wäre dieser Endpunkt:

    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 Zeichenzeichenfolge 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"]
    
  5. Wenn Ihre Anwendung für einen bestimmten Mandanten konfiguriert ist (anstatt für die Konfiguration mit mehreren Mandanten), 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 letzte app_config.py Datei mit der folgenden Übereinstimmung ü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. Nachdem Sie überprüft haben, können Sie den Inhalt 'app.py' und das 'ms-identity-python-webapp-master\templates' Verzeichnis ändern, um das Senden von Anforderungen an den Rest der PAT-Lifecycle-API-Endpunkte zu unterstützen. Ein Beispiel für eine Python Flask Quickstart-Anwendung, die geändert wurde, um Anforderungen an alle PAT-Lifecycle-Verwaltungs-API-Endpunkte zu unterstützen, finden Sie in diesem Beispiel-Repo auf GitHub.

Automatische Aktualisierung eines Azure AD-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 angegebene MSAL-Code aktualisiert das Token automatisch, sobald es abläuft. Beim Aktualisieren des Token wird verhindert, dass sich der Benutzer erneut anmelden muss und einen neuen Autorisierungscode erhält. Benutzer müssen sich jedoch nach Ablauf des Aktualisierungstokens nach 90 Tagen erneut anmelden.

Erkunden der PAT-Lifecycle-Verwaltungs-API

In der obigen GitHub-Beispielanwendung und Schnellstartanwendungen wurde die Anwendung vorkonfiguriert, um Anforderungen mit den Azure AD-Token vorzunehmen, die Sie erworben haben. Weitere Informationen zu den Endpunkten, welche Parameter sie akzeptieren, und was in Antworten zurückgegeben wird, finden Sie in den API-Referenzdokumenten.

Häufig gestellte Fragen

F: Warum muss ich mit einem Azure AD-Token authentifizieren? Warum ist ein PAT nicht genug?

Eine: Mit dieser PAT-Lifecycle-Verwaltungs-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 Azure AD-Authentifizierung hoffen wir, dass diese leistungsstarke API gegen diese nicht autorisierte Nutzung sicherer ist.

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

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

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

Eine: Wir lieben, dass Sie die API in Ihrer Wahlsprache verwenden möchten! Wenn Sie eine Anforderung für ein Beispiel haben, wechseln Sie zu unserer Dev Community , um zu sehen, ob jemand anderes 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 mit , und wir können es auf diesen Dokumenten weiterverzweigen!

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

Eine: Diese Token-API und die Tokenadministrator-API, während ähnliche Anwendungsfälle und Zielgruppen dienen:

  • Diese Token-API ist weitgehend für Benutzer, die die PATs verwalten möchten, die sie in einer automatisierten Pipeline besitzen. Diese API ermöglicht. Es bietet Ihnen die Möglichkeit, neue Token zu erstellen und vorhandene zu aktualisieren.
  • Die Tokenadministrator-API ist für Organisationsadministratoren gedacht. Administratoren können diese API verwenden, um OAuth-Autorisierungen abzurufen und zu widerrufen, einschließlich persönlicher Zugriffstoken (PATs) und selbst beschreibender Sitzungstoken von Benutzern in ihren Organisationen.

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

Eine: Tolle Frage! Die "Regenerate"-Funktionalität, die in der Benutzeroberfläche verfügbar ist, führt tatsächlich einige Aktionen durch, die vollständig über die API repliziert werden.

Um Ihr PAT zu drehen, müssen Sie folgendes ausführen:

  1. Verstehen der Metadaten des PAT mithilfe eines GET-Anrufs
  2. Erstellen Sie einen neuen PAT mit den Metadaten des alten PAT mithilfe eines POST-Anrufs .
  3. Widerrufen des alten PAT mithilfe eines DELETE-Aufrufs

F: Ich sehe ein Popup "Administratorgenehmigung benötigen", wenn ich versucht, mit dieser App fortzufahren. Wie kann ich diese App ohne Administratorgenehmigung verwenden?

Eine: Es scheint, dass Ihr Mandanten Sicherheitsrichtlinien festgelegt hat, die erfordern, dass Ihre Anwendung Berechtigungen für den Zugriff auf Ressourcen in der Organisation gewährt. In diesem Moment ist die einzige Möglichkeit, mit dieser App in diesem Mandanten fortzufahren, um einen Administrator zu bitten, die Berechtigung für die App zu erteilen, bevor Sie es verwenden können.

Nächste Schritte