Obsługa uwierzytelniania

Artykuł
03/19/2024

Rodzaje uwierzytelniania

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

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	Pole	opis
Anonimowe		Typ uwierzytelniania anonimowego (nazywanego `Implicit`również ) nie ma żadnych pól.
OAuth	StartLogin	Funkcja, która udostępnia informacje o adresie URL i stanie uruchamiania przepływu OAuth. Przejdź do sekcji Implementowanie przepływu OAuth.
	Zakończloguj	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	Identyfikator AuthorizationUri	`text` wartość lub funkcja jednoargumentowa zwracająca punkt końcowy autoryzacji identyfikatora entra firmy Microsoft (na przykład: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Przejdź do sekcji Uwierzytelnianie za pomocą identyfikatora Entra firmy Microsoft.
	Zasób	`text` wartość lub funkcja jednoargumentowa zwracająca wartość zasobu Microsoft Entra ID dla usługi.
	Scope	(opcjonalnie)`text` wartość lub funkcja jednoargumentowa, 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 identyfikatora URI identyfikatora aplikacji (na przykład: `Data.Read`). Jeśli nie zostanie podany, `user_impersonation` żądany jest zakres.
UsernamePassword	UsernameLabel	(opcjonalnie) Wartość tekstowa zastępująca domyślną etykietę pola tekstowego Nazwa użytkownika w interfejsie użytkownika poświadczeń.
	PasswordLabel	(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	UsernameLabel	(opcjonalnie) Wartość tekstowa zastępująca domyślną etykietę pola tekstowego Nazwa użytkownika w interfejsie użytkownika poświadczeń.
	PasswordLabel	(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.
Klucz	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.

Przykład:

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 Extension.CurrentCredential funkcji .

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 w przypadku używania typu uwierzytelniania klucza interfejsu API).
Ustawianie właściwości parametry połączenia dla rozszerzeń ODBC lub ADO.NET.
Sprawdzanie właściwości niestandardowych na 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.

Pole	opis	Używane przez
AuthenticationKind	Zawiera nazwę rodzaju uwierzytelniania przypisanego do tego poświadczenia (UsernamePassword, OAuth itd.).	wszystkie
Username	Wartość nazwy użytkownika	UsernamePassword, 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 refresh_token) zwracanych z access_token podczas przepływu uwierzytelniania.	OAuth
Klucz	Wartość klucza interfejsu API. Należy pamiętać, że wartość klucza jest również dostępna w polu Hasło. Domyślnie aparat mashupu wstawia ten klucz w nagłówku autoryzacji tak, jakby ta wartość była podstawowym hasłem uwierzytelniania (bez nazwy użytkownika). Jeśli ten typ zachowania nie jest odpowiedni, musisz określić opcję ManualCredentials = true w rekordzie opcji opcji.	Klucz
Szyfruj Połączenie ion	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 ustawiona tylko wtedy, gdy w definicji źródła danych określono szyfrowanie Połączenie ion.	wszystkie

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

Przykład:

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 rozszerzenie implementowania niestandardowej logiki dla swojej 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 dla nowego tokenu dostępu) i Logout (wygasające bieżące tokeny odświeżania i dostępu).

Uwaga

Rozszerzenia Power Query są oceniane w aplikacjach działających na maszynach klienckich. Połączenie danych nie powinny używać poufnych wpisów tajnych w przepływach protokołu OAuth, ponieważ użytkownicy mogą sprawdzać rozszerzenie lub ruch sieciowy w celu poznania wpisu tajnego. Aby uzyskać więcej informacji na temat udostępniania przepływów, które nie korzystają z udostępnionych wpisów tajnych, przejdź do pozycji Klucz dowodowy dla wymiany kodu przez klienta publicznego 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. Wywołania funkcji są dopasowywane 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ą dataSourcePath element (nazywany resourceUrl również w większości przykładów).
Funkcja Refresh akceptuje oldCredential parametr , który jest poprzedni record zwrócony przez funkcję FinishLogin (lub poprzednie wywołanie metody ).Refresh

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

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

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

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

Uwierzytelnianie identyfikatora Entra firmy Microsoft

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 dodatku Power Query, które obsługują uwierzytelnianie konta organizacyjnego. Więcej informacji można znaleźć w przewodniku Szybki start Dotyczącym konfigurowania usługi Microsoft Entra dla łącznika niestandardowego.

Uwaga

Jeśli zaimplementujesz własny przepływ OAuth dla identyfikatora Entra firmy Microsoft, użytkownicy, którzy włączyli dostęp warunkowy dla swojej dzierżawy, mogą napotkać problemy podczas odświeżania przy użyciu usługa Power BI. Nie wpłynie to na odświeżanie oparte na bramie, ale będzie miało wpływ na certyfikowany łącznik obsługujący odświeżanie z usługa 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ługa Power BI. Token dostępu wygenerowany przez ten przepływ będzie ostatecznie używany na innym komputerze (czyli usługa 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 działa wokół tego problemu przy użyciu innego klienta Microsoft Entra ID podczas konfigurowania poświadczeń w usługa Power BI. Ta opcja nie będzie dostępna dla łączników korzystających OAuth z rodzaju uwierzytelniania.

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

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)

Połączenie ory korzystające z Identyfikator oparty na identyfikatorze URI nie musi 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), Resource należy podać wartość.

Przykłady rodzaju uwierzytelniania usługi Aad

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

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

W poniższym przypadku źródło danych obsługuje odnajdywanie dzierżaw na podstawie Połączenie OpenID (OIDC) lub podobnego protokołu. Ta możliwość umożliwia łącznikowi określenie prawidłowego punktu końcowego identyfikatora entra firmy Microsoft do użycia na podstawie co najmniej jednego parametru w ścieżce źródła danych. To podejście do odnajdywania dynamicznego umożliwia łącznikowi obsługę usługi Azure B2B.


// 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.

Udostępnij za pośrednictwem