Spracovanie overovania

Článok
03/19/2024

Typy overovania

Rozšírenie môže podporovať jeden alebo viac druhov overovania. Každý typ overenia je iný typ poverení. Používateľské rozhranie overovania, ktoré sa zobrazuje koncovým používateľom v doplnku Power Query, je riadené typom poverení, ktoré rozšírenie podporuje.

Zoznam podporovaných typov overovania je definovaný ako súčasť definície typu zdroja údajov rozšírenia. Každá hodnota overovania je záznam so špecifickými poľami. Nasledujúca tabuľka obsahuje zoznam očakávaných polí pre každý druh. Všetky polia sa vyžadujú, pokiaľ nie sú označené inak.

Typ overenia	Pole	Description
Anonymné		Typ overenia Anonymné (nazývané `Implicit`aj ) neobsahuje žiadne polia.
OAuth	StartLogin	Funkcia, ktorá poskytuje URL adresu a informácie o stave na spustenie postupu OAuth. Prejdite do časti Implementácia postupu OAuth.
	FinishLogin	Funkcia, ktorá extrahuje access_token a ďalšie vlastnosti súvisiace s postupom OAuth.
	Obnoviť	(voliteľné) Funkcia, ktorá načíta nový prístupový token z tokenu obnovenia.
	Odhlásiť sa	(voliteľné) Funkcia, ktorá zruší aktuálny prístupový token používateľa.
	Označenie	(voliteľné) Textová hodnota, ktorá umožňuje prepísať predvolené označenie pre túto vlastnosť AuthenticationKind.
Aad	AuthorizationUri	`text` value alebo unary function, ktorá vráti koncový bod oprávnenia Microsoft Entra ID (príklad: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Prejdite do časti Overenie ID microsoft Entra.
	Resource	`text` alebo unárnu funkciu, ktorá vráti hodnotu zdroja Microsoft Entra ID pre vašu službu.
	Scope	(voliteľné) `text` value alebo unary function, ktorá vráti zoznam rozsahov, o ktoré sa má požiadať ako súčasť postupu overovania. Viaceré hodnoty rozsahu by mali byť oddelené medzerou. Hodnota rozsahu by mala byť názvom rozsahu bez identifikátora URI ID aplikácie (príklad: `Data.Read`). Ak nie je zadaný, `user_impersonation` rozsah sa požaduje.
UsernamePassword	UsernameLabel	(voliteľné) Textová hodnota na nahradenie predvoleného označenia pre textové pole Meno používateľa v používateľskom rozhraní poverení.
	PasswordLabel	(voliteľné) Textová hodnota na nahradenie predvoleného označenia textového poľa Heslo v používateľskom rozhraní poverení.
	Označenie	(voliteľné) Textová hodnota, ktorá umožňuje prepísať predvolené označenie pre túto vlastnosť AuthenticationKind.
Windows	UsernameLabel	(voliteľné) Textová hodnota na nahradenie predvoleného označenia pre textové pole Meno používateľa v používateľskom rozhraní poverení.
	PasswordLabel	(voliteľné) Textová hodnota na nahradenie predvoleného označenia textového poľa Heslo v používateľskom rozhraní poverení.
	Označenie	(voliteľné) Textová hodnota, ktorá umožňuje prepísať predvolené označenie pre túto vlastnosť AuthenticationKind.
Kľúč	KeyLabel	(voliteľné) Textová hodnota na nahradenie predvoleného označenia textového poľa kľúča rozhrania API v používateľskom rozhraní poverení.
	Označenie	(voliteľné) Textová hodnota, ktorá umožňuje prepísať predvolené označenie pre túto vlastnosť AuthenticationKind.

Nasledujúca ukážka zobrazuje záznam overenia pre konektor, ktorý podporuje OAuth, Key, Windows, Basic (meno používateľa a heslo) a anonymné poverenia.

Príklad:

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

Prístup k aktuálnym povereniam

Aktuálne poverenia je možné načítať pomocou Extension.CurrentCredential funkcie .

Funkcie zdroja údajov M, ktoré boli povolené na rozšíriteľnosť, automaticky dedia rozsah poverení vášho rozšírenia. Vo väčšine prípadov nie je potrebný explicitný prístup k aktuálnym povereniam. Existujú však výnimky, ako napríklad:

Odovzdanie prihlasovacích údajov do vlastnej hlavičky alebo do parametra reťazca dotazu (napríklad pri používaní typu overenia Kľúč rozhrania API).
Nastavenie reťazec pripojenia vlastností pre ODBC alebo ADO.NET rozšírenia.
Kontrola vlastných vlastností v tokene OAuth.
Použitie poverení ako súčasť postupu OAuth v1.

Funkcia Extension.CurrentCredential vráti objekt záznamu. Polia, ktoré obsahuje, sú špecifické pre typ overenia. Nasledujúca tabuľka obsahuje podrobnosti.

Pole	Description	Používa sa
AuthenticationKind	Obsahuje názov druhu overenia priradeného k tomuto povereniu (UsernamePassword, OAuth atď.).	Všetko
Username	Hodnota mena používateľa	UsernamePassword, Windows
Heslo	Hodnota hesla. Zvyčajne sa používa s parametrom UsernamePassword, ale je tiež nastavený na možnosť Kľúč.	Kľúč, UsernamePassword, Windows
access_token	Hodnota prístupového tokenu OAuth.	OAuth
Vlastnosti	Záznam obsahujúci iné vlastné vlastnosti pre dané poverenie. Zvyčajne sa používa s OAuth na ukladanie iných vlastností (napríklad refresh_token) vrátených s access_token počas postupu overovania.	OAuth
Kľúč	Hodnota kľúča rozhrania API. Všimnite si, že hodnota kľúča je tiež k dispozícii v poli Heslo. Mashup modul predvolene vloží tento kľúč do hlavičky Authorization, akoby táto hodnota bola základným heslom overenia (bez mena používateľa). Ak tento typ správania nie je ten, ktorý chcete, musíte v zázname možností zadať možnosť ManualCredentials = true.	Kľúč
EncryptConnection	Logická hodnota, ktorá určuje, či sa má k zdroju údajov vyžadovať šifrované pripojenie. Táto hodnota je k dispozícii pre všetky typy overovania, ale nastaví sa len v prípade, že encryptConnection je špecifikovaná v definícii zdroja údajov.	Všetko

Nasledujúca ukážka kódu pristupuje k aktuálnemu povereniu pre kľúč rozhrania API a používa ho na vyplnenie vlastnej hlavičky (x-APIKey).

Prí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

Implementácia postupu overovania OAuth

Typ overovania OAuth umožňuje rozšíreniu implementovať vlastnú logiku pre svoju službu. Na tento účely rozšírenie poskytuje funkcie pre StartLogin (vrátenie identifikátora URI oprávnenia na spustenie postupu OAuth) a FinishLogin (výmenou kódu oprávnenia pre prístupový token). Rozšírenia môžu voliteľne implementovať Refresh (výmenou tokenu na obnovenie pre nový prístupový token) a Logout (po uplynutí platnosti aktuálneho obnovenia a prístupových tokenov) tiež.

Poznámka

Rozšírenia Power Query sa vyhodnocujú v aplikáciách spustených na klientskych počítačoch. Konektory údajov by vo svojich postupoch OAuth nemali používať dôverné tajné kódy, pretože používatelia môžu skontrolovať rozšírenie alebo sieťový prenos údajov a naučiť sa tajný kód. Ak chcete získať ďalšie podrobnosti o poskytovaní postupov, ktoré sa nespoliehajú na zdieľané tajomstvá, prejdite na časť Proof Key for Code Exchange od OAuth Public Clients RFC (známu aj ako PKCE). Vzorovú implementáciu tohto postupu nájdete na našej lokalite GitHub.

Existujú dve množiny podpisov funkcie OAuth: pôvodný podpis, ktorý obsahuje minimálny počet parametrov, a pokročilý podpis, ktorý prijíma viac parametrov. Väčšina postupov OAuth je možné implementovať s použitím pôvodných podpisov. Vo svojej implementácii môžete tiež kombinovať a zhodovať typy podpisov. Volania funkcie sú zhodné na základe počtu parametrov (a ich typov). Názvy parametrov sa nevezmú do úvahy.

Ďalšie podrobnosti nájdete v ukážke služby GitHub.

Pôvodné podpisy OAuth

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

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

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

Logout = (accessToken) => ...;

Rozšírené podpisy overovania OAuth

Poznámky o pokročilých podpisoch:

Všetky podpisy akceptujú hodnotu záznamu clientApplication , ktorá je vyhradená pre budúce použitie.
Všetky podpisy akceptujú a dataSourcePath (označuje sa aj ako resourceUrl vo väčšine ukážok).
Funkcia Refresh prijme oldCredential parameter, čo je predchádzajúci record výsledok vrátený funkciou FinishLogin (alebo predchádzajúce volanie funkcie Refresh).

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

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

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

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

Overenie ID Microsoft Entra

Typ Aad overenia je špecializovaná verzia OAuth pre Microsoft Entra ID. Používa rovnaký klient Microsoft Entra ID ako vstavané konektory Power Query, ktoré podporujú overovanie konta organizácie. Ďalšie informácie nájdete v téme Konfigurácia služby Microsoft Entra, kde nájdete príručku so stručným návodom pre vlastný konektor .

Poznámka

Ak implementujete vlastný postup OAuth pre ID služby Microsoft Entra, používateľom, ktorí pre nájomníka povolili podmienený prístup, sa môžu pri obnovovaní pomocou služba Power BI vyskytnúť problémy. Obnovenie založené na bráne to neovplyvní, ale ovplyvní certifikovaný konektor, ktorý podporuje obnovenie z služba Power BI. Používateľom sa môže vyskytnúť problém vyplývajúci z konektora pomocou verejnej klientskej aplikácie pri konfigurácii webových poverení prostredníctvom služba Power BI. Prístupový token vygenerovaný týmto postupom sa nakoniec použije v inom počítači (t. j. v služba Power BI v údajovom centre Azure, nie v sieti spoločnosti), než je ten, ktorý bol použitý na pôvodné overenie (teda počítač používateľa, ktorý konfiguruje poverenia zdroja údajov v sieti spoločnosti). Aad Tento problém sa rieši pomocou iného klienta Microsoft Entra ID pri konfigurácii poverení v služba Power BI. Táto možnosť nebude k dispozícii pre konektory, ktoré používajú OAuth typ overenia.

Väčšina konektorov musí poskytovať hodnoty pre AuthorizationUri polia a Resource . Obe polia môžu byť text hodnoty alebo jedna funkcia argumentu text value, ktorá vráti .

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)

Konektory, ktoré používajú identifikátor založený na identifikátore Uri, nemusia Resource zadať hodnotu. Predvolene sa hodnota rovná koreňovej ceste parametra Uri konektora. Ak je zdroj Microsoft Entra ID zdroja údajov iný ako hodnota domény (napríklad používa identifikátor GUID), Resource je potrebné zadať hodnotu.

Ukážky druhov overovania Aad

V nasledujúcom prípade zdroj údajov podporuje globálne cloudové id entra spoločnosti Microsoft pomocou bežného nájomníka (žiadna podpora pre Azure B2B). Žiadosť o .default scope vráti token so všetkými predtým povolenými rozsahmi pre ID klientskej aplikácie 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 nasledujúcom prípade zdroj údajov podporuje vyhľadávanie nájomníkov na základe openid connect (OIDC) alebo podobného protokolu. Táto možnosť umožňuje konektoru určiť správny koncový bod MICROSOFT Entra ID, ktorý sa má použiť na základe jedného alebo viacerých parametrov v ceste k zdroju údajov. Tento prístup dynamického zisťovania umožňuje konektoru podporovať 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"
    ]
]

Iné typy overovania

Ďalšie informácie o iných typoch overenia, ktoré nie sú uvedené v tomto článku, ako je napríklad jediné prihlásenie založené na protokole Kerberos, nájdete v článku o ďalších funkciách konektora .

Zdieľať cez