Sdílet prostřednictvím

Zpracování ověřování

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á ověřovací hodnota 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í Obor Description
Anonymní Typ ověřování Anonymní (označovaný také jako Implicit) neobsahuje žádná pole.
OAuth ZahájitPřihlášení Funkce, která poskytuje adresu URL a informace o stavu pro spuštění toku OAuth.

Přejděte do části Implementace toku OAuth .
Dokončit přihlášení Funkce, která extrahuje access_token a další vlastnosti související s tokem OAuth.
Obnovit (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.
Označení (volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento AuthenticationKind.
Aad Autorizační 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 sekce ověřování Microsoft Entra ID.
Resource text hodnota nebo unární funkce, která vrací hodnotu prostředku Microsoft Entra ID pro vaši službu.
Scope (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 rozsahu by mělo být odděleno mezerou. Hodnota rozsahu by měla být název rozsahu bez URI identifikátoru ID aplikace (například: Data.Read). Pokud není zadán, je požadován rozsah user_impersonation.
UživatelskéJménoHeslo Štítek uživatelského jména (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ů.
Označení (volitelné) Textová hodnota, která umožňuje přepsat výchozí označení pro tento AuthenticationKind.
Windows Uživatelské jméno popisek (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ů.
Štítek hesla (volitelné) Textová hodnota, která nahradí výchozí popisek textového pole Heslo v uživatelském rozhraní přihlašovacích údajů.
Označení (volitelné) Textová hodnota, která umožňuje přepsat výchozí označení pro tento AuthenticationKind.
Key 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ů.
Označení (volitelné) Textová hodnota, která umožňuje přepsat výchozí popisek pro tento typ ověřování.

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.

Example:

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 přebírají rozsah 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ů prostřednictvím vlastní hlavičky nebo parametru řetězce dotazu (například při použití typu ověřování klíčem API)
  • Nastavení vlastností připojovacího řetězce 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.

Obor Description Používá
AuthenticationKind Obsahuje název ověřovacího typu přiřazeného k tomuto pověření (UsernamePassword, OAuth atd.). Všechno
Uživatelské jméno Hodnota uživatelského jména Uživatelské jméno a heslo, Windows
Heslo Hodnota hesla. Obvykle se používá s UsernamePassword, ale je to také nastaveno pro Key. Klíč, Uživatelské Jméno a Heslo, 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
Key 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. Key
EncryptConnection Logická hodnota, která určila, jestli se má vyžadovat šifrované připojení ke zdroji dat. Tato hodnota je k dispozici pro všechny typy ověřování, ale je nastavena pouze v případě, že je v definici zdroje dat zadán EncryptConnection. Všechno

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

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

Implementace procesu OAuth

Typ ověřování OAuth umožňuje rozšíření implementovat vlastní logiku pro 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. Datové konektory 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 používání toků, které nespoléhají na sdílené tajné kódy, naleznete v dokumentu PKCE (Proof Key for Code Exchange) pro veřejné klienty OAuth podle RFC. 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á parametr oldCredential, který je předchozí record, vrácený 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í ID Microsoft Entra

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 příručce rychlého startu konfigurace Microsoft Entra pro vlastní konektor.

Poznámka:

Pokud implementujete vlastní tok OAuth pro Microsoft Entra ID, mohou uživatelé, kteří pro svého tenanta povolili podmíněný přístup, narazit na problémy při aktualizaci pomocí služby 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 ze služby Power BI. Uživatelé můžou narazit na problém vyplývající z konektoru pomocí veřejné klientské aplikace při konfiguraci webových přihlašovacích údajů prostřednictvím služby Power BI. Přístupový token vygenerovaný tímto tokem se nakonec použije na jiném počítači (tedy ve službě 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 na počítači 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ů ve službě 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 jednofunkční argument, který vrací text value.

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)

Konektory, 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), je třeba poskytnout hodnotu Resource.

Ukázky druhů 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 = "44445555-eeee-6666-ffff-7777aaaa8888", // 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 Connect (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 .

  • Last updated on