Freigeben über

Schnellstart: Konfigurieren von Microsoft Entra für einen benutzerdefinierten Konnektor

  • Artikel

In dieser Anleitung werden die Schritte zum Konfigurieren einer Microsoft Entra-Anwendung für die Verwendung mit einem benutzerdefinierten Power Query-Konnektor beschrieben. Die Entwickler*innen von Konnektoren sollten sich vor dem Fortfahren die Konzepte der Microsoft Identity Platform anschauen.

Da der Begriff Anwendung in der Microsoft Entra-Plattform in mehreren Zusammenhängen verwendet wird, wird in dieser Anleitung anhand der folgenden Begriffe zwischen den Anwendungs-IDs von Konnektoren und Datenquellen unterschieden:

  • Clientanwendung: Die Microsoft Entra-Client-IDs, die vom Power Query-Konnektor genutzt werden.
  • Ressourcenanwendung: Die Microsoft Entra-Anwendungsregistrierung für den Endpunkt, mit dem der Konnektor eine Verbindung herstellt (d. h. der Dienst oder die Datenquelle).

Die Aktivierung der Microsoft Entra-Unterstützung für einen benutzerdefinierten Konnektor umfasst Folgendes:

  • Definieren eines oder mehrerer Bereiche in der vom Konnektor genutzten Ressourcenanwendung.
  • Vorabautorisierung der Power Query-Client-IDs für die Verwendung dieser Bereiche.
  • Festlegen der richtigen Werte Resource und Scopes in der Konnektordefinition.

In dieser Anleitung wird davon ausgegangen, dass eine neue Ressourcenanwendung in Microsoft Entra registriert ist. Entwickler*innen mit einer vorhandenen Ressourcenanwendung können mit dem Abschnitt Konfigurieren eines Bereichs fortfahren.

Hinweis

Weitere Informationen zur Nutzung von Microsoft Entra in Diensten oder Anwendungen erhalten Sie in einer der Schnellstartanleitungen.

Registrieren der Ressourcenanwendung

Die Datenquelle oder der API-Endpunkt stellt mit dieser Ressourcenanwendung eine Vertrauensstellung zwischen dem Dienst und der Microsoft Identity Platform her.

Gehen Sie wie folgt vor, um eine neue Ressourcenanwendung zu registrieren:

  1. Melden Sie sich beim Microsoft Entra Admin Center mindestens als Cloudanwendungsadministrator an.
  2. Wechseln Sie zu Identität>Anwendungen>App-Registrierungen, und wählen Sie Neue Registrierung aus.
  3. Geben Sie einen Anzeigenamen für Ihre Anwendung ein.
  4. Wählen Sie für Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus, wenn der Endpunkt nur innerhalb Ihrer Organisation zugänglich ist. Wählen Sie für öffentlich zugängliche, mehrinstanzenfähige Dienste die Option Konten in einem beliebigen Organisationsverzeichnis aus.
  5. Wählen Sie Registrieren aus.

Sie müssen keinen Wert für Umleitungs-URI angeben.

Die Seite Übersicht der Anwendung wird angezeigt, wenn die Registrierung abgeschlossen ist. Achten Sie auf die Werte Verzeichnis-ID (Mandant) und Anwendungs-ID (Client), da sie im Quellcode des Diensts verwendet werden. Folgen Sie einer der Anleitungen in den Codebeispielen der Microsoft Identity Platform, die Ihrer Dienstumgebung und Architektur ähneln, um nachzuvollziehen, wie Sie die neue Anwendung konfigurieren und nutzen.

Festlegen eines Anwendungs-ID-URI

Bevor Sie für den Endpunkt einen Bereich konfigurieren können, müssen Sie einen Anwendungs-ID-URI für die Ressourcenanwendung festlegen. Diese ID wird vom Feld Resource des Eintrags Aad im Konnektor verwendet. Der Wert wird auf die Stamm-URL des Diensts eingestellt. Außerdem können Sie den von Microsoft Entra generierten Standardwert (api://{clientId}) verwenden, wobei {clientId} die Client-ID der Ressourcenanwendung ist.

  1. Wechseln Sie zur Seite Übersicht der Ressourcenanwendung.
  2. Wählen Sie im mittleren Bildschirm unter Essentials die Option Anwendungs-ID-URI hinzufügen aus.
  3. Geben Sie einen URI ein, oder übernehmen Sie den Standardwert basierend auf Ihrer App-ID.
  4. Wählen Sie Speichern und fortfahren aus.

In den Beispielen in dieser Anleitung wird davon ausgegangen, dass Sie das Standardformat für den Anwendungs-ID-URI verwenden (z. B. api://44994a60-7f50-4eca-86b2-5d44f873f93f).

Konfigurieren eines Bereichs

Mithilfe von Bereichen werden Berechtigungen oder Funktionalitäten für den Zugriff auf APIs oder Daten im Dienst definiert. Die Liste der unterstützten Bereiche ist dienstspezifisch. Sie sollten einen Mindestsatz an Bereichen festlegen, die für den Konnektor erforderlich sind. Für die Power Query-Client-IDs müssen Sie mindestens einen Bereich vorab autorisieren.

Wenn für die Ressourcenanwendung bereits Bereiche definiert sind, können Sie mit dem nächsten Schritt fortfahren.

Wenn im Dienst keine bereichsbasierten Berechtigungen zum Einsatz kommen, können Sie dennoch einen einzelnen Bereich definieren, der vom Konnektor verwendet wird. Diesen Bereich können Sie im Dienstcode in Zukunft (optional) nutzen.

In diesem Beispiel definieren Sie einen einzelnen Bereich namens Data.Read.

  1. Wechseln Sie zur Seite Übersicht der Ressourcenanwendung.
  2. Wählen Sie unter Verwalten die Optionen Eine API verfügbar machen > Bereich hinzufügen aus.
  3. Geben Sie unter Bereichsname den Namen Data.Read ein.
  4. Wählen Sie unter Zum Einwilligen berechtigte Personen die Option Administratoren und Benutzer aus.
  5. Füllen Sie die restlichen Felder („Anzeigename“ und „Beschreibung“) aus.
  6. Stellen Sie sicher, dass Status auf Aktiviert eingestellt ist.
  7. Wählen Sie Umfang hinzufügen aus.

Vorabautorisieren der Power Query-Clientanwendungen

Power Query-Konnektoren nutzen zwei verschiedene Microsoft Entra-Client-IDs. Die Vorabautorisierung von Bereichen für diese Client-IDs vereinfacht das Herstellen von Verbindungen.

Client-ID Anwendungsname Verwendet von
a672d62c-fc7b-4e81-a576-e60dc46e951d Power Query für Excel Desktopumgebungen
b52893c8-bc2e-47fc-918b-77022b299bbc Datenaktualisierung in Power BI Dienstumgebungen

So autorisieren Sie die Power Query-Client-IDs vorab:

  1. Wechseln Sie zur Seite Übersicht der Ressourcenanwendung.
  2. Wählen Sie unter Verwalten die Option Eine API verfügbar machen aus.
  3. Wählen Sie Client-Anwendung hinzufügen.
  4. Geben Sie eine der Power Query-Client-IDs ein.
  5. Wählen Sie die geeigneten autorisierten Bereiche aus.
  6. Wählen Sie Anwendung hinzufügen aus.
  7. Wiederholen Sie die Schritte 3 bis 6 für jede Power Query-Client-ID.

Aktivieren der Aad-Authentifizierungsart im Konnektor

Die Unterstützung für die Microsoft Entra-ID wird für den Konnektor aktiviert, indem die Authentifizierungsart Aad dem Datenquelleneintrag des Konnektors hinzugefügt wird.

MyConnector = [
    Authentication = [
        Aad = [
            AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
            Resource = "{YourApplicationIdUri}"
            Scope = ".default"
        ]
    ]
];

Ersetzen Sie den Wert {YourApplicationIdUri} durch den Wert von Anwendungs-ID-URI für die Ressourcenanwendung, z. B api://44994a60-7f50-4eca-86b2-5d44f873f93f.

In diesem Beispiel:

  • AuthorizationUri: Die Microsoft Entra-URL, mit deren Hilfe der Authentifizierungsablauf initiiert wird. Die meisten Konnektoren können diesen Wert in https://login.microsoftonline.com/common/oauth2/authorize hartcodieren, er kann aber auch dynamisch bestimmt werden, wenn der Dienst Azure-B2B/Gastkonten unterstützt. Weitere Informationen finden Sie unter Beispiele.
  • Ressource: Der Anwendungs-ID-URI des Konnektors.
  • Bereich: Nutzen Sie den Standardbereich, um automatisch alle vorab autorisierten Bereiche zu empfangen. Mit .default können Sie die erforderlichen Konnektorbereiche in der Registrierung der Ressourcenanwendung ändern, ohne den Konnektor aktualisieren zu müssen.

Weitere Details und Optionen zum Konfigurieren der Microsoft Entra-Unterstützung im Konnektor finden Sie auf der Seite mit Beispielen für die Microsoft Entra ID-Authentifizierung.

Erstellen Sie den Konnektor neu. Jetzt sollten Sie sich mit Microsoft Entra ID beim Dienst authentifizieren können.

Problembehandlung

In diesem Abschnitt werden Fehler beschrieben, die bei einer Fehlkonfiguration der Microsoft Entra-Anwendung häufiger auftreten können.

Die Power Query-Anwendung wurde nicht vorab autorisiert.

access_denied: AADSTS650057: Ungültige Ressource. Der Client hat Zugriff auf eine Ressource angefordert, die in der Anwendungsregistrierung des Clients nicht unter den angeforderten Berechtigungen aufgeführt ist. Client-App-ID: a672d62c-fc7b-4e81-a576-e60dc46e951d (Microsoft Power Query für Excel). Ressourcenwert aus Anforderung: 44994a60-7f50-4eca-86b2-5d44f873f93f. Ressourcenanwendungs-ID: 44994a60-7f50-4eca-86b2-5d44f873f93

Dieser Fehler kann auftreten, wenn die Ressourcenanwendung die Power Query-Clientanwendungen nicht vorab autorisiert hat. Führen Sie die Schritte zum Vorabautorisieren der Power Query-Client-IDs aus.

Im Aad-Eintrag des Konnektors fehlt ein Bereichswert.

access_denied: AADSTS650053: Die Anwendung Microsoft Power Query für Excel hat den Bereich „user_impersonation“ angefordert, der in der Ressource „44994a60-7f50-4eca-86b2-5d44f873f93f“ nicht vorhanden ist. Wenden Sie sich an den App-Hersteller.

Power Query fordert den Bereich user_impersonation an, wenn im Eintrag Aad des Konnektors kein Feld Scope definiert ist oder der Wert Scopenull lautet. Dieses Problem können Sie beheben, indem Sie im Konnektor einen Scope-Wert definieren. Die Nutzung des Bereichs .default wird empfohlen, Sie können Bereiche aber auch auf der Konnektorebene angeben (z. B. Data.Read).

Bereich oder Clientanwendung erfordert Admin-Genehmigung

Die Admin-Genehmigung ist erforderlich. Der <Mandant> benötigt für den Zugriff auf Ressourcen in Ihrer Organisation eine Berechtigung, die nur ein Admin erteilen kann. Bitten Sie einen Administrator, die Berechtigungen für diese App zu erteilen, damit Sie die App verwenden können.

Dieser Fehler kann während des Authentifizierungsablaufs auftreten, wenn die Ressourcenanwendung Admin-beschränkte Berechtigungen erfordert oder der Mandant des Benutzers verhindert, dass Nicht-Admin-Benutzer*innen Anträgen für neue Anwendungsberechtigungen zustimmen können. Dieses Problem können Sie vermeiden, indem Sie sicherstellen, dass der Konnektor keine Admin-beschränkten Bereiche erfordert, und die Power Query-Client-IDs für die Ressourcenanwendung vorab autorisieren.