Freigeben über


Tutorial: Authentifizieren für APIs

In diesem Tutorial erfahren Sie, wie Sie sich für die Microsoft Purview-Datenebenen-APIs authentifizieren. Jeder, der Daten an Microsoft Purview übermitteln, Microsoft Purview als Teil eines automatisierten Prozesses einbinden oder eine eigene Benutzererfahrung in Microsoft Purview erstellen möchte, kann dazu die APIs verwenden.

Voraussetzungen

Erstellen eines Dienstprinzipals (Anwendung)

Damit ein API-Client auf die Microsoft Purview-Datenebenen-APIs zugreifen kann, muss der Client über einen Dienstprinzipal (Anwendung) und eine Identität verfügen, die Microsoft Purview erkennt und so konfiguriert ist, dass sie als vertrauenswürdig konfiguriert ist. Wenn Sie API-Aufrufe ausführen, wird die Identität dieses Dienstprinzipals für die Autorisierung verwendet.

Kunden, die vorhandene Dienstprinzipale (Anwendungs-IDs) verwendet haben, weisen eine hohe Fehlerrate auf. Daher wird empfohlen, einen neuen Dienstprinzipal zum Aufrufen von APIs zu erstellen.

So erstellen Sie einen neuen Dienstprinzipal:

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie im Portal nach Microsoft Entra ID, und wählen Sie sie aus.

  3. Wählen Sie auf der Seite Microsoft Entra ID im linken Bereich App-Registrierungen aus.

  4. Wählen Sie Neue Registrierung aus.

  5. Gehen Sie auf der Seite Anwendung registrieren wie

    1. Geben Sie einen Namen für die Anwendung (dienstprinzipalname) ein.
    2. Wählen Sie für Wer kann diese Anwendung verwenden oder auf diese API zugreifen? die Arten von Benutzerkonten aus, die Sie für die Verwendung dieser API erwarten.

      Tipp

      Wenn Sie erwarten, dass nur Benutzer aus Ihrem aktuellen Microsoft Entra ID Mandanten die REST-API verwenden, wählen Sie Nur Konten in diesem Organisationsverzeichnis (<nur Name> Ihres Mandanten – Einzelner Mandant) aus. Ziehen Sie andernfalls die anderen Optionen in Betracht.

    3. Wählen Sie für Umleitungs-URI (optional)die Option Web aus, und geben Sie einen Wert ein. Dieser Wert muss kein gültiger Endpunkt sein. https://exampleURI.com wird.
    4. Wählen Sie Registrieren aus.

    Screenshot der Anwendungsregistrierungsseite mit den oben aufgeführten Optionen.

  6. Kopieren Sie auf der Seite für den neuen Dienstprinzipal die Werte des Anzeigenamens und der Anwendungs-ID (Client), um sie später zu speichern.

    Die Anwendungs-ID ist der client_id Wert im Beispielcode.

    Screenshot der Anwendungsseite im Portal mit hervorgehobener Anwendungs-ID (Client-ID).

Um den Dienstprinzipal (Anwendung) verwenden zu können, müssen Sie das Kennwort des Dienstprinzipals kennen, das sie finden können:

  1. Suchen Sie im Azure-Portal nach Microsoft Entra ID, wählen Sie sie aus, und wählen Sie dann im linken Bereich App-Registrierungen aus.

  2. Wählen Sie Ihren Dienstprinzipal (Anwendung) aus der Liste aus.

  3. Wählen Sie im linken Bereich Zertifikate & Geheimnisse aus.

  4. Wählen Sie Neues Clientgeheimnis aus.

  5. Geben Sie auf der Seite Geheimen Clientschlüssel hinzufügen eine Beschreibung ein, wählen Sie unter Läuft ab eine Ablaufzeit aus, und wählen Sie dann Hinzufügen aus.

    Auf der Seite Geheime Clientschlüssel ist die Zeichenfolge in der Spalte Wert Ihres neuen Geheimnisses Ihr Kennwort. Speichern Sie diesen Wert.

    Screenshot: Geheimer Clientschlüssel

Einrichten der Authentifizierung mithilfe des Dienstprinzipals

Nachdem der neue Dienstprinzipal erstellt wurde, müssen Sie die Datenebenenrollen Ihres Purview-Kontos dem oben erstellten Dienstprinzipal zuweisen. Führen Sie die folgenden Schritte aus, um die richtige Rolle zuzuweisen, um eine Vertrauensstellung zwischen dem Dienstprinzipal und dem Purview-Konto herzustellen:

  1. Navigieren Sie zu Ihrem Microsoft Purview-Governanceportal.

  2. Wählen Sie im linken Menü die Data Map aus.

  3. Wählen Sie Sammlungen aus.

  4. Wählen Sie die Stammsammlung im Menü Sammlungen aus. Dies ist die oberste Sammlung in der Liste und hat den gleichen Namen wie Ihr Microsoft Purview-Konto.

    Hinweis

    Sie können Ihre Dienstprinzipalberechtigung auch allen Untersammlungen anstelle der Stammsammlung zuweisen. Alle APIs werden jedoch auf diese Sammlung (und Untersammlungen, die Berechtigungen erben) festgelegt, und Benutzer, die versuchen, die API für eine andere Sammlung aufzurufen, erhalten Fehler.

  5. Wählen Sie die Registerkarte Rollenzuweisungen aus.

  6. Weisen Sie dem zuvor erstellten Dienstprinzipal die folgenden Rollen zu, um auf verschiedene Datenebenen in Microsoft Purview zuzugreifen. Ausführliche Schritte finden Sie unter Zuweisen von Azure-Rollen mithilfe des Microsoft Purview-Governanceportals.

    • Rolle "Datenkurator" für den Zugriff auf die Katalogdatenebene.
    • Die Rolle "Datenquellenadministrator" für den Zugriff auf die Scandatenebene.
    • Sammlung Admin Rolle für den Zugriff auf Kontodatenebene und Metadatenrichtlinie Datenebene.
    • Rolle "Richtlinienautor" für den Zugriff auf die DevOps-Richtlinien-API

    Hinweis

    Nur Mitglieder der Rolle Sammlung Admin können Datenebenenrollen in Microsoft Purview zuweisen. Weitere Informationen zu Microsoft Purview-Rollen finden Sie unter Access Control in Microsoft Purview.

Token abrufen

Sie können eine POST-Anforderung an die folgende URL senden, um das Zugriffstoken abzurufen.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Sie können Ihre Mandanten-ID finden, indem Sie im Azure-Portal nach Mandanteneigenschaften suchen. Die ID ist auf der Eigenschaftenseite des Mandanten verfügbar.

Die folgenden Parameter müssen an die obige URL übergeben werden:

  • client_id: Client-ID der Anwendung, die in Microsoft Entra ID registriert ist und einer Datenebenenrolle für das Microsoft Purview-Konto zugewiesen ist.
  • client_secret: Geheimer Clientschlüssel, der für die oben genannte Anwendung erstellt wurde.
  • grant_type: Dies sollte "client_credentials" sein.
  • ressource: 'https://purview.azure.net'

Hier sehen Sie eine BEISPIEL-POST-Anforderung in PowerShell:

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

Beispielantworttoken:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

Tipp

Wenn Sie eine Fehlermeldung mit folgendem Text erhalten: Die tokenübergreifende Einlösung ist nur für den Clienttyp "Single-Page Application" zulässig.

  • Überprüfen Sie Ihre Anforderungsheader, und vergewissern Sie sich, dass Ihre Anforderung nicht den Header "origin" enthält.
  • Vergewissern Sie sich, dass Der Umleitungs-URI in Ihrem Dienstprinzipal auf web festgelegt ist.
  • Stellen Sie sicher, dass Ihre Software für die Anwendung, die Sie zum Senden Ihrer POST-Anforderung verwenden, auf dem neuesten Stand ist.

Verwenden Sie das oben genannte Zugriffstoken, um die Datenebenen-APIs aufzurufen.

Nächste Schritte