Zpracování ověřování

Článek
03/19/2024

Typy ověřování

Rozšíření může podporovat jeden nebo více typů ověřování. Každý druh ověřování je jiný typ přihlašovacích údajů. Uživatelské rozhraní ověřování zobrazené koncovým uživatelům v Power Query je řízené typem přihlašovacích údajů, které rozšíření podporuje.

Seznam podporovaných typů ověřování je definován jako součást definice typu zdroje dat rozšíření. Každá hodnota ověřování je záznam s konkrétními poli. Následující tabulka uvádí očekávaná pole pro každý druh. Všechna pole jsou povinná, pokud nejsou označena jinak.

Druh ověřování	Pole	Popis
Anonymní		Typ ověřování Anonymní (označovaný také jako `Implicit`) neobsahuje žádná pole.
OAuth	StartLogin	Funkce, která poskytuje adresu URL a informace o stavu pro spuštění toku OAuth. Přejděte do části Implementace toku OAuth.
	FinishLogin	Funkce, která extrahuje access_token a další vlastnosti související s tokem OAuth.
	Aktualizovat	(volitelné) Funkce, která načte nový přístupový token z obnovovacího tokenu.
	Odhlášení	(volitelné) Funkce, která zneplatňuje aktuální přístupový token uživatele.
	Popisek	(volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento AuthenticationKind.
Aad	Autorizační identifikátor URI	`text` hodnota nebo unární funkce, která vrací koncový bod autorizace Microsoft Entra ID (příklad: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Přejděte do části ověřování Microsoft Entra ID.
	Prostředek	`text` hodnota nebo unární funkce, která vrací hodnotu prostředku Microsoft Entra ID pro vaši službu.
	Obor	(volitelné)`text` hodnota nebo unární funkce, která vrací seznam oborů, které se mají vyžádat jako součást ověřovacího toku. Více hodnot oboru by mělo být odděleno mezerou. Hodnota oboru by měla být název oboru bez identifikátoru URI ID aplikace (například: `Data.Read`). Pokud ho nezadáte, `user_impersonation` je požadován rozsah.
UsernamePassword	UsernameLabel	(volitelné) Textová hodnota, která nahradí výchozí popisek textového pole Uživatelské jméno v uživatelském rozhraní přihlašovacích údajů.
	PasswordLabel	(volitelné) Textová hodnota, která nahradí výchozí popisek textového pole Heslo v uživatelském rozhraní přihlašovacích údajů.
	Popisek	(volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento AuthenticationKind.
Windows	UsernameLabel	(volitelné) Textová hodnota, která nahradí výchozí popisek textového pole Uživatelské jméno v uživatelském rozhraní přihlašovacích údajů.
	PasswordLabel	(volitelné) Textová hodnota, která nahradí výchozí popisek textového pole Heslo v uživatelském rozhraní přihlašovacích údajů.
	Popisek	(volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento AuthenticationKind.
Klíč	KeyLabel	(volitelné) Textová hodnota, která nahradí výchozí popisek textového pole klíč rozhraní API v uživatelském rozhraní přihlašovacích údajů.
	Popisek	(volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento AuthenticationKind.

Následující ukázka ukazuje záznam ověřování konektoru, který podporuje OAuth, Key, Windows, Basic (uživatelské jméno a heslo) a anonymní přihlašovací údaje.

Příklad:

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

Přístup k aktuálním přihlašovacím údajům

Aktuální přihlašovací údaje je možné načíst pomocí Extension.CurrentCredential funkce.

Funkce zdroje dat M, které byly povoleny pro rozšiřitelnost, automaticky dědí obor přihlašovacích údajů vašeho rozšíření. Ve většině případů nemusíte explicitně přistupovat k aktuálním přihlašovacím údajům, ale existují výjimky, například:

Předání přihlašovacích údajů do vlastní hlavičky nebo parametru řetězce dotazu (například při použití typu ověřování klíče rozhraní API)
Nastavení vlastností připojovací řetězec pro rozšíření ODBC nebo ADO.NET
Kontrola vlastních vlastností tokenu OAuth
Použití přihlašovacích údajů jako součásti toku OAuth v1

Funkce Extension.CurrentCredential vrátí objekt záznamu. Pole, která obsahuje, jsou specifická pro typ ověřování. Následující tabulka obsahuje podrobnosti.

Pole	Popis	Používá
AuthenticationKind	Obsahuje název ověřovacího typu přiřazeného k tomuto pověření (UsernamePassword, OAuth atd.).	Vše
Username	Hodnota uživatelského jména	UsernamePassword, Windows
Heslo	Hodnota hesla. Obvykle se používá s usernamePassword, ale je také nastaven pro klíč.	Klíč, UsernamePassword, Windows
access_token	Hodnota přístupového tokenu OAuth	OAuth
Vlastnosti	Záznam obsahující další vlastní vlastnosti pro dané přihlašovací údaje. Obvykle se používá s OAuth k ukládání dalších vlastností (například refresh_token) vrácených s access_token během ověřovacího toku.	OAuth
Klíč	Hodnota klíče rozhraní API. Všimněte si, že hodnota klíče je také k dispozici v poli Heslo. Ve výchozím nastavení mashupový modul vloží tento klíč do autorizační hlavičky, jako by tato hodnota byla základní ověřovací heslo (bez uživatelského jména). Pokud tento typ chování není to, co chcete, musíte v záznamu možností zadat možnost ManualCredentials = true.	Klíč
Šifrování Připojení ion	Logická hodnota, která určila, jestli se má vyžadovat šifrované připojení ke zdroji dat. Tato hodnota je k dispozici pro všechny druhy ověřování, ale je nastavena pouze v případě, že je v definici zdroje dat zadána funkce Encrypt Připojení ion.	Vše

Následující ukázka kódu přistupuje k aktuálním přihlašovacím údajům pro klíč rozhraní API a používá ho k naplnění vlastní hlavičky (x-APIKey).

Příklad:

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

Implementace toku OAuth

Typ ověřování OAuth umožňuje rozšíření implementovat vlastní logiku pro svou službu. K tomu rozšíření poskytuje funkce StartLogin (vrácení autorizačního identifikátoru URI pro zahájení toku OAuth) a FinishLogin (výměna autorizačního kódu pro přístupový token). Rozšíření můžou volitelně implementovat Refresh (výměnou obnovovacího tokenu pro nový přístupový token) a Logout (vypršení platnosti aktuální aktualizace a přístupových tokenů).

Poznámka:

Rozšíření Power Query se vyhodnocují v aplikacích spuštěných na klientských počítačích. Data Připojení orům by ve svých tocích OAuth neměly používat důvěrné tajné kódy, protože uživatelé můžou zkontrolovat rozšíření nebo síťový provoz, aby se dozvěděli tajný kód. Další podrobnosti o poskytování toků, které nespoléhají na sdílené tajné kódy, najdete v dokumentu RFC veřejných klientů OAuth (označovaný také jako PKCE). Ukázkovou implementaci tohoto toku najdete na našem webu GitHubu.

Existují dvě sady podpisů funkce OAuth: původní podpis, který obsahuje minimální počet parametrů, a pokročilý podpis, který přijímá další parametry. Většinu toků OAuth je možné implementovat pomocí původních podpisů. V implementaci můžete také kombinovat a shodovat typy podpisů. Volání funkce jsou shodná podle počtu parametrů (a jejich typů). Názvy parametrů se nevezmou v úvahu.

Další podrobnosti najdete v ukázce GitHubu.

Původní podpisy OAuth

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

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

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

Logout = (accessToken) => ...;

Pokročilé podpisy OAuth

Poznámky k pokročilým podpisům:

Všechny podpisy přijímají hodnotu záznamu clientApplication , která je vyhrazena pro budoucí použití.
Všechny podpisy přijímají ( dataSourcePath označované také jako resourceUrl ve většině ukázek).
Funkce Refresh přijímá oldCredential parametr, který je předchozí record vrácenou funkcí FinishLogin (nebo předchozím voláním Refresh).

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

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

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

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

Ověřování Microsoft Entra ID

Druh Aad ověřování je specializovaná verze OAuth pro ID Microsoft Entra. Používá stejného klienta Microsoft Entra ID jako integrované konektory Power Query, které podporují ověřování účtů organizace. Další informace najdete v průvodci rychlým startem konfigurace Microsoft Entra pro vlastní konektor .

Poznámka:

Pokud implementujete vlastní tok OAuth pro ID Microsoft Entra, můžou se uživatelům, kteří pro svého tenanta povolili podmíněný přístup, setkat s problémy při aktualizaci pomocí služba Power BI. To nebude mít vliv na aktualizaci založenou na bráně, ale mělo by to vliv na certifikovaný konektor, který podporuje aktualizaci z služba Power BI. Uživatelé můžou při konfiguraci webových přihlašovacích údajů prostřednictvím služba Power BI narazit na problém vyplývající z konektoru pomocí veřejné klientské aplikace. Přístupový token vygenerovaný tímto tokem se nakonec použije na jiném počítači (to znamená služba Power BI v datovém centru Azure, ne v síti společnosti) než na počítači použitém k původnímu ověření (tedy počítač uživatele, který konfiguruje přihlašovací údaje ke zdroji dat v síti společnosti). Předdefinovaný Aad typ tento problém řeší pomocí jiného klienta Microsoft Entra ID při konfiguraci přihlašovacích údajů v služba Power BI. Tato možnost nebude dostupná pro konektory, které používají OAuth druh ověřování.

Většina konektorů musí poskytovat hodnoty pro AuthorizationUri pole a Resource pole. Obě pole mohou být text hodnoty nebo jedna funkce argumentu text value, která vrací .

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)

Připojení otory, které používají Identifikátor založený na identifikátoru URI nemusí zadávat Resource hodnotu. Ve výchozím nastavení se hodnota rovná kořenové cestě parametru URI konektoru. Pokud se prostředek Microsoft Entra ID zdroje dat liší od hodnoty domény (například používá identifikátor GUID), Resource je potřeba poskytnout hodnotu.

Ukázky typu ověřování Aad

V následujícím případě zdroj dat podporuje globální cloudové ID Microsoft Entra s použitím společného tenanta (bez podpory Azure B2B). Vyžádání výchozího oboru vrátí token se všemi dříve autorizovanými obory pro ID klientské aplikace 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"
    ]
]

V následujícím případě zdroj dat podporuje zjišťování tenantů na základě OpenID Připojení (OIDC) nebo podobného protokolu. Tato schopnost umožňuje konektoru určit správný koncový bod ID Microsoft Entra, který se má použít na základě jednoho nebo více parametrů v cestě ke zdroji dat. Tento přístup dynamického zjišťování umožňuje konektoru podporovat 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"
    ]
]

Další typy ověřování

Další informace o dalších typech ověřování, které nejsou popsané v tomto článku, jako je jednotné přihlašování založené na protokolu Kerberos, najdete v článku o dalších funkcích konektoru .

Share via