Del via

Håndtering af godkendelse

Godkendelsestyper

En udvidelse kan understøtte en eller flere former for autentificering. Hver autentificeringstype er en forskellig type legitimation. Autentificeringsgrænsefladen, der vises for slutbrugere i Power Query, styres af typen af legitimationsoplysninger, som en udvidelse understøtter.

Listen over understøttede autentificeringstyper defineres som en del af en udvidelses definition af Data Source Kind . Hver autentificeringsværdi er en post med specifikke felter. Følgende tabel viser de forventede felter for hver type. Alle felter er påkrævet, medmindre andet er markeret.

Autentificeringstype Felt Beskrivelse
Anonym Den anonyme (også kaldet Implicit) autentificeringsformular har ingen felter.
OAuth StartLogin Funktion, der leverer URL- og tilstandsinformation til start af et OAuth-flow.

Gå til afsnittet Implementering af en OAuth-flow .
FinishLogin Funktion, der udtrækker access_token og andre egenskaber relateret til OAuth-flowet.
Opdater (valgfrit) Funktion, der henter en ny adgangstoken fra en opdateringstoken.
Logout (valgfrit) Funktion, der ugyldiggør brugerens nuværende adgangstoken.
Navn (valgfrit) En tekstværdi, der tillader dig at tilsidesætte standardetiketten for denne AuthenticationKind.
Aad AuthorizationUri text værdi eller unær funktion, der returnerer Microsoft Entra ID-autorisationsendepunktet (eksempel: "https://login.microsoftonline.com/common/oauth2/authorize").

Gå til afsnittet Microsoft Entra ID-autentificering .
Ressource text værdi eller unær funktion, der returnerer Microsoft Entra ID-ressourceværdien for din tjeneste.
Område (valgfrit)text værdi eller unær funktion, der returnerer listen over scope(r) til anmodning som en del af autentificeringsprocessen. Flere scope-værdier bør adskilles med et mellemrum. Scope-værdien bør være scope-navnet uden en Application ID URI (eksempel: Data.Read). Hvis det ikke er oplyst, anmodes omfanget user_impersonation om.
BrugernavnAdgangskode BrugernavnLabel (valgfrit) En tekstværdi til at erstatte standardetiketten for brugernavn-tekstboksen i legitimationsbrugerfladen.
PasswordLabel (valgfrit) En tekstværdi til at erstatte standardetiketten for adgangskodetekstboksen i legitimationsbrugerfladen.
Navn (valgfrit) En tekstværdi, der tillader dig at tilsidesætte standardetiketten for denne AuthenticationKind.
Windows BrugernavnLabel (valgfrit) En tekstværdi til at erstatte standardetiketten for brugernavn-tekstboksen i legitimationsbrugerfladen.
PasswordLabel (valgfrit) En tekstværdi til at erstatte standardetiketten for adgangskodetekstboksen i legitimationsbrugerfladen.
Navn (valgfrit) En tekstværdi, der tillader dig at tilsidesætte standardetiketten for denne AuthenticationKind.
Nøgle KeyLabel (valgfrit) En tekstværdi til at erstatte standardetiketten for API-nøgletekstboksen på legitimationsbrugerfladen.
Navn (valgfrit) En tekstværdi, der tillader dig at tilsidesætte standardetiketten for denne AuthenticationKind.

Følgende eksempel viser autentificeringsposten for en connector, der understøtter OAuth, Key, Windows, Basic (brugernavn og adgangskode) og anonyme legitimationsoplysninger.

Eksempel:

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

Adgang til de aktuelle legitimationsoplysninger

De aktuelle legitimationsoplysninger kan hentes ved hjælp af Extension.CurrentCredential funktionen.

M datakildefunktioner, der er aktiveret for udvidelsesmuligheder, arver automatisk din udvidelses legitimationsomfang. I de fleste tilfælde behøver du ikke eksplicit at tilgå de aktuelle legitimationsoplysninger, men der er undtagelser, såsom:

  • At sende legitimationsoplysningerne ind i en brugerdefineret header eller en forespørgselsstreng-parameter (for eksempel når du bruger API Key-autentificeringstypen).
  • Indstilling af forbindelsesstrengsegenskaber for ODBC eller ADO.NET udvidelser.
  • Tjekker brugerdefinerede egenskaber på et OAuth-token.
  • At bruge legitimationsoplysningerne som en del af et OAuth v1-flow.

Funktionen Extension.CurrentCredential returnerer et postobjekt. De felter, den indeholder, er specifikke for autentificeringstypen. Følgende tabel indeholder detaljer.

Felt Beskrivelse Brugt af
AuthenticationKind Indeholder navnet på den autentificeringstype, der er tildelt denne legitimation (BrugernavnPassword, OAuth osv.). Alle
Brugernavn Brugernavnsværdi BrugernavnAdgangskode, Windows
Adgangskode Adgangskodeværdi. Bruges typisk med BrugernavnPassword, men det er også sat til Key. Nøgle, brugernavnAdgangskode, Windows
access_token OAuth adgangstoken-værdi. OAuth
Egenskaber En post, der indeholder andre brugerdefinerede egenskaber for en given legitimation. Typisk bruges det med OAuth til at gemme andre egenskaber (såsom de refresh_token), der returneres med access_token under autentificeringsprocessen. OAuth
Nøgle API-nøgleværdien. Bemærk, at nøgleværdien også er tilgængelig i Adgangskodefeltet. Som standard indsætter mashup-motoren denne nøgle i en autorisationsheader, som om denne værdi var en grundlæggende autentificeringsadgangskode (uden brugernavn). Hvis denne type adfærd ikke er det, du ønsker, skal du angive optionen ManualCredentials = true i optionsposten. Nøgle
EncryptConnection En logisk værdi, der afgjorde, om der skulle kræves en krypteret forbindelse til datakilden. Denne værdi er tilgængelig for alle autentificeringstyper, men er kun sat, hvis EncryptConnection er specificeret i Data Source-definitionen . Alle

Følgende kodeeksempel tilgår den aktuelle legitimation for en API-nøgle og bruger den til at udfylde en brugerdefineret header (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

Implementering af et OAuth-flow

OAuth-autentificeringstypen gør det muligt for en udvidelse at implementere brugerdefineret logik til deres tjeneste. For at gøre dette tilbyder en udvidelse funktioner for StartLogin (at returnere autorisations-URI'en for at starte OAuth-flowet) og FinishLogin (at udveksle autorisationskoden med en adgangstok). Udvidelser kan valgfrit implementere Refresh (at bytte en opdateringstoken ud med en ny adgangstoken) og Logout (udløber de nuværende opdaterings- og adgangstoks) funktioner.

Notat

Power Query-udvidelser evalueres i applikationer, der kører på klientmaskiner. Data Connectors bør ikke bruge fortrolige hemmeligheder i deres OAuth-flows, da brugere kan inspicere udvidelsen eller netværkstrafikken for at lære hemmeligheden. Gå til Proof Key for Code Exchange fra OAuth Public Clients RFC (også kendt som PKCE) for yderligere detaljer om at levere flows, der ikke er afhængige af delte hemmeligheder. Et eksempel på implementering af dette flow kan findes på vores GitHub-side.

Der findes to sæt OAuth-funktionssignaturer: den oprindelige signatur, der indeholder et minimalt antal parametre, og en avanceret signatur, der accepterer flere parametre. De fleste OAuth-flows kan implementeres ved hjælp af de oprindelige signaturer. Du kan også mixe og matche signaturtyper i din implementering. Funktionskaldene er matches baseret på antallet af parametre (og deres typer). Parameternavnene tages ikke i betragtning.

Gå til GitHub-eksemplet for flere detaljer.

Originale OAuth-signaturer

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

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

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

Logout = (accessToken) => ...;

Avancerede OAuth-signaturer

Noter om de avancerede signaturer:

  • Alle signaturer accepterer en clientApplication postværdi, som er reserveret til fremtidig brug.
  • Alle signaturer accepterer en (også kaldet som dataSourcePathresourceUrl i de fleste samples).
  • Funktionen Refresh accepterer en oldCredential parameter, som er den foregående record , der returneres af din FinishLogin funktion (eller det forrige kald til Refresh).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

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

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

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

Microsoft Entra ID-godkendelse

Autentificeringstypen Aad er en specialiseret version af OAuth til Microsoft Entra ID. Den bruger den samme Microsoft Entra ID-klient som de indbyggede Power Query-connectorer, der understøtter autentificering af organisatoriske kontoer. Mere information kan findes i guiden Konfigurere Microsoft Entra for en hurtigstart med brugerdefineret connector .

Notat

Hvis du implementerer dit eget OAuth-flow for Microsoft Entra ID, kan brugere, der har aktiveret betinget adgang for deres lejer, opleve problemer ved opdatering med Power BI-tjenesten. Dette vil ikke påvirke gateway-baseret opdatering, men vil påvirke en certificeret connector, der understøtter opdatering fra Power BI-tjenesten. Brugere kan støde på et problem, der stammer fra, at connectoren bruger en offentlig klientapplikation , når webbaserede legitimationsoplysninger konfigureres via Power BI-tjenesten. Den adgangstoken, der genereres af dette flow, vil i sidste ende blive brugt på en anden computer (det vil sige Power BI-tjenesten i et Azure-datacenter, ikke på virksomhedens netværk) end den, der oprindeligt blev brugt til autentificering (dvs. den computer, der tilhører den bruger, der konfigurerer datakildens legitimationsoplysninger på virksomhedens netværk). Den indbyggede Aad type omgår dette problem ved at bruge en anden Microsoft Entra ID-klient, når man konfigurerer legitimationsoplysninger i Power BI-tjenesten. Denne mulighed vil ikke være tilgængelig for connectorer, der bruger OAuth autentificeringstypen.

De fleste stik skal angive værdier for og-felterne AuthorizationUriResource . Begge felter kan være text værdier eller en enkelt argumentfunktion, der 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)

Connectors, der bruger en URI-baseret identifikator , behøver ikke at angive en Resource værdi. Som standard er værdien lig rodstien for connectorens URI-parameter. Hvis datakildens Microsoft Entra ID-ressource er forskellig fra domæneværdien (for eksempel bruger den en GUID), skal der gives en Resource værdi.

Aad-autentificeringseksempler

I det følgende tilfælde understøtter datakilden global cloud Microsoft Entra ID ved brug af den fælles lejer (ingen Azure B2B-understøttelse). Anmodning om .default-scope returnerer et token med alle tidligere autoriserede scopes for Power Query-klientapplikations-ID'et.

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 det følgende tilfælde understøtter datakilden lejeropdagelse baseret på OpenID Connect (OIDC) eller lignende protokol. Denne evne gør det muligt for connectoren at bestemme det korrekte Microsoft Entra ID-endpoint, der skal bruges, baseret på en eller flere parametre i datakildestien. Denne dynamiske discovery-tilgang gør det muligt for connectoren at understø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 autentificering

For information om andre typer autentificering, der ikke dækkes i denne artikel, såsom Kerberos-baseret single sign-on, besøg artiklen om yderligere connector-funktionalitet for at lære mere.

  • Last updated on