Todentamisen käsittely

Artikkeli
12/04/2024

Todennuslajit

Laajennus voi tukea yhtä tai useampaa todentamistyyppiä. Jokainen todennuslaji on erityyppinen tunnistetieto. Loppukäyttäjille Power Queryssä näytettävää todennuksen käyttöliittymää ohjaa tunnistetietojen tyyppi, jota laajennus tukee.

Tuettujen todennustyyppien luettelo on määritetty laajennuksen tietolähteen lajimääritelmän osana. Kukin todennusarvo on tietue, joka sisältää tietyt kentät. Seuraavassa taulukossa luetellaan kunkin lajien odotetut kentät. Kaikkia kenttiä tarvitaan, ellei niitä ole merkitty muulla tavalla.

Todennuslaji	Field	Kuvaus
Anonyymi		Anonyymin (kutsutaan `Implicit`myös ) todennuslajiksi ei ole kenttiä.
OAuth	StartLogin	Funktio, joka antaa URL-osoitteen ja tilatiedot OAuth-työnkulun aloittamista varten. Siirry OAuth-työnkulun toteuttaminen - osaan.
	FinishLogin	Funktio, joka poimii access_token ja muut OAuth-työnkulkuun liittyvät ominaisuudet.
	Päivitä	(valinnainen) Funktio, joka noutaa uuden käyttöoikeustietueen päivitystunnuksella.
	Kirjaudu ulos	(valinnainen) Funktio, joka mitätöi käyttäjän nykyisen käyttöoikeustietueen.
	Otsikko	(valinnainen) Tekstiarvo, jonka avulla voit ohittaa tämän AuthenticationKind-kohdan oletusotsikon.
Aad	Valtuutustieto	`text` -arvo tai yksiarvoinen funktio, joka palauttaa Microsoft Entra ID -valtuutuksen päätepisteen (esimerkki: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Siirry Microsoft Entra ID - todentamisen osioon.
	Resurssi	`text` -arvo tai yksiarvoinen funktio, joka palauttaa palvelusi Microsoft Entra ID -resurssiarvon.
	Vaikutusalue	(valinnainen) `text` -arvo tai yksiarvoinen funktio, joka palauttaa luettelon pyynnöistä osana todentamisen työnkulkua. Useita vaikutusalueen arvoja tulee erottaa välilyönnillä. Vaikutusalueen arvon tulee olla vaikutusalueen nimi ilman sovellustunnuksen URI:tä (esimerkki: `Data.Read`). Kun vaikutusaluetta ei anneta, `user_impersonation` sitä pyydetään.
UsernamePassword	UsernameLabel	(valinnainen) Tekstiarvo, joka korvaa tunnistetietojen käyttöliittymässä olevan Käyttäjänimi-tekstiruudun oletusotsikon.
	PasswordLabel	(valinnainen) Tekstiarvo, joka korvaa tunnistetietojen käyttöliittymän Salasana-tekstiruudun oletusotsikon.
	Otsikko	(valinnainen) Tekstiarvo, jonka avulla voit ohittaa tämän AuthenticationKind-kohdan oletusotsikon.
Windows	UsernameLabel	(valinnainen) Tekstiarvo, joka korvaa tunnistetietojen käyttöliittymässä olevan Käyttäjänimi-tekstiruudun oletusotsikon.
	PasswordLabel	(valinnainen) Tekstiarvo, joka korvaa tunnistetietojen käyttöliittymän Salasana-tekstiruudun oletusotsikon.
	Otsikko	(valinnainen) Tekstiarvo, jonka avulla voit ohittaa tämän AuthenticationKind-kohdan oletusotsikon.
Avain	KeyLabel	(valinnainen) Tekstiarvo, joka korvaa tunnistetietojen käyttöliittymässä olevan ohjelmointirajapinta-avain-tekstiruudun oletusotsikon.
	Otsikko	(valinnainen) Tekstiarvo, jonka avulla voit ohittaa tämän AuthenticationKind-kohdan oletusotsikon.

Seuraavassa esimerkissä näytetään OAuth-, Key-, Windows-, Basic- (käyttäjänimi ja salasana) -liittimen todennustietue sekä anonyymit tunnistetiedot.

Esimerkki:

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

Nykyisten tunnistetietojen käyttäminen

Nykyiset tunnistetiedot voidaan hakea käyttämällä -funktiota Extension.CurrentCredential .

M-tietolähdefunktiot, jotka on otettu käyttöön laajennettavuutta varten, perivät automaattisesti laajennuksen tunnistetietojen laajuuden. Useimmissa tapauksissa sinun ei tarvitse nimenomaisesti käyttää nykyisiä tunnistetietoja, mutta tähän liittyy kuitenkin poikkeuksia, kuten:

Tunnistetietojen välittäminen mukautettuun otsikkoon tai kyselymerkkijonoparametriin (esimerkiksi kun käytät ohjelmointirajapinnan avaimen todennustyyppiä).
ODBC- tai ADO.NET-laajennusten ominaisuuksien ühendusstring määrittäminen.
Mukautettujen ominaisuuksien tarkistaminen OAuth-tunnuksen kautta.
Tunnistetietojen käyttäminen OAuth v1 -työnkulun osana.

Funktio Extension.CurrentCredential palauttaa tietueobjektin. Sen sisältämät kentät ovat todennustyyppikohtaisia. Seuraavassa taulukossa on tietoja.

Field	Kuvaus	Käyttänyt
AuthenticationKind	Sisältää tälle tunnistetiedukselle määritetyn todennuslajin nimen (UsernamePassword, OAuth ja niin edelleen).	Kaikki
Username	Käyttäjänimi-arvo	UsernamePassword, Windows
salasanalla	Salasanan arvo. Käytetään yleensä usernamePassword-sarakkeen kanssa, mutta se on myös määritetty avaimeksi.	Key, UsernamePassword, Windows
access_token	OAuth-käyttöoikeustietueen arvo.	OAuth
Ominaisuudet	Tietue, joka sisältää muut mukautetut ominaisuudet annetulle tunnistetiedelle. Käytetään yleensä OAuthin kanssa muiden ominaisuuksien (kuten refresh_token) tallentamiseen, jotka palautetaan access_token todennuksen työnkulun aikana.	OAuth
Avain	Ohjelmointirajapinnan avaimen arvo. Huomaa, että avaimen arvo on käytettävissä myös Salasana-kentässä. Koostemoduuli lisää tämän avaimen oletusarvoisesti valtuutusotsikoon aivan kuin tämä arvo olisi perustodentamissalasana (ilman käyttäjänimeä). Jos tällainen toiminta ei ole haluamaasi, sinun on määritettävä ManualCredentials = true -asetus asetustietueessa.	Avain
SalausYhteys	Looginen arvo, joka selvitti, täytyykö tietolähteeseen olla salattu yhteys. Tämä arvo on käytettävissä kaikille todennustyypeille, mutta se määritetään vain, jos Salausyhteys on määritetty tietolähteen määrityksessä.	Kaikki

Seuraava koodiesimerkki käyttää ohjelmointirajapinta-avaimen nykyistä tunnistetietoa ja täyttää sen avulla mukautetun otsikon (x-APIKey).

Esimerkki:

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

OAuth-työnkulun toteuttaminen

OAuth-todennustyypin avulla laajennus voi toteuttaa oman palvelunsa mukautetun logiikan. Tätä varten StartLogin laajennus tarjoaa funktiot (valtuutus-URI:n, joka käynnistää OAuth-työnkulun) ja FinishLogin (valtuutuskoodin vaihtamisen käyttöoikeustietueeksi). Laajennukset voivat halutessaan ottaa käyttöön Refresh (vaihtaa päivitystunnuksen uudelle käyttöoikeustietueelle) ja Logout (nykyisen päivitys- ja käyttöoikeustietueen vanhentuminen) -funktion.

Muistiinpano

Power Query -laajennukset arvioidaan asiakaskoneissa suoritettavissa sovelluksissa. Tietoyhdistimien ei tulisi käyttää luottamuksellisia salaisuuksia OAuth-työnkuluissaan, koska käyttäjät voivat tarkastaa laajennuksen tai verkkoliikenteen oppiakseen salaisen koodin. Siirry OAuth Public Clients RFC:n (eli PKCE:n) koodinvaihtoa varten -kohtaan lisätietoja työnkulkujen tarjoamisesta, jotka eivät perustu jaettuihin salaisuuksiin. Esimerkki tämän työnkulun toteutuksesta löytyy GitHub-sivustostamme.

OAuth-funktion allekirjoituksia on kaksi joukkoa: alkuperäinen allekirjoitus, joka sisältää vähimmäismäärän parametreja, ja kehittynyt allekirjoitus, joka hyväksyy enemmän parametreja. Useimmat OAuth-työnkulut voidaan toteuttaa käyttämällä alkuperäisiä allekirjoituksia. Voit myös yhdistää ja sovittaa allekirjoitustyyppejä toteutuksessasi. Funktiokutsut ovat vastaavuuksia parametrien määrän (ja niiden tyyppien) perusteella. Parametrien nimiä ei oteta huomioon.

Lisätietoja saat GitHub-mallista .

Alkuperäiset OAuth-allekirjoitukset

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

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

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

Logout = (accessToken) => ...;

OAuth-lisäallekirjoitukset

Lisäallekirjoituksia koskevat huomautukset:

Kaikki allekirjoitukset hyväksyvät tietuearvon clientApplication , joka on varattu tulevaa käyttöä varten.
Kaikki allekirjoitukset hyväksyvät - dataSourcePath (kutsutaan myös nimellä resourceUrl useimmissa esimerkeissä).
Funktio Refresh hyväksyy parametrinoldCredential, joka on funktion FinishLogin palauttama edellinen record (tai edellinen kutsu kohteeseen Refresh).

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

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

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

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

Microsoft Entra ID -todennus

Todennuslaji Aad on OAuth-todennustyypin Erikoisversio Microsoft Entra -tunnukseen. Se käyttää samaa Microsoft Entra ID -asiakasohjelmistoa kuin organisaation tilin todentamista tukevat sisäiset Power Query -yhdistimet. Lisätietoja löytyy Microsoft Entran määrittäminen mukautetulle liittimelle -pikaoppaasta.

Muistiinpano

Jos otat käyttöön oman OAuth-työnkulun Microsoft Entra -tunnukseen, käyttäjät, jotka ovat ottaneet käyttöön ehdollisen käyttöoikeuden vuokraajaansa varten, saattavat kohdata ongelmia päivitettäessä Power BI teenus. Tämä ei vaikuta yhdyskäytäväpohjaiseen päivitykseen, mutta se vaikuttaa sertifioituun liittimeen, joka tukee Power BI teenus päivitystä. Käyttäjät saattavat kohdata ongelman, joka johtuu liittimestä julkisen asiakassovelluksen avulla, kun verkkopohjaisia tunnistetietoja määritetään Power BI teenus kautta. Tämän työnkulun luomaa käyttöoikeustietuetta käytetään lopulta toisessa tietokoneessa (eli Power BI teenus Azure-palvelinkeskuksessa, ei yrityksen verkossa), kuin mitä käytettiin alun perin todentamiseen (eli käyttäjän tietokoneeseen, joka määrittää tietolähteen tunnistetiedot yrityksen verkossa). Aad Sisäinen tyyppi toimii tämän ongelman ympärillä käyttämällä eri Microsoft Entra ID -asiakasohjelmaa tunnistetietoja määritettäessä Power BI teenus. Tämä vaihtoehto ei ole käytettävissä liittimille, jotka käyttävät OAuth todennustyyppiä.

Useimpien liittimien on tarjottava -ja-kenttiä AuthorizationUri Resource koskevat arvot. Molemmat kentät voivat olla text arvoja tai yksittäinen argumenttifunktio, joka palauttaa arvon 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)

Liittimien, jotka käyttävät Uri-pohjaista tunnistetta , ei tarvitse antaa Resource arvoa. Oletusarvon mukaan arvo on sama kuin liittimen Uri-parametrin pääpolku. Jos tietolähteen Microsoft Entra ID -resurssi on eri kuin toimialueen arvo (esimerkiksi käyttää GUID-tunnusta), Resource on annettava arvo.

Aad-todennuslajiesimerkit

Seuraavassa tapauksessa tietolähde tukee yleistä Microsoft Entra -pilvipalvelun tunnusta käyttämällä yleistä vuokraajaa (ei Azure B2B -tukea). .default-vaikutusalueen pyytäminen palauttaa tunnuksen, joka sisältää kaikki aiemmin valtuutetut alueet Power Query -asiakassovellustunnukselle.

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

Seuraavassa tapauksessa tietolähde tukee vuokraajan etsintää OpenID Connectin (OIDC) tai vastaavan protokollan perusteella. Tämän mahdollisuuden avulla liitin voi määrittää oikean Microsoft Entra ID -päätepisteen käytettäväksi yhden tai useamman tietolähdepolun parametrin perusteella. Tämän dynaamisen etsintätavan avulla liitin voi tukea Azure B2B:tä.


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

Muuntyyppiset todentamiset

Lisätietoja muista todennustyypeistä, joita ei tässä artikkelissa ole käsitelty, kuten Kerberos-pohjainen kertakirjautuminen, on liittimen lisätoimintoja käsittelevässä artikkelissa.

Jaa