Håndtering af godkendelse

Artikel
03/19/2024

Godkendelsestyper

En udvidelse kan understøtte en eller flere typer godkendelse. Hver godkendelsestype er en anden type legitimationsoplysninger. Den godkendelsesbrugergrænseflade, der vises for slutbrugere i Power Query, er baseret på den eller de legitimationsoplysninger, som en udvidelse understøtter.

Listen over understøttede godkendelsestyper er defineret som en del af definitionen af datakildetypen for en udvidelse. Hver godkendelsesværdi er en post med bestemte felter. I følgende tabel vises de forventede felter for hver type. Alle felter er obligatoriske, medmindre andet er markeret.

Godkendelsestype	Felt	Beskrivelse
Anonym		Godkendelsestypen Anonym (også kaldet `Implicit`) har ingen felter.
OAuth	StartLogin	Funktion, der leverer URL-adressen og tilstandsoplysningerne til start af et OAuth-flow. Gå til afsnittet Implementering af et OAuth Flow .
	FinishLogin	Funktion, der udtrækker access_token og andre egenskaber, der er relateret til OAuth-flowet.
	Opdater	(valgfrit) Funktion, der henter et nyt adgangstoken fra et opdateringstoken.
	Logout	(valgfrit) Funktion, der ugyldiggør brugerens aktuelle adgangstoken.
	Mærkat	(valgfrit) En tekstværdi, der giver dig mulighed for at tilsidesætte standardnavnet for denne AuthenticationKind.
Aad	AuthorizationUri	`text` værdi eller monadisk funktion, der returnerer Microsoft Entra ID-godkendelsesslutpunktet (f.eks.: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Gå til godkendelsesafsnittet Microsoft Entra ID .
	Ressource	`text` værdi eller monadisk funktion, der returnerer microsoft Entra ID-ressourceværdien for din tjeneste.
	Omfang	(valgfrit) `text` værdi eller monadisk funktion, der returnerer listen over områder, der skal anmodes om som en del af godkendelsesflowet. Flere områdeværdier skal adskilles af et mellemrum. Områdeværdien skal være områdenavnet uden en URI for program-id'en (f.eks.: `Data.Read`). Når det ikke er angivet, anmodes `user_impersonation` der om området.
BrugernavnAdgangskode	UsernameLabel	(valgfrit) En tekstværdi, der erstatter standardnavnet for tekstfeltet Brugernavn på brugergrænsefladen for legitimationsoplysninger.
	PasswordLabel	(valgfrit) En tekstværdi, der erstatter standardnavnet for tekstfeltet Adgangskode i brugergrænsefladen for legitimationsoplysninger.
	Mærkat	(valgfrit) En tekstværdi, der giver dig mulighed for at tilsidesætte standardnavnet for denne AuthenticationKind.
Windows	UsernameLabel	(valgfrit) En tekstværdi, der erstatter standardnavnet for tekstfeltet Brugernavn på brugergrænsefladen for legitimationsoplysninger.
	PasswordLabel	(valgfrit) En tekstværdi, der erstatter standardnavnet for tekstfeltet Adgangskode i brugergrænsefladen for legitimationsoplysninger.
	Mærkat	(valgfrit) En tekstværdi, der giver dig mulighed for at tilsidesætte standardnavnet for denne AuthenticationKind.
Nøgle	KeyLabel	(valgfrit) En tekstværdi, der erstatter standardnavnet for tekstfeltet API-nøgle på brugergrænsefladen for legitimationsoplysninger.
	Mærkat	(valgfrit) En tekstværdi, der giver dig mulighed for at tilsidesætte standardnavnet for denne AuthenticationKind.

I følgende eksempel vises godkendelsesposten 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 til udvidelse, arver automatisk omfanget af legitimationsoplysningerne for din udvidelse. I de fleste tilfælde behøver du ikke eksplicit at få adgang til de aktuelle legitimationsoplysninger, men der er dog undtagelser, f.eks.:

Overførsel af legitimationsoplysningerne i en brugerdefineret header- eller forespørgselsstrengparameter (f.eks. når du bruger godkendelsestypen FOR API-nøgle).
Angivelse forbindelsesstreng egenskaber for ODBC- eller ADO.NET-udvidelser.
Kontrollerer brugerdefinerede egenskaber på et OAuth-token.
Brug af legitimationsoplysningerne som en del af et OAuth v1-flow.

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

Felt	Beskrivelse	Bruges af
AuthenticationKind	Indeholder navnet på den godkendelsestype, der er tildelt disse legitimationsoplysninger (UsernamePassword, OAuth osv.).	All
Username	Værdi for brugernavn	UsernamePassword, Windows
Adgangskode	Adgangskodeværdi. Bruges typisk sammen med UsernamePassword, men den er også angivet for Key.	Nøgle, BrugernavnAdgangskode, Windows
access_token	OAuth-adgangstokenværdi.	OAuth
Egenskaber	En post, der indeholder andre brugerdefinerede egenskaber for en given legitimationsoplysninger. Bruges typisk sammen med OAuth til at gemme andre egenskaber (f.eks. refresh_token), der returneres sammen med access_token under godkendelsesflowet.	OAuth
Nøgle	API-nøgleværdien. Bemærk, at nøgleværdien også er tilgængelig i feltet Adgangskode. Miksprogrammet indsætter som standard denne nøgle i en autorisationsheader, som om denne værdi var en grundlæggende godkendelsesadgangskode (uden brugernavn). Hvis denne type funktionsmåde ikke er, som du ønsker det, skal du angive indstillingen ManualCredentials = true i indstillingsposten.	Nøgle
EncryptConnection	En logisk værdi, der bestemmer, om der skal kræves en krypteret forbindelse til datakilden. Denne værdi er tilgængelig for alle godkendelsestyper, men angives kun, hvis EncryptConnection er angivet i datakildedefinitionen.	All

Følgende kodeeksempel får adgang til de aktuelle legitimationsoplysninger 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-godkendelsestypen tillader en udvidelse til at implementere brugerdefineret logik for deres tjeneste. For at gøre dette indeholder en udvidelse funktioner til (returnering af autorisations-URI'en for StartLogin at starte OAuth-flowet) og FinishLogin (udveksling af godkendelseskoden for et adgangstoken). Udvidelser kan eventuelt implementere Refresh (udveksle et opdateringstoken for et nyt adgangstoken) og Logout (der udløber de aktuelle opdaterings- og adgangstokens) funktioner.

Bemærk

Power Query-udvidelser evalueres i programmer, der kører på klientcomputere. Dataconnectors bør ikke bruge fortrolige hemmeligheder i deres OAuth-flow, da brugerne kan undersøge udvidelsen eller netværkstrafikken for at lære hemmeligheden at kende. Gå til Proof Key for Code Exchange by OAuth Public Clients RFC (også kendt som PKCE) for at få flere oplysninger om at angive flow, der ikke er afhængige af delte hemmeligheder. Du kan finde et eksempel på implementering af dette flow på vores GitHub-websted.

Der er 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-flow kan implementeres ved hjælp af de oprindelige signaturer. Du kan også blande og matche signaturtyper i din implementering. Funktionskaldene er match baseret på antallet af parametre (og deres typer). Parameternavnene tages ikke i betragtning.

Gå til GitHub-eksemplet for at få flere oplysninger.

Oprindelige 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 dataSourcePath (også kaldet resourceUrl i de fleste eksempler).
Funktionen Refresh accepterer en oldCredential parameter, som er den forrige record , der blev returneret af funktionen FinishLogin (eller 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

Godkendelses Aad kinden er en specialiseret version af OAuth til Microsoft Entra ID. Den bruger den samme Microsoft Entra ID-klient som de indbyggede Power Query-connectors, der understøtter godkendelse af organisationskonto. Du kan finde flere oplysninger i vejledning til konfiguration af Microsoft Entra til en brugerdefineret connector .

Bemærk

Hvis du implementerer dit eget OAuth-flow til Microsoft Entra-id, kan brugere, der har aktiveret Betinget adgang for deres lejer, støde på problemer, når de opdaterer ved hjælp af Power BI-tjeneste. Dette påvirker ikke gatewaybaseret opdatering, men påvirker en certificeret connector, der understøtter opdatering fra Power BI-tjeneste. Brugerne kan støde på et problem, der stammer fra connectoren, ved hjælp af et offentligt klientprogram, når de konfigurerer webbaserede legitimationsoplysninger via Power BI-tjeneste. Det adgangstoken, der genereres af dette flow, bruges i sidste ende på en anden computer (dvs. Power BI-tjeneste i et Azure-datacenter, ikke på virksomhedens netværk) end det, der oprindeligt blev brugt til godkendelse (dvs. computeren for den bruger, der konfigurerer legitimationsoplysningerne for datakilden på virksomhedens netværk). Den indbyggede Aad type kan løse problemet ved hjælp af en anden Microsoft Entra ID-klient, når du konfigurerer legitimationsoplysninger i Power BI-tjeneste. Denne indstilling er ikke tilgængelig for connectorer, der bruger godkendelses OAuth kind.

De fleste connectors skal angive værdier for AuthorizationUri felterne og Resource . 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 = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Microsoft Entra ID resource value for your service - Guid or URL

Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Forbindelser, der bruger et URI-baseret id , behøver ikke at angive en Resource værdi. Værdien er som standard lig med rodstien for connectorens URI-parameter. Hvis datakildens Microsoft Entra ID-ressource er forskellig fra domæneværdien (den bruger f.eks. et GUID), skal der angives en Resource værdi.

Eksempler på aad-godkendelses kind

I følgende tilfælde understøtter datakilden microsoft entra-id'et i den globale cloud ved hjælp af den fælles lejer (ingen Azure B2B-understøttelse). Anmodning om .default-området returnerer et token med alle tidligere godkendte områder for program-id'et 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 tilfælde understøtter datakilden lejerregistrering baseret på OpenID Connect (OIDC) eller lignende protokol. Denne mulighed gør det muligt for connectoren at bestemme det korrekte Microsoft Entra ID-slutpunkt, der skal bruges baseret på en eller flere parametre i datakildestien. Denne dynamiske registreringstilgang 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 godkendelsestyper

Du kan finde oplysninger om andre godkendelsestyper, der ikke er omfattet af denne artikel, f.eks. Kerberos-baseret enkeltlogon, i artiklen yderligere connectorfunktionalitet for at få mere at vide.

Del via