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
- Um zu beginnen, benötigen Sie ein vorhandenes Microsoft Purview-Konto. Wenn Sie über keinen Katalog verfügen, lesen Sie den Schnellstart zum Erstellen eines Microsoft Purview-Kontos.
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:
Melden Sie sich beim Azure-Portal an.
Suchen Sie im Portal nach Microsoft Entra ID, und wählen Sie sie aus.
Wählen Sie auf der Seite Microsoft Entra ID im linken Bereich App-Registrierungen aus.
Wählen Sie Neue Registrierung aus.
Gehen Sie auf der Seite Anwendung registrieren wie
- Geben Sie einen Namen für die Anwendung (dienstprinzipalname) ein.
- 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.
- 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. - Wählen Sie Registrieren aus.
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.
Um den Dienstprinzipal (Anwendung) verwenden zu können, müssen Sie das Kennwort des Dienstprinzipals kennen, das sie finden können:
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.
Wählen Sie Ihren Dienstprinzipal (Anwendung) aus der Liste aus.
Wählen Sie im linken Bereich Zertifikate & Geheimnisse aus.
Wählen Sie Neues Clientgeheimnis aus.
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.
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:
Navigieren Sie zu Ihrem Microsoft Purview-Governanceportal.
Wählen Sie im linken Menü die Data Map aus.
Wählen Sie Sammlungen aus.
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.
Wählen Sie die Registerkarte Rollenzuweisungen aus.
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.