Durchführen der Authentifizierung

Arten der Authentifizierung

Eine Erweiterung kann eine oder mehrere Arten der Authentifizierung unterstützen. Jede Authentifizierungsart ist eine andere Art von Berechtigungsnachweis. Die Authentifizierungsoberfläche, die den Endbenutzern in Power Query angezeigt wird, hängt von der Art der Berechtigung(en) ab, die eine Erweiterung unterstützt.

Die Liste der unterstützten Authentifizierungstypen wird als Teil der Definition einer Erweiterung Data Source Kind definiert. Jeder Authentifizierungswert ist ein Datensatz mit spezifischen Feldern. In der folgenden Tabelle sind die erwarteten Felder für jede Art aufgeführt. Alle Felder müssen ausgefüllt werden, sofern nicht anders angegeben.

Art der Authentifizierung	Feld	Beschreibung
Anonym		Die Authentifizierungsart Anonym (auch Implicit genannt) hat keine Felder.
OAuth	StartLogin	Funktion, die die URL und Statusinformationen für den Start eines OAuth-Flows bereitstellt. Gehen Sie zum Abschnitt Implementieren eines OAuth-Flows .
	FinishLogin	Funktion, die das access_token und andere Eigenschaften im Zusammenhang mit dem OAuth-Flow extrahiert.
	Refresh	(optional) Funktion, die ein neues Zugriffs-Token aus einem Refresh-Token abruft.
	Logout	(optional) Funktion, die das aktuelle Zugangs-Token des Benutzers ungültig macht.
	Label	(optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind überschreiben können.
Aad	AuthorizationUri	text Wert oder unäre Funktion, der bzw. die den Autorisierungsendpunkt von Microsoft Entra ID zurückgibt (Beispiel: "https://login.microsoftonline.com/common/oauth2/authorize"). Wechseln Sie zum Abschnitt " Microsoft Entra ID-Authentifizierung ".
	Resource	text Wert oder unäre Funktion, der bzw. die den Ressourcenwert von Microsoft Entra ID für den Dienst zurückgibt.
	`Scope`	(optional)text Wert oder unäre Funktion, der bzw. die die Liste der Bereiche zurückgibt, die im Rahmen des Authentifizierungsablaufs anzufordern sind. Mehrere Bereiche müssen durch ein Leerzeichen getrennt werden. Der Bereichswert muss der Bereichsname sein, ohne einen Anwendungs-ID-URI (Beispiel: Data.Read). Wenn keine Angabe erfolgt, wird der Bereich user_impersonation angefordert.
UsernamePassword	UsernameLabel	(optional) Ein Textwert, der die Standardbeschriftung für das Textfeld Benutzername auf der Benutzeroberfläche für Anmeldeinformationen ersetzt.
	PasswordLabel	(optional) Ein Textwert, der die Standardbeschriftung für das Textfeld Password auf der Benutzeroberfläche für Anmeldeinformationen ersetzt.
	Label	(optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind überschreiben können.
Windows	UsernameLabel	(optional) Ein Textwert, der die Standardbeschriftung für das Textfeld Benutzername auf der Benutzeroberfläche für Anmeldeinformationen ersetzt.
	PasswordLabel	(optional) Ein Textwert, der die Standardbeschriftung für das Textfeld Password auf der Benutzeroberfläche für Anmeldeinformationen ersetzt.
	Label	(optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind überschreiben können.
Schlüssel	KeyLabel	(optional) Ein Textwert, der die Standardbeschriftung für das Textfeld API Key auf der Benutzeroberfläche für Anmeldeinformationen ersetzt.
	Label	(optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind überschreiben können.

Das folgende Beispiel zeigt den Authentifizierungsdatensatz für einen Connector, der OAuth-, Schlüssel-, Windows-, Basis- (Benutzername und Kennwort) und anonyme Anmeldeinformationen unterstützt.

Beispiel:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Anonymous = []
]

Zugriff auf die aktuellen Anmeldeinformationen

Die aktuellen Anmeldedaten können mit der Funktion Extension.CurrentCredential abgerufen werden.

M-Datenquellenfunktionen, die für die Erweiterbarkeit aktiviert wurden, erben automatisch den Berechtigungsbereich Ihrer Erweiterung. In den meisten Fällen müssen Sie nicht explizit auf die aktuellen Anmeldeinformationen zugreifen, es gibt jedoch Ausnahmen, wie z. B.:

• Übergabe der Anmeldeinformationen in einem benutzerdefinierten Header- oder Query-String-Parameter (z. B. wenn Sie den Authentifizierungstyp API-Schlüssel verwenden).
• Festlegen von Verbindungsstring-Eigenschaften für ODBC- oder ADO.NET-Erweiterungen.
• Überprüfung der benutzerdefinierten Eigenschaften eines OAuth-Tokens.
• Verwendung der Anmeldedaten als Teil eines OAuth v1-Flusses.

Die Funktion Extension.CurrentCredential gibt ein Datensatzobjekt zurück. Die darin enthaltenen Felder sind spezifisch für den Authentifizierungstyp. Die folgende Tabelle enthält Einzelheiten.

Feld	Beschreibung	Verwendet von
AuthenticationKind	Enthält den Namen der Authentifizierungsart, die diesem Berechtigungsnachweis zugewiesen ist (BenutzernamePasswort, OAuth usw.).	Alle
Benutzername	Wert des Benutzernamens	BenutzernamePasswort, Windows
Kennwort	Wert des Passworts. Wird in der Regel mit UsernamePassword verwendet, kann aber auch für Key gesetzt werden.	Schlüssel, BenutzernamePasswort, Windows
access_token	OAuth-Zugangs-Token-Wert.	OAuth
Eigenschaften	Ein Datensatz mit weiteren benutzerdefinierten Eigenschaften für eine bestimmte Berechtigung. Wird in der Regel mit OAuth verwendet, um andere Eigenschaften (z. B. das refresh_token) zu speichern, die während des Authentifizierungsvorgangs mit dem access_token zurückgegeben werden.	OAuth
Schlüssel	Der Wert des API-Schlüssels. Beachten Sie, dass der Schlüsselwert auch im Feld Passwort verfügbar ist. Standardmäßig fügt die Mashup-Engine diesen Schlüssel in einen Autorisierungs-Header ein, als wäre dieser Wert ein einfaches Autorisierungskennwort (ohne Benutzernamen). Wenn Sie diese Art von Verhalten nicht wünschen, müssen Sie die Option ManualCredentials = true im Optionssatz angeben.	Schlüssel
EncryptConnection	Ein logischer Wert, der bestimmt, ob eine verschlüsselte Verbindung zur Datenquelle erforderlich ist. Dieser Wert ist für alle Authentifizierungsarten verfügbar, wird aber nur gesetzt, wenn EncryptConnection in der Definition von Data Source angegeben ist.	Alle

Das folgende Codebeispiel greift auf die aktuellen Anmeldeinformationen für einen API-Schlüssel zu und verwendet sie, um eine benutzerdefinierte Kopfzeile (x-APIKey) auszufüllen.

Beispiel:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

Implementierung eines OAuth-Flusses

Der OAuth-Authentifizierungstyp ermöglicht es einer Erweiterung, eine eigene Logik für ihren Dienst zu implementieren. Zu diesem Zweck bietet eine Erweiterung Funktionen für StartLogin (Rückgabe der Autorisierungs-URI zur Einleitung des OAuth-Flows) und FinishLogin (Austausch des Autorisierungscodes gegen ein Zugriffstoken). Erweiterungen können optional auch die Funktionen Refresh (Austausch eines Refresh-Tokens gegen ein neues Access-Token) und Logout (Auslaufen der aktuellen Refresh- und Access-Tokens) implementieren.

Hinweis

Power Query-Erweiterungen werden in Anwendungen ausgewertet, die auf Client-Rechnern laufen. Data Connectors sollten keine vertraulichen Geheimnisse in ihren OAuth-Strömen verwenden ( ), da Benutzer die Erweiterung oder den Netzwerkverkehr untersuchen könnten, um das Geheimnis zu erfahren. Unter Proof Key for Code Exchange by OAuth Public Clients RFC (auch bekannt als PKCE) finden Sie weitere Einzelheiten zur Bereitstellung von Abläufen, die nicht auf gemeinsamen Geheimnissen beruhen. Eine Beispielimplementierung dieses Flusses ist auf unserer GitHub-Seite zu finden.

Es gibt zwei Gruppen von OAuth-Funktionssignaturen: die ursprüngliche Signatur, die eine minimale Anzahl von Parametern enthält, und eine erweiterte Signatur, die mehr Parameter akzeptiert. Die meisten OAuth-Abläufe können unter Verwendung der Originalsignaturen implementiert werden. Sie können auch Signaturtypen in Ihrer Implementierung mischen und anpassen. Die Funktionsaufrufe werden anhand der Anzahl der Parameter (und deren Typen) zugeordnet. Die Parameternamen werden nicht berücksichtigt.

Weitere Einzelheiten finden Sie im GitHub-Beispiel.

Original OAuth-Signaturen

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

Erweiterte OAuth-Signaturen

Hinweise zu den fortgeschrittenen Signaturen:

• Alle Signaturen akzeptieren einen clientApplication Datensatzwert, der für die zukünftige Verwendung reserviert ist.
• Alle Signaturen akzeptieren eine dataSourcePath (in den meisten Mustern auch resourceUrl genannt).
• Die Funktion Refresh akzeptiert einen Parameter oldCredential , der der vorherige record ist, der von Ihrer Funktion FinishLogin (oder dem vorherigen Aufruf von Refresh) zurückgegeben wurde.

StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

Microsoft Entra ID-Authentifizierung

Die Authentifizierungsart Aad ist eine spezielle Version von OAuth für Microsoft Entra ID. Sie nutzt den gleichen Azure AD-Client wie die integrierten Power Query-Konnektoren, die die Authentifizierung von Organisationskonten unterstützen. Weitere Informationen finden Sie in der Schnellstartanleitung Konfigurieren von Microsoft Entra für einen benutzerdefinierten Konnektor.

Hinweis

Wenn Sie Ihren eigenen OAuth-Flow für Azure AD implementieren, können Benutzer, die Conditional Access für ihren Tenant aktiviert haben, Probleme bei der Aktualisierung mit dem Power BI-Dienst haben. Dies hat keine Auswirkungen auf die gatewaybasierte Aktualisierung, wohl aber auf einen zertifizierten Connector, der die Aktualisierung über den Power BI-Dienst unterstützt. Bei der Konfiguration von webbasierten Anmeldeinformationen über den Power BI-Dienst kann ein Problem auftreten, das darauf zurückzuführen ist, dass der Connector eine öffentliche Clientanwendung verwendet. Das von diesem Fluss generierte Zugriffstoken wird letztendlich auf einem anderen Computer verwendet (d. h. dem Power BI-Dienst in einem Azure-Rechenzentrum, nicht im Unternehmensnetzwerk) als dem, der ursprünglich für die Authentifizierung verwendet wurde (d. h. dem Computer des Benutzers, der die Anmeldeinformationen für die Datenquelle im Unternehmensnetzwerk konfiguriert). Der integrierte Aad-Typ umgeht dieses Problem, indem er bei der Konfiguration der Anmeldeinformationen im Power BI-Dienst einen anderen Azure AD-Client verwendet. Diese Option ist für Connectors, die die Authentifizierungsart OAuth verwenden, nicht verfügbar.

Die meisten Connectors müssen Werte für die Felder AuthorizationUri und Resource bereitstellen. Beide Felder können text Werte oder eine Funktion mit einem Argument sein, die text value zurückgibt.

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Verbinder, die einen Uri-basierten Bezeichner verwenden, müssen keinen Resource Wert angeben. Standardmäßig ist der Wert gleich dem Wurzelpfad des Uri-Parameters des Connectors. Wenn die Azure AD-Ressource der Datenquelle vom Domänenwert abweicht (z. B. weil sie eine GUID verwendet), muss ein Resource -Wert angegeben werden.

Aad-Authentifizierung Art Muster

Im folgenden Fall unterstützt die Datenquelle die globale Cloud Azure AD unter Verwendung des gemeinsamen Mandanten (keine Unterstützung von Azure B2B). Beim Anfordern des Standardbereichs wird ein Token mit allen zuvor autorisierten Bereichen für die Power Query-Clientanwendungs-ID zurückgegeben.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Im folgenden Fall unterstützt die Datenquelle die Mieterkennung auf der Grundlage von OpenID Connect (OIDC) oder einem ähnlichen Protokoll. Diese Fähigkeit ermöglicht es dem Konnektor, den richtigen Azure AD-Endpunkt zu bestimmen, der basierend auf einem oder mehreren Parametern im Datenquellenpfad zu verwenden ist. Dieser dynamische Erkennungsansatz ermöglicht es dem Connector, Azure B2B zu unterstützen.

// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication.", [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication.");

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Microsoft Entra ID resource value for your service - Guid or URL
        Scope = ".default"
    ]
]

Andere Arten der Authentifizierung

Informationen zu anderen Arten der Authentifizierung, die in diesem Artikel nicht behandelt werden, wie z. B. Kerberos-basiertes Single Sign-On, finden Sie im Artikel additional connector functionality .