Obsługa uwierzytelniania

Rodzaje uwierzytelniania

Rozszerzenie może obsługiwać co najmniej jeden rodzaj uwierzytelniania. Każdy rodzaj uwierzytelniania to inny typ poświadczeń. Interfejs uwierzytelniania użytkownika wyświetlany użytkownikom końcowym w dodatku Power Query jest zależny od typu poświadczeń, które obsługuje dodatek.

Lista obsługiwanych typów uwierzytelniania jest definiowana jako część definicji typu źródła danych rozszerzenia. Każda wartość uwierzytelniania jest rekordem z określonymi polami. W poniższej tabeli wymieniono oczekiwane pola dla każdego rodzaju. Wszystkie pola są wymagane, chyba że oznaczono inaczej.

Rodzaj uwierzytelniania	(No changes needed)	Description
Anonim		Typ uwierzytelniania anonimowego (nazywanego `Implicit`również ) nie ma żadnych pól.
OAuth	RozpocznijLogowanie	Funkcja, która udostępnia adres URL oraz informacje o stanie do uruchomienia przepływu OAuth. Przejdź do sekcji Implementowanie przepływu OAuth .
	Zakończ logowanie	Funkcja, która wyodrębnia access_token i inne właściwości związane z przepływem OAuth.
	Odśwież	(opcjonalnie) Funkcja, która pobiera nowy token dostępu z tokenu odświeżania.
	Wyloguj	(opcjonalnie) Funkcja, która unieważnia bieżący token dostępu użytkownika.
	Etykieta	(opcjonalnie) Wartość tekstowa, która umożliwia zastąpienie etykiety domyślnej dla tego elementu AuthenticationKind.
Aad	AuthorizationUri	`text` wartość lub funkcja jednoargumentowa zwracająca punkt końcowy autoryzacji Microsoft Entra ID (na przykład: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Przejdź do sekcji Uwierzytelnianie za pomocą identyfikatora Entra firmy Microsoft .
	Resource	`text` wartość lub funkcja jednoargumentowa zwracająca wartość zasobu Microsoft Entra ID dla Twojej usługi.
	Scope	(opcjonalnie)`text` wartość lub funkcja unarna, która zwraca listę zakresów do żądania w ramach przepływu uwierzytelniania. Wiele wartości zakresu powinno być rozdzielonych spacją. Wartość zakresu powinna być nazwą zakresu bez URI identyfikatora aplikacji (na przykład: `Data.Read`). Jeśli nie zostanie podany, zakres `user_impersonation` jest żądany.
Nazwa użytkownika i hasło	EtykietaNazwaUżytkownika	(opcjonalnie) Wartość tekstowa, która zastępuje domyślną etykietę dla pola tekstowego Nazwa użytkownika w interfejsie użytkownika poświadczeń.
	Etykieta Hasła	(opcjonalnie) Wartość tekstowa zastępująca domyślną etykietę pola tekstowego Hasło w interfejsie użytkownika poświadczeń.
	Etykieta	(opcjonalnie) Wartość tekstowa, która umożliwia zastąpienie etykiety domyślnej dla tego elementu AuthenticationKind.
Windows	EtykietaNazwaUżytkownika	(opcjonalnie) Wartość tekstowa, która zastępuje domyślną etykietę pola tekstowego Nazwa użytkownika w interfejsie poświadczeń.
	EtykietaHasła	(opcjonalnie) Wartość tekstowa zastępująca domyślną etykietę pola tekstowego Hasło w interfejsie użytkownika poświadczeń.
	Etykieta	(opcjonalnie) Wartość tekstowa, która umożliwia zastąpienie etykiety domyślnej dla tego elementu AuthenticationKind.
Key	Etykieta klucza	(opcjonalnie) Wartość tekstowa zastępująca domyślną etykietę pola tekstowego Klucz interfejsu API w interfejsie użytkownika poświadczeń.
	Etykieta	(opcjonalnie) Wartość tekstowa, która umożliwia zastąpienie etykiety domyślnej dla tego elementu AuthenticationKind.

W poniższym przykładzie przedstawiono rekord uwierzytelniania dla łącznika, który obsługuje poświadczenia OAuth, Key, Windows, Basic (nazwa użytkownika i hasło) oraz poświadczenia anonimowe.

Example:

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

Uzyskiwanie dostępu do bieżących poświadczeń

Bieżące poświadczenia można pobrać przy użyciu funkcji Extension.CurrentCredential.

Funkcje źródła danych języka M, które zostały włączone na potrzeby rozszerzalności, automatycznie dziedziczą zakres poświadczeń rozszerzenia. W większości przypadków nie trzeba jawnie uzyskiwać dostępu do bieżących poświadczeń, jednak istnieją wyjątki, takie jak:

Przekazywanie poświadczeń w niestandardowym nagłówku lub parametrze ciągu zapytania (na przykład gdy używasz typu uwierzytelniania klucza API).
Ustawianie właściwości parametrów połączenia dla rozszerzeń ODBC lub ADO.NET.
Sprawdzanie właściwości niestandardowych w tokenie OAuth.
Używanie poświadczeń w ramach przepływu OAuth w wersji 1.

Funkcja Extension.CurrentCredential zwraca obiekt rekordu. Pola, które zawiera, są specyficzne dla typu uwierzytelniania. Poniższa tabela zawiera szczegółowe informacje.

(No changes needed)	Description	Używane przez
AuthenticationKind	Zawiera nazwę rodzaju uwierzytelniania przypisanego do tego poświadczenia (UsernamePassword, OAuth itd.).	Wszystko
Nazwa użytkownika	Wartość nazwy użytkownika	Nazwa Użytkownika i Hasło, Windows
Hasło	Wartość hasła. Zazwyczaj używany z elementem UsernamePassword, ale jest również ustawiony dla opcji Klucz.	Key, UsernamePassword, Windows
access_token	Wartość tokenu dostępu OAuth.	OAuth
Właściwości	Rekord zawierający inne właściwości niestandardowe dla danego poświadczenia. Zazwyczaj używane z protokołem OAuth do przechowywania innych właściwości (takich jak token odświeżania, czyli refresh_token), które są zwracane razem z tokenem dostępu podczas procesu uwierzytelniania.	OAuth
Key	Wartość klucza interfejsu API. Należy pamiętać, że wartość klucza jest również dostępna w polu Hasło. Domyślnie silnik mashup wstawia ten klucz do nagłówka autoryzacji, jakby ta wartość była traktowana jako podstawowe hasło uwierzytelniania, bez nazwy użytkownika. Jeśli ten typ zachowania nie jest tym, czego chcesz, musisz określić opcję ManualCredentials = true w rekordzie opcji.	Key
Szyfruj Połączenie	Wartość logiczna określająca, czy wymagane jest zaszyfrowane połączenie ze źródłem danych. Ta wartość jest dostępna dla wszystkich rodzajów uwierzytelniania, ale jest ustawiana tylko wtedy, gdy element EncryptConnection jest określony w definicji źródła danych .	Wszystko

Poniższy przykładowy kod uzyskuje dostęp do bieżącego poświadczenia klucza API i używa go do wypełnienia nagłówka własnego (x-APIKey).

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

Implementowanie przepływu OAuth

Typ uwierzytelniania OAuth umożliwia rozszerzeniom implementowanie niestandardowej logiki dla danej usługi. W tym celu rozszerzenie udostępnia funkcje StartLogin (zwracając identyfikator URI autoryzacji w celu zainicjowania przepływu OAuth) i FinishLogin (wymieniając kod autoryzacji dla tokenu dostępu). Rozszerzenia mogą opcjonalnie implementować Refresh (wymieniając token odświeżania na nowy token dostępu) i Logout (wygaszenie bieżących tokenów odświeżania i dostępu).

Uwaga / Notatka

Rozszerzenia Power Query są oceniane w aplikacjach działających na maszynach klienckich. Łączniki danych nie powinny używać poufnych sekretów w przepływach OAuth, ponieważ użytkownicy mogą sprawdzać rozszerzenia lub ruch sieciowy, aby poznać sekret. Aby uzyskać więcej informacji na temat obsługi przepływów, które nie opierają się na współdzielonych tajemnicach, odwiedź RFC dotyczący Klucza dowodowego dla wymiany kodu przez publicznych klientów OAuth (znanego również jako PKCE). Przykładową implementację tego przepływu można znaleźć w naszej witrynie GitHub.

Istnieją dwa zestawy podpisów funkcji OAuth: oryginalny podpis zawierający minimalną liczbę parametrów i zaawansowany podpis, który akceptuje więcej parametrów. Większość przepływów OAuth można zaimplementować przy użyciu oryginalnych podpisów. W implementacji można również mieszać i dopasowywać typy podpisów. Dopasowania wywołań funkcji są dokonywane na podstawie liczby parametrów (i ich typów). Nazwy parametrów nie są brane pod uwagę.

Aby uzyskać więcej informacji, przejdź do przykładu usługi GitHub .

Oryginalne podpisy OAuth

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

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

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

Logout = (accessToken) => ...;

Zaawansowane podpisy OAuth

Uwagi dotyczące podpisów zaawansowanych:

Wszystkie podpisy akceptują wartość rekordu clientApplication , która jest zarezerwowana do użycia w przyszłości.
Wszystkie podpisy akceptują element dataSourcePath (nazywany również resourceUrl w większości przykładów).
Funkcja Refresh akceptuje parametr oldCredential, który jest poprzedni zwrócony record przez funkcję FinishLogin (lub poprzednie wywołanie Refresh).

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

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

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

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

Uwierzytelnianie za pomocą Microsoft Entra ID

Rodzaj Aad uwierzytelniania to wyspecjalizowana wersja protokołu OAuth dla identyfikatora Entra firmy Microsoft. Używa on tego samego klienta Microsoft Entra ID co wbudowane łączniki Power Query, które obsługują uwierzytelnianie konta organizacyjnego. Więcej informacji można znaleźć w przewodniku szybkiego startu dotyczącym konfigurowania usługi Microsoft Entra dla łącznika niestandardowego.

Uwaga / Notatka

Jeśli zaimplementujesz własny przepływ OAuth dla Microsoft Entra ID, użytkownicy, którzy włączyli dostęp warunkowy dla swojej dzierżawy, mogą napotkać problemy podczas odświeżania używając usługi Power BI. Nie wpłynie to na odświeżanie przez bramę, ale wpłynie na certyfikowany łącznik, który obsługuje odświeżanie z usługi Power BI. Użytkownicy mogą napotkać problem wynikający z łącznika przy użyciu publicznej aplikacji klienckiej podczas konfigurowania poświadczeń internetowych za pośrednictwem usługi Power BI. Token dostępu wygenerowany przez ten przepływ będzie ostatecznie używany na innym komputerze (czyli usłudze Power BI w centrum danych platformy Azure, a nie w sieci firmowej) niż ten używany do pierwotnego uwierzytelniania (czyli komputera użytkownika, który konfiguruje poświadczenia źródła danych w sieci firmy). Wbudowany Aad typ rozwiązuje ten problem, korzystając z innego klienta Microsoft Entra ID podczas konfigurowania poświadczeń w usłudze Power BI. Ta opcja nie będzie dostępna dla łączników korzystających z rodzaju uwierzytelniania OAuth.

Większość łączników musi podać wartości pól AuthorizationUri i Resource . Oba pola mogą być text wartościami lub funkcją z jednym argumentem zwracającą text value wartość.

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)

Łączniki korzystające z identyfikatora opartego na identyfikatorze URI nie muszą podawać Resource wartości. Domyślnie wartość jest równa ścieżce głównej parametru Uri łącznika. Jeśli zasób Microsoft Entra ID źródła danych różni się od wartości domeny (na przykład używa identyfikatora GUID), należy podać wartość Resource.

Przykłady typów uwierzytelniania AAD

W poniższym przypadku źródło danych obsługuje globalny identyfikator Microsoft Entra ID w chmurze przy użyciu wspólnego dzierżawcy (bez obsługi Azure B2B). Żądanie zakresu domyślnego zwraca token ze wszystkimi wcześniej autoryzowanymi zakresami dla identyfikatora aplikacji klienckiej Power Query.

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"
    ]
]

W poniższym przypadku źródło danych obsługuje odnajdywanie dzierżaw na podstawie protokołu OpenID Connect (OIDC) lub podobnego. Funkcja ta pozwala łącznikowi określić prawidłowy punkt końcowy identyfikatora Microsoft Entra, który należy użyć na podstawie jednego lub kilku parametrów w ścieżce do źródła danych. To dynamiczne podejście do odkrywania umożliwia obsługę Azure B2B przez łącznik.


// 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"
    ]
]

Inne typy uwierzytelniania

Aby uzyskać informacje na temat innych typów uwierzytelniania, które nie zostały opisane w tym artykule, takich jak logowanie jednokrotne oparte na protokole Kerberos, zapoznaj się z dodatkowym artykułem dotyczącym funkcji łącznika , aby dowiedzieć się więcej.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-26