Håndtering av godkjenning

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.

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.

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

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 .

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 = "44445555-eeee-6666-ffff-7777aaaa8888"   // 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 = "44445555-eeee-6666-ffff-7777aaaa8888", // 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.