Voraussetzungen für den Zugriff auf die Azure Active Directory-Berichterstellungs-API

  • Artikel
  • 5 Minuten Lesedauer

Die Berichtserstellungs-APIs von Azure Active Directory (Azure AD) bieten Ihnen über eine Gruppe von REST-basierten APIs programmgesteuerten Zugriff auf die Daten. Sie können diese APIs über mehrere Programmiersprachen und Tools aufrufen.

Die Berichterstellungs-API verwendet OAuth zum Autorisieren des Zugriffs auf die Web-APIs.

Um auf die Berichterstellungs-API zugreifen zu können, müssen Sie folgende Schritte ausführen:

  1. Zuweisen von Rollen
  2. Lizenzanforderungen
  3. Registrieren einer Anwendung
  4. Erteilen von Berechtigungen
  5. Erfassen von Konfigurationseinstellungen

Zuweisen von Rollen

Um mithilfe der API auf die Berichtsdaten zuzugreifen, müssen Ihnen eine der folgenden Rollen zugewiesen sein:

  • Sicherheitsleseberechtigter

  • Sicherheitsadministrator

  • Globaler Administrator

Lizenzanforderungen

Um auf die Anmeldungsberichte eines Mandanten zugreifen zu können, muss einem Azure AD-Mandanten eine Azure AD Premium-Lizenz zugeordnet sein. Eine Azure AD Premium-Lizenz ab P1 ist erforderlich, um auf die Anmeldeberichte beliebiger Azure AD-Mandanten zugreifen zu können. Alternativ dazu ist der Zugriff auf die Anmeldeberichte über die API ohne zusätzliche Lizenzanforderungen möglich, wenn der Verzeichnistyp „Azure AD B2C“ lautet.

Registrieren einer Anwendung

Eine Registrierung ist auch dann erforderlich, wenn Sie mithilfe eines Skripts auf die Berichterstellungs-API zugreifen. Bei der Registrierung wird Ihnen eine Anwendungs-ID zugewiesen, die für die Autorisierungsaufrufe erforderlich ist und den Empfang von Token über Ihren Code ermöglicht.

Um Ihr Verzeichnis für den Zugriff auf die Azure AD-Berichterstellungs-API zu konfigurieren, müssen Sie sich beim Azure-Portal mit dem Konto eines Azure-Administrators anmelden, das auch der Verzeichnisrolle Globaler Administrator Ihres Azure AD-Mandanten angehört.

Wichtig

Anwendungen, die unter Anmeldeinformationen mit Administratorberechtigungen ausgeführt werden, können äußerst einflussreich sein. Sorgen Sie also unbedingt dafür, dass die ID und geheimen Anmeldeinformationen der Anwendung an einem sicheren Ort aufbewahrt werden.

Registrieren Sie eine Azure AD-Anwendung wie folgt:

  1. Wählen Sie im Azure-Portal im linken Navigationsbereich die Option Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu.

  2. Wählen Sie auf der Seite Azure Active Directory die Option App-Registrierungen.

    Screenshot shows App registrations selected from the Manage menu.

  3. Wählen Sie auf der Seite App-Registrierungen die Option Registrierung einer neuen Anwendung aus.

    Screenshot shows New registration selected.

  4. Die Seite Anwendung registrieren:

    Screenshot shows the Register an application page where you can enter the values in this step.

    a. Geben Sie im Textfeld Name Folgendes ein: Reporting API application.

    b. Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

    c. Wählen Sie unter Umleitungs-URL das Textfeld Web aus, und geben Sie https://localhost ein.

    d. Wählen Sie Registrieren.

Erteilen von Berechtigungen

Für den Zugriff auf die Berichterstellungs-API von Azure AD müssen Sie Ihrer App die folgenden beiden Berechtigungen erteilen:

API Berechtigung
Microsoft Graph Verzeichnisdaten lesen
Microsoft Graph Alle Überwachungsprotokolldaten lesen

Screenshot shows where you can select Add a permission in the A P I permissions pane.

Im folgenden Abschnitt werden die Schritte für die API-Einstellung aufgelistet.

So erteilen Sie Ihrer Anwendung die Berechtigung zur Verwendung der APIs:

  1. Klicken Sie auf API-Berechtigungen und anschließend auf Berechtigung hinzufügen.

    Screenshot shows the A P I Permissions page where you can select Add a permission.

  2. Suchen Sie auf der Seite API-Berechtigungen anfordern nach Microsoft Graph.

    Screenshot shows the Request A P I permissions page where you can select Azure Active Directory Graph.

  3. Wählen Sie auf der Seite Erforderliche Berechtigungen die Option Anwendungsberechtigungen aus. Aktivieren Sie das Kontrollkästchen Verzeichnis, und wählen Sie anschließend Directory.ReadAll aus. Aktivieren Sie das Kontrollkästchen AuditLog, und wählen Sie anschließend AuditLog.Read.All aus. Wählen Sie Berechtigungen hinzufügen aus.

    Screenshot shows the Request A P I permissions page where you can select Application permissions.

  4. Wählen Sie auf der Seite Berichterstellungs-API-Anwendung – API-Berechtigungen die Option Administratoreinwilligung erteilen aus.

    Screenshot shows the Reporting A P I Application A P I permissions page where you can select Grant admin consent.

Erfassen von Konfigurationseinstellungen

In diesem Abschnitt wird gezeigt, wie Sie die folgenden Einstellungen aus Ihrem Verzeichnis abrufen:

  • Domänenname
  • Client-ID
  • Geheimer Clientschlüssel oder Zertifikat

Sie benötigen diese Werte, um Aufrufe an die Berichterstellungs-API zu konfigurieren. Aus Sicherheitsgründen wird die Verwendung eines Zertifikats empfohlen.

Ermitteln des Domänennamens

So ermitteln Sie den Domänennamen:

  1. Wählen Sie im Azure-Portal im linken Navigationsbereich die Option Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get domain name.

  2. Wählen Sie auf der Seite Azure Active Directory die Option Benutzerdefinierte Domänennamen.

    Screenshot shows Custom domain names selected from Azure Active Directory.

  3. Kopieren Sie Ihren Domänennamen aus der Liste der Domänen.

Abrufen der Client-ID der Anwendung

So rufen Sie die Client-ID der Anwendung ab:

  1. Klicken Sie im linken Navigationsbereich des Azure-Portals auf Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get application's client ID.

  2. Wählen Sie Ihre Anwendung auf der Seite App-Registrierungen aus.

  3. Navigieren Sie auf der Anwendungsseite zu Anwendungs-ID, und wählen Sie die Option Click to copy (Zum Kopieren klicken).

    Screenshot shows the Reporting A P I Application page where you can copy the Application I D.

Abrufen des geheimen Clientschlüssels der Anwendung

So rufen Sie den geheimen Clientschlüssel der Anwendung ab:

  1. Klicken Sie im linken Navigationsbereich des Azure-Portals auf Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get application's client secret.

  2. Wählen Sie Ihre Anwendung auf der Seite App-Registrierungen aus.

  3. Wählen Sie auf der Seite API-Anwendung die Option Zertifikate und Geheimnisse aus, und klicken Sie im Abschnitt Geheime Clientschlüssel auf + Neuer geheimer Clientschlüssel.

    Screenshot shows the Certificates & secrets page where you can add a client secret.

  4. Führen Sie auf der Seite Geheimen Clientschlüssel hinzufügen die folgenden Aktionen aus:

    a. Geben Sie im Textfeld Beschreibung Folgendes ein: Reporting API.

    b. Wählen Sie für Läuft ab die Option In 2 Jahren aus.

    c. Klicken Sie auf Speichern.

    d. Kopieren Sie den Schlüsselwert.

Hochladen des Zertifikats Ihrer Anwendung

Führen Sie folgende Schritte aus, um das Zertifikat hochzuladen:

  1. Wählen Sie im Azure-Portal im linken Navigationsbereich die Option Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to upload the certificate.

  2. Klicken Sie auf der Seite Azure Active Directory auf die Option App-Registrierung.

  3. Wählen Sie auf der Anwendungsseite Ihre Anwendung aus.

  4. Wählen Sie Zertifikate und Geheimnisse aus.

  5. Wählen Sie Zertifikat hochladen.

  6. Klicken Sie auf das Dateisymbol. Wählen Sie ein Zertifikat aus, und klicken Sie anschließend auf Hinzufügen.

    Screenshot shows uploading the certificate.

Beheben von Fehlern in der Berichterstellungs-API

In diesem Abschnitt werden die häufigsten Fehlermeldungen, die beim Zugreifen auf Aktivitätsberichte über die Microsoft Graph-API auftreten können, sowie Schritte zu deren Behebung aufgeführt.

Error: Fehler beim Abrufen von Benutzerrollen aus Microsoft Graph

Melden Sie sich auf der Graph-Tester-Benutzeroberfläche über beide Anmeldeschaltflächen bei Ihrem Konto an, um zu vermeiden, dass bei der Anmeldung mit dem Graph-Tester ein Fehler ausgegeben wird.

Graph Explorer

Error: Fehler beim Überprüfen der Premium-Lizenz aus Microsoft Graph

Wenn Sie diese Fehlermeldung beim Versuch erhalten, auf Anmeldungen mithilfe des Graph-Explorers zuzugreifen, wählen Sie Berechtigungen ändern unter Ihrem Konto im linken Navigationsbereich aus, und wählen Sie dann Tasks.ReadWrite und Directory.Read.All aus.

Modify permissions UI

Error: Der Mandant ist nicht B2C, oder der Mandant besitzt keine Premium-Lizenz

Für den Zugriff auf Anmeldeberichte ist eine Azure Active Directory Premium 1-Lizenz (P1) erforderlich. Wenn diese Fehlermeldung beim Zugriff auf Anmeldungen angezeigt wird, stellen Sie sicher, dass Ihr Mandant mit einer Azure AD P1-Lizenz lizenziert ist.

Error: Die zulässigen Rollen enthalten nicht „Benutzer“.

Vermeiden Sie Fehler beim Zugreifen auf Überwachungsprotokolle oder beim Anmelden mithilfe der API. Stellen Sie sicher, dass Ihr Konto zu der Rolle Sicherheitsleseberechtigter oder Berichtsleser in Ihrem Azure Active Directory-Mandanten gehört.

Error: Der Anwendung fehlt die AAD-Berechtigung „Verzeichnisdaten lesen“

Error: Der Anwendung fehlt die Berechtigung „Alle Überwachungsprotokolldaten lesen“ der Microsoft Graph-API

Führen Sie die unter Voraussetzungen für den Zugriff auf die Azure Active Directory-Berichterstellungs-API aufgeführten Schritte aus, um sicherzustellen, dass Ihre Anwendung mit dem richtigen Berechtigungssatz ausgeführt wird.

Nächste Schritte