Freigeben über

Verwaltung der Authentifizierung

Authentifizierungstypen

Eine Erweiterung kann eine oder mehrere Arten von Authentifizierung unterstützen. Jede Authentifizierungsart ist ein unterschiedlicher Typ von Anmeldedaten. Die für Endbenutzer in Power Query angezeigte Authentifizierungsoberfläche wird durch den Typ der Anmeldeinformationen gesteuert, die eine Erweiterung unterstützt.

Die Liste der unterstützten Authentifizierungstypen wird als Teil der Data Source Kind-Definition einer Erweiterung definiert. Jeder Authentifizierungswert ist ein Datensatz mit bestimmten Feldern. In der folgenden Tabelle sind die erwarteten Felder für jede Art aufgeführt. Alle Felder sind erforderlich, sofern nicht anders markiert.

Authentifizierungsart Feld Description
Anonym Die Authentifizierungsart "Anonym" (auch als "Anonym" bezeichnet Implicit) weist keine Felder auf.
OAuth StartLogin Funktion, die die URL- und Statusinformationen zum Starten eines OAuth-Flusses bereitstellt.

Wechseln Sie zum Abschnitt "Implementieren eines OAuth-Flusses ".
LoginAbschließen Funktion, die die access_token und andere Eigenschaften im Zusammenhang mit dem OAuth-Fluss extrahiert.
Refresh (optional) Funktion, die ein neues Zugriffstoken aus einem Refresh-Token abruft.
Logout (optional) Funktion, die das aktuelle Zugriffstoken des Benutzers ungültig macht.
Etikett (optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind außer Kraft setzen können.
Aad Autorisierungs-URI text Wert oder unäre Funktion, die den Microsoft Entra ID-Autorisierungsendpunkt 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, die den Microsoft Entra ID-Ressourcenwert für Ihren Dienst zurückgibt.
Geltungsbereich (optional)text Wert oder unäre Funktion, die die Liste der Bereiche zurückgibt, die als Teil des Authentifizierungsflusses angefordert werden sollen. Mehrere Bereichswerte sollten durch ein Leerzeichen getrennt werden. Der Bereichswert sollte der Bereichsname sein, ohne einen Anwendungs-ID-URI (Beispiel: Data.Read). Wenn nicht angegeben, wird der user_impersonation Bereich angefordert.
BenutzernamePasswort BenutzernameBezeichner (optional) Ein Textwert, der die Standardbeschriftung für das Textfeld "Benutzername " auf der Anmeldeinformationsbenutzeroberfläche ersetzt.
PasswortLabel (optional) Ein Textwert, der die Standardbeschriftung für das Textfeld "Kennwort " auf der Anmeldeinformationsbenutzeroberfläche ersetzt.
Etikett (optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind außer Kraft setzen können.
Fenster Benutzername-Etikett (optional) Ein Textwert, der die Standardbeschriftung für das Textfeld "Benutzername " auf der Anmeldeinformationsbenutzeroberfläche ersetzt.
Passwortfeld (optional) Ein Textwert, der die Standardbeschriftung für das Textfeld "Kennwort " auf der Anmeldeinformationsbenutzeroberfläche ersetzt.
Etikett (optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind außer Kraft setzen können.
Key KeyLabel (optional) Ein Textwert, der die Standardbezeichnung für das Textfeld "API-Schlüssel " auf der Anmeldeinformationsbenutzeroberfläche ersetzt.
Etikett (optional) Ein Textwert, mit dem Sie die Standardbezeichnung für diese AuthenticationKind außer Kraft setzen können.

Das folgende Beispiel zeigt den Authentifizierungseintrag für einen Connector, der OAuth, Key, Windows, Basic (Benutzername und Kennwort) und anonyme Anmeldeinformationen unterstützt.

Example:

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

Zugreifen auf die aktuellen Anmeldeinformationen

Die aktuellen Anmeldeinformationen können mithilfe der Extension.CurrentCredential Funktion abgerufen werden.

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

  • Übergeben der Anmeldeinformationen in einem benutzerdefinierten Header- oder Query-String-Parameter (z. B. wenn Sie die API-Schlüssel-Authentifizierung verwenden).
  • Festlegen von Verbindungszeichenfolgeneigenschaften für ODBC- oder ADO.NET-Erweiterungen.
  • Überprüfen benutzerdefinierter Eigenschaften für ein OAuth-Token.
  • Verwenden der Anmeldeinformationen als Teil eines OAuth v1-Flusses.

Die Extension.CurrentCredential Funktion gibt ein Datensatzobjekt zurück. Die darin enthaltenen Felder sind Authentifizierungstypspezifisch. Die folgende Tabelle enthält Details.

Feld Description Verwendet von
AuthenticationKind Enthält den Namen der Authentifizierungsart, die diesen Anmeldeinformationen zugewiesen ist (UsernamePassword, OAuth usw.). All
Nutzername Benutzernamewert BenutzernamePasswort, Windows
Kennwort Kennwortwert. Wird normalerweise mit UsernamePassword verwendet, ist jedoch auch für Key festgelegt. Key, UsernamePassword, Windows
access_token OAuth-Zugriffstokenwert. OAuth
Eigenschaften Ein Eintrag, der andere benutzerdefinierte Eigenschaften für eine bestimmte Zugangsdaten enthält. Wird in der Regel mit OAuth verwendet, um andere Eigenschaften (z. B. die refresh_token) zu speichern, die während des Authentifizierungsflusses mit dem access_token zurückgegeben werden. OAuth
Key Der API-Schlüsselwert. Beachten Sie, dass der Schlüsselwert auch im Feld "Kennwort" verfügbar ist. Standardmäßig fügt das Mashupmodul diesen Schlüssel in einen Autorisierungsheader ein, als wäre dieser Wert ein einfaches Authentifizierungskennwort (ohne Benutzername). Wenn diese Art von Verhalten nicht ihren Vorstellungen entspricht, müssen Sie die Option "ManualCredentials = true" im Optionsdatensatz angeben. Key
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 jedoch nur festgelegt, wenn EncryptConnection in der Datenquellendefinition angegeben ist. All

Im folgenden Codebeispiel wird auf die aktuellen Anmeldeinformationen für einen API-Schlüssel zugegriffen, um einen benutzerdefinierten Header (x-APIKey) zu füllen.

Example:

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

Implementieren eines OAuth-Flusses

Der OAuth-Authentifizierungstyp ermöglicht es einer Erweiterung, benutzerdefinierte Logik für ihren Dienst zu implementieren. Dazu stellt eine Erweiterung Funktionen für StartLogin (zurückgeben des Autorisierungs-URI zum Initiieren des OAuth-Flusses) und FinishLogin (Austausch des Autorisierungscodes für ein Zugriffstoken) bereit. Erweiterungen können optional Refresh (Eintausch eines Refresh-Tokens gegen ein neues Access-Token) und Logout (aktuelle Refresh- und Access-Token ablaufen zu lassen)-Funktionen implementieren.

Hinweis

Power Query-Erweiterungen werden in Anwendungen ausgewertet, die auf Clientcomputern ausgeführt werden. Daten-Connectors sollten in ihren OAuth-Vorgängen keine vertraulichen Informationen verwenden, da Benutzer die Erweiterung oder den Netzwerkdatenverkehr überprüfen können, um das Geheimnis zu erfahren. Wechseln Sie zu "Proof Key for Code Exchange" von OAuth Public Clients RFC (auch als PKCE bezeichnet), um weitere Details zur Bereitstellung von Flüssen zu erhalten, die nicht auf freigegebene geheime Schlüssel angewiesen sind. Eine Beispielimplementierung dieses Flusses finden Sie auf unserer GitHub-Website.

Es gibt zwei Sätze von OAuth-Funktionssignaturen: die ursprüngliche Signatur, die eine minimale Anzahl von Parametern enthält, und eine erweiterte Signatur, die weitere Parameter akzeptiert. Die meisten OAuth-Flüsse können mithilfe der ursprünglichen Signaturen implementiert werden. Sie können Signaturtypen auch in Ihrer Implementierung kombinieren und abgleichen. Die Funktionsaufrufe sind Übereinstimmungen basierend auf der Anzahl der Parameter (und deren Typen). Die Parameternamen werden nicht berücksichtigt.

Weitere Details finden Sie im GitHub-Beispiel .

Ursprüngliche OAuth-Signaturen

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

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

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

Logout = (accessToken) => ...;

Erweiterte OAuth-Signaturen

Hinweise zu den erweiterten Signaturen:

  • Alle Signaturen akzeptieren einen clientApplication Datensatzwert, der für die zukünftige Verwendung reserviert ist.
  • Alle Signaturen akzeptieren eine dataSourcePath (auch in den meisten Beispielen bezeichnet als resourceUrl).
  • Die Refresh Funktion akzeptiert einen oldCredential Parameter, bei dem es sich um den vorherigen record handelt, der von Ihrer FinishLogin Funktion zurückgegeben wurde (oder beim vorherigen Aufruf von Refresh).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

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

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

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

Microsoft Entra ID-Authentifizierung

Die Aad Authentifizierungsart ist eine spezielle Version von OAuth für Microsoft Entra ID. Er verwendet denselben Microsoft Entra ID-Client wie die integrierten Power Query-Connectors, die die Authentifizierung des Organisationskontos unterstützen. Weitere Informationen finden Sie im Schnellstarthandbuch zum Konfigurieren von Microsoft Entra für einen benutzerdefinierten Connector .

Hinweis

Wenn Sie Ihren eigenen OAuth-Fluss für Microsoft Entra-ID implementieren, könnten Benutzer, die den bedingten Zugriff für ihren Mandanten aktiviert haben, auf Probleme beim Aktualisieren mit dem Power BI-Dienst stoßen. Dies wirkt sich nicht auf die gatewaybasierte Aktualisierung aus, wirkt sich aber auf einen zertifizierten Connector aus, der die Aktualisierung vom Power BI-Dienst unterstützt. Bei der Konfiguration von webbasierter Anmeldeinformationen über den Power BI-Dienst können Probleme auftreten, die dadurch verursacht werden, dass der Connector eine öffentliche Clientanwendung verwendet. Das von diesem Fluss generierte Zugriffstoken wird letztendlich auf einem anderen Computer (d. a. dem Power BI-Dienst in einem Azure-Rechenzentrum, nicht im Netzwerk des Unternehmens) verwendet als das Zugriffstoken, das zum ursprünglichen Authentifizieren verwendet wird (d. a. der Computer des Benutzers, der die Datenquellenanmeldeinformationen im Netzwerk des Unternehmens konfiguriert). Der integrierte Typ umgeht dieses Problem, indem er bei der Konfiguration von Anmeldeinformationen im Power BI-Dienst einen anderen Microsoft Entra ID-Client verwendet Aad. Diese Option ist für Connectors, die die OAuth Authentifizierungsart verwenden, nicht verfügbar.

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

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

AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)

Resource = "44445555-eeee-6666-ffff-7777aaaa8888"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Connectors, die einen URI-basierten Bezeichner verwenden, müssen keinen Wert angeben Resource . Standardmäßig ist der Wert gleich dem Stammpfad des URI-Parameters des Connectors. Wenn sich die Microsoft Entra-ID-Ressource der Datenquelle von dem Domänenwert unterscheidet (z. B. eine GUID), muss ein Resource Wert angegeben werden.

Beispiele für AAD-Authentifizierungsarten

Im folgenden Fall unterstützt die Datenquelle die globale Cloud Microsoft Entra ID mithilfe des gemeinsamen Mandanten (keine Azure B2B-Unterstützung). Das Anfordern des Standardbereichs gibt ein Token mit allen zuvor autorisierten Bereichen für die Power Query-Clientanwendungs-ID zurück.

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "44445555-eeee-6666-ffff-7777aaaa8888", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Im folgenden Fall unterstützt die Datenquelle die Mandantenermittlung basierend auf OpenID Connect (OIDC) oder einem ähnlichen Protokoll. Mit dieser Möglichkeit kann der Connector den richtigen Microsoft Entra ID-Endpunkt ermitteln, der basierend auf einem oder mehreren Parametern im Datenquellenpfad verwendet werden soll. Dieser dynamische Ermittlungsansatz 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 Authentifizierungstypen

Weitere Informationen zu anderen Authentifizierungstypen, die in diesem Artikel nicht behandelt werden, z. B. Kerberos-basiertes Einmaliges Anmelden, finden Sie im Artikel zu weiteren Connectorfunktionen .

  • Last updated on