Håndtering av godkjenning

Artikkel
03/19/2024

Godkjenningstyper

En utvidelse kan støtte én eller flere typer godkjenning. Hver godkjenningstype er en annen type legitimasjon. Brukergrensesnittet for godkjenning som vises for sluttbrukere i Power Query, drives av legitimasjonstypen(e) som en utvidelse støtter.

Listen over støttede godkjenningstyper er definert som en del av filtypens definisjon av datakildetype . Hver godkjenningsverdi er en post med bestemte felt. Tabellen nedenfor viser de forventede feltene for hver type. Alle felt kreves med mindre annet er merket.

Godkjenningstype	Felt	Bekrivelse
Anonym		Godkjenningstype for anonym (også kalt `Implicit`) har ingen felt.
OAuth	StartLogin	Funksjon som gir informasjon om nettadresse og tilstand for å starte en OAuth-flyt. Gå til delen Implementer en OAuth Flow .
	FinishLogin	Funksjon som trekker ut access_token og andre egenskaper som er relatert til OAuth-flyten.
	Oppdater	(valgfritt) Funksjon som henter et nytt tilgangstoken fra et oppdateringstoken.
	Logg av	(valgfritt) Funksjonen som ugyldiggjør brukerens gjeldende tilgangstoken.
	Etikett	(valgfritt) En tekstverdi som lar deg overstyre standardetiketten for denne AuthenticationKind.
Aad	AuthorizationUri	`text` verdi eller unary-funksjon som returnerer endepunktet for Microsoft Entra ID-autorisasjon (eksempel: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Gå til delen Microsoft Entra ID-godkjenning .
	Ressurs	`text` verdi eller uærmhørlig funksjon som returnerer Ressursverdien for Microsoft Entra ID for tjenesten.
	Omfang	(valgfritt) `text` verdi eller unary-funksjon som returnerer listen over omfang som skal bes om som en del av godkjenningsflyten. Flere omfangsverdier bør skilles med et mellomrom. Omfangsverdien må være omfangsnavnet, uten program-ID-URI (eksempel: `Data.Read`). Når det ikke er angitt, `user_impersonation` blir omfanget forespurt.
BrukernavnPassord	UsernameLabel	(valgfritt) En tekstverdi som erstatter standardetiketten for tekstboksen Brukernavn på legitimasjonsgrensesnittet.
	PasswordLabel	(valgfritt) En tekstverdi for å erstatte standardetiketten for tekstboksen Passord på legitimasjonsgrensesnittet.
	Etikett	(valgfritt) En tekstverdi som lar deg overstyre standardetiketten for denne AuthenticationKind.
Windows	UsernameLabel	(valgfritt) En tekstverdi som erstatter standardetiketten for tekstboksen Brukernavn på legitimasjonsgrensesnittet.
	PasswordLabel	(valgfritt) En tekstverdi for å erstatte standardetiketten for tekstboksen Passord på legitimasjonsgrensesnittet.
	Etikett	(valgfritt) En tekstverdi som lar deg overstyre standardetiketten for denne AuthenticationKind.
Nøkkel	KeyLabel	(valgfritt) En tekstverdi som erstatter standardetiketten for tekstboksen API-nøkkel på legitimasjonsgrensesnittet.
	Etikett	(valgfritt) En tekstverdi som lar deg overstyre standardetiketten for denne AuthenticationKind.

Eksemplet nedenfor viser godkjenningsposten for en kobling som støtter OAuth, Key, Windows, Basic (brukernavn og passord) og anonym legitimasjon.

Eksempel:

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

Få tilgang til gjeldende legitimasjon

Gjeldende legitimasjon kan hentes ved hjelp av Extension.CurrentCredential funksjonen.

M-datakildefunksjoner som er aktivert for utvidbarhet, arver automatisk utvidelsens legitimasjonsomfang. I de fleste tilfeller trenger du ikke eksplisitt tilgang til gjeldende legitimasjon, men det finnes unntak, for eksempel:

Sender inn legitimasjonen i en egendefinert overskrift eller spørringsstrengparameter (for eksempel når du bruker godkjenningstypen API-nøkkel).
Angi tilkoblingsstreng egenskaper for ODBC- eller ADO.NET-utvidelser.
Kontrollerer egendefinerte egenskaper på et OAuth-token.
Bruke legitimasjonen som en del av en OAuth v1-flyt.

Funksjonen Extension.CurrentCredential returnerer et postobjekt. Feltene den inneholder, er spesifikke godkjenningstyper. Tabellen nedenfor inneholder detaljer.

Felt	Bekrivelse	Brukt av
AuthenticationKind	Inneholder navnet på godkjenningstype tilordnet denne legitimasjonen (BrukernavnPassord, OAuth og så videre).	Alle
Username	Brukernavnverdi	Brukernavnpassord, Windows
Passord	Passordverdi. Brukes vanligvis med UsernamePassword, men er også angitt for Key.	Key, UsernamePassword, Windows
access_token	Verdi for OAuth-tilgangstoken.	OAuth
Egenskaper	En post som inneholder andre egendefinerte egenskaper for en gitt legitimasjon. Brukes vanligvis med OAuth til å lagre andre egenskaper (for eksempel refresh_token) som returneres med access_token under godkjenningsflyten.	OAuth
Nøkkel	API-nøkkelverdien. Vær oppmerksom på at nøkkelverdien også er tilgjengelig i Passord-feltet. Som standard setter mashup-motoren inn denne nøkkelen i et autorisasjonshode som om denne verdien var et grunnleggende godkjenningspassord (uten brukernavn). Hvis denne virkemåten ikke er den du vil bruke, må du angi alternativet ManualCredentials = true i alternativposten.	Nøkkel
EncryptConnection	En logisk verdi som avgjorde om det skulle kreves en kryptert tilkobling til datakilden. Denne verdien er tilgjengelig for alle godkjenningstyper, men angis bare hvis EncryptConnection er angitt i datakildedefinisjonen.	Alle

Følgende kodeeksempel får tilgang til gjeldende legitimasjon for en API-nøkkel og bruker den til å fylle ut en egendefinert topptekst (x-APIKey).

Eksempel:

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

Implementere en OAuth-flyt

OAuth-godkjenningstypen tillater en utvidelse for å implementere egendefinert logikk for tjenesten. Hvis du vil gjøre dette, gir en utvidelse funksjoner for (returnere autorisasjons-URI-en for StartLogin å starte OAuth-flyten) og FinishLogin (bytte autorisasjonskoden for et tilgangstoken). Utvidelser kan eventuelt implementere Refresh (utveksle et oppdateringstoken for et nytt tilgangstoken) og Logout (utløp av gjeldende oppdaterings- og tilgangstokener) funksjoner også.

Merk

Power Query-utvidelser evalueres i programmer som kjører på klientmaskiner. Datakoblinger bør ikke bruke konfidensielle hemmeligheter i OAuth-flytene sine, da brukere kan undersøke utvidelsen eller nettverkstrafikken for å lære hemmeligheten. Gå til Proof Key for Code Exchange av OAuth Public Clients RFC (også kjent som PKCE) for mer informasjon om hvordan du gir flyter som ikke er avhengige av delte hemmeligheter. Du finner en eksempelimplementering av denne flyten på GitHub-nettstedet vårt.

Det finnes to sett med OAuth-funksjonssignaturer: den opprinnelige signaturen som inneholder et minimalt antall parametere, og en avansert signatur som godtar flere parametere. De fleste OAuth-flyter kan implementeres ved hjelp av de opprinnelige signaturene. Du kan også blande og sammenligne signaturtyper i implementeringen. Funksjonskaller er treff basert på antall parametere (og deres typer). Parameternavnene tas ikke i betraktning.

Gå til GitHub-eksemplet for mer informasjon.

Opprinnelige OAuth-signaturer

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

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

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

Logout = (accessToken) => ...;

Avanserte OAuth-signaturer

Notater om de avanserte signaturene:

Alle signaturer godtar en clientApplication postverdi, som er reservert for fremtidig bruk.
Alle signaturer godtar en dataSourcePath (også referert til som resourceUrl i de fleste eksempler).
Funksjonen Refresh godtar en oldCredential parameter, som er den forrige record som returneres av FinishLogin funksjonen (eller det forrige kallet til Refresh).

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

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

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

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

Microsoft Entra ID-godkjenning

Godkjenningstype Aad er en spesialisert versjon av OAuth for Microsoft Entra ID. Den bruker samme Microsoft Entra ID-klient som de innebygde Power Query-koblingene som støtter godkjenning av organisasjonskonto. Du finner mer informasjon i hurtigstartveiledningen Konfigurer Microsoft Entra for en egendefinert kobling .

Merk

Hvis du implementerer din egen OAuth-flyt for Microsoft Entra ID, kan brukere som har aktivert betinget tilgang for leieren, støte på problemer når de oppdaterer ved hjelp av Power Bi-tjeneste. Dette påvirker ikke gateway-basert oppdatering, men vil påvirke en sertifisert kobling som støtter oppdatering fra Power Bi-tjeneste. Brukere kan støte på et problem som stammer fra koblingen ved hjelp av et offentlig klientprogram når de konfigurerer nettbasert legitimasjon gjennom Power Bi-tjeneste. Tilgangstokenet som genereres av denne flyten, brukes til slutt på en annen datamaskin (det vil eksempelvis Power Bi-tjeneste i et Azure-datasenter, ikke på firmaets nettverk) enn det som ble brukt til å godkjenne (det vil eksempelvis datamaskinen til brukeren som konfigurerer legitimasjonen for datakilden på firmaets nettverk). Den innebygde typen fungerer rundt dette problemet ved hjelp av en annen Microsoft Entra ID-klient Aad når du konfigurerer legitimasjon i Power Bi-tjeneste. Dette alternativet vil ikke være tilgjengelig for koblinger som bruker OAuth godkjenningstype.

De fleste koblinger må angi verdier for AuthorizationUri feltene og Resource . Begge feltene kan være text verdier, eller en enkelt argumentfunksjon som returnerer en text value.

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)

Koblinger som bruker en URI-basert identifikator , trenger ikke å angi en Resource verdi. Som standard er verdien lik rotbanen til koblingens URI-parameter. Hvis datakildens Microsoft Entra ID-ressurs er forskjellig fra domeneverdien (for eksempel den bruker en GUID), må en Resource verdi angis.

Eksempler på AAD-godkjenningstype

I følgende tilfelle støtter datakilden global skybasert Microsoft Entra ID ved hjelp av den vanlige leieren (ingen Azure B2B-støtte). Hvis du ber om standardomfang, returneres et token med alle tidligere autoriserte omfang for program-ID-en for Power Query-klienten.

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

I følgende tilfelle støtter datakilden tenantoppdagelse basert på OpenID Connect (OIDC) eller lignende protokoll. Denne muligheten gjør det mulig for koblingen å bestemme riktig Microsoft Entra ID-endepunkt som skal brukes basert på én eller flere parametere i datakildebanen. Denne dynamiske oppdagelsestilnærmingen gjør det mulig for koblingen å støtte 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"
    ]
]

Andre typer godkjenning

Hvis du vil ha informasjon om andre typer godkjenning som ikke dekkes i denne artikkelen, for eksempel Kerberos-basert enkel pålogging, kan du gå til den ekstra artikkelen om koblingsfunksjonalitet for å finne ut mer.

Del via