Verificatie afhandelen

Artikel
12/04/2024

Verificatietypen

Een extensie kan een of meer soorten verificatie ondersteunen. Elk verificatietype is een ander type referentie. De gebruikersinterface voor verificatie die wordt weergegeven aan eindgebruikers in Power Query, wordt aangestuurd door het type referenties dat door een extensie wordt ondersteund.

De lijst met ondersteunde verificatietypen wordt gedefinieerd als onderdeel van de definitie gegevensbrontype van een extensie. Elke verificatiewaarde is een record met specifieke velden. De volgende tabel bevat de verwachte velden voor elk type. Alle velden zijn vereist, tenzij anders gemarkeerd.

Verificatietype	Veld	Beschrijving
Anoniem		Het verificatietype Anoniem (ook wel `Implicit`genoemd) heeft geen velden.
OAuth	StartLogin	Functie die de URL en statusinformatie biedt voor het starten van een OAuth-stroom. Ga naar de sectie Een OAuth-stroom implementeren.
	FinishLogin	Functie waarmee de access_token en andere eigenschappen worden geëxtraheerd die betrekking hebben op de OAuth-stroom.
	Vernieuwen	(optioneel) Functie waarmee een nieuw toegangstoken wordt opgehaald uit een vernieuwingstoken.
	Afmelden	(optioneel) Functie die het huidige toegangstoken van de gebruiker ongeldig maakt.
	Label	(optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Aad	AuthorizationUri	`text` waarde of unaire functie die het Microsoft Entra ID-autorisatie-eindpunt retourneert (bijvoorbeeld: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Ga naar de sectie Microsoft Entra ID-verificatie .
	Bron	`text` waarde of unaire functie die de Microsoft Entra ID-resourcewaarde voor uw service retourneert.
	Bereik	(optioneel) `text` waarde of unaire functie die de lijst met bereiken retourneert die moeten worden aangevraagd als onderdeel van de verificatiestroom. Meerdere bereikwaarden moeten worden gescheiden door een spatie. De bereikwaarde moet de naam van het bereik zijn, zonder een URI voor de toepassings-id (bijvoorbeeld: `Data.Read`). Wanneer dit niet is opgegeven, wordt het `user_impersonation` bereik aangevraagd.
UsernamePassword	UsernameLabel	(optioneel) Een tekstwaarde voor het vervangen van het standaardlabel voor het tekstvak Gebruikersnaam in de gebruikersinterface voor referenties.
	PasswordLabel	(optioneel) Een tekstwaarde die het standaardlabel voor het tekstvak Wachtwoord in de gebruikersinterface voor referenties vervangt.
	Label	(optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Windows	UsernameLabel	(optioneel) Een tekstwaarde voor het vervangen van het standaardlabel voor het tekstvak Gebruikersnaam in de gebruikersinterface voor referenties.
	PasswordLabel	(optioneel) Een tekstwaarde die het standaardlabel voor het tekstvak Wachtwoord in de gebruikersinterface voor referenties vervangt.
	Label	(optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Sleutel	KeyLabel	(optioneel) Een tekstwaarde die het standaardlabel voor het tekstvak API-sleutel in de gebruikersinterface van referenties vervangt.
	Label	(optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.

In het volgende voorbeeld ziet u de verificatierecord voor een connector die ondersteuning biedt voor OAuth-, Sleutel-, Windows-, Basic-, (gebruikersnaam en wachtwoord) en anonieme referenties.

Voorbeeld:

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

Toegang tot de huidige referenties

De huidige referenties kunnen worden opgehaald met behulp van de Extension.CurrentCredential functie.

M-gegevensbronfuncties die zijn ingeschakeld voor uitbreidbaarheid nemen automatisch het referentiebereik van uw extensie over. In de meeste gevallen hoeft u niet expliciet toegang te krijgen tot de huidige referenties, maar er zijn uitzonderingen, zoals:

Geef de referentie door in een aangepaste header- of querytekenreeksparameter (bijvoorbeeld wanneer u het verificatietype API-sleutel gebruikt).
Het instellen van verbindingsreeks eigenschappen voor ODBC- of ADO.NET-extensies.
Aangepaste eigenschappen controleren op een OAuth-token.
Gebruik de referenties als onderdeel van een OAuth v1-stroom.

De Extension.CurrentCredential functie retourneert een recordobject. De velden die het bevat, zijn verificatietypespecifiek. De volgende tabel bevat details.

Veld	Beschrijving	Gebruikt door
AuthenticationKind	Bevat de naam van het verificatietype dat is toegewezen aan deze referentie (UsernamePassword, OAuth, enzovoort).	Alle
Username	Gebruikersnaamwaarde	UsernamePassword, Windows
Wachtwoord	Wachtwoordwaarde. Wordt meestal gebruikt met UsernamePassword, maar deze is ook ingesteld voor Sleutel.	Sleutel, UsernamePassword, Windows
access_token	OAuth-toegangstokenwaarde.	OAuth
Eigenschappen	Een record met andere aangepaste eigenschappen voor een bepaalde referentie. Meestal gebruikt met OAuth om andere eigenschappen (zoals de refresh_token) op te slaan die tijdens de verificatiestroom worden geretourneerd met de access_token.	OAuth
Sleutel	De API-sleutelwaarde. De sleutelwaarde is ook beschikbaar in het veld Wachtwoord. De mashup-engine voegt deze sleutel standaard in een autorisatieheader in alsof deze waarde een basisverificatiewachtwoord is (zonder gebruikersnaam). Als dit type gedrag niet is wat u wilt, moet u de optie ManualCredentials = true opgeven in de optiesrecord.	Sleutel
EncryptConnection	Een logische waarde die bepaalt of er een versleutelde verbinding met de gegevensbron moet worden vereist. Deze waarde is beschikbaar voor alle verificatietypen, maar wordt alleen ingesteld als EncryptConnection is opgegeven in de definitie van de gegevensbron .	Alle

Het volgende codevoorbeeld krijgt toegang tot de huidige referentie voor een API-sleutel en gebruikt deze om een aangepaste header (x-APIKey) in te vullen.

Voorbeeld:

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

Een OAuth-stroom implementeren

Met het verificatietype OAuth kan een extensie aangepaste logica voor hun service implementeren. Hiervoor biedt een extensie functies voor StartLogin (retourneert de autorisatie-URI om de OAuth-stroom te initiëren) en FinishLogin (de autorisatiecode voor een toegangstoken uitwisselen). Extensies kunnen eventueel ook (het uitwisselen van een vernieuwingstoken voor een nieuw toegangstoken) en Logout (het verlopen van de huidige vernieuwings- en toegangstokens) ook implementeren Refresh .

Notitie

Power Query-extensies worden geëvalueerd in toepassingen die worden uitgevoerd op clientcomputers. Gegevensconnectors mogen geen vertrouwelijke geheimen in hun OAuth-stromen gebruiken, omdat gebruikers de extensie of het netwerkverkeer kunnen inspecteren om het geheim te leren kennen. Ga naar Proof Key for Code Exchange by OAuth Public Clients RFC (ook wel PKCE genoemd) voor meer informatie over het verstrekken van stromen die niet afhankelijk zijn van gedeelde geheimen. Een voorbeeld van deze stroom is te vinden op onze GitHub-site.

Er zijn twee sets OAuth-functiehandtekeningen: de oorspronkelijke handtekening met een minimaal aantal parameters en een geavanceerde handtekening die meer parameters accepteert. De meeste OAuth-stromen kunnen worden geïmplementeerd met behulp van de oorspronkelijke handtekeningen. U kunt ook handtekeningtypen combineren en vergelijken in uw implementatie. De functie-aanroepen zijn overeenkomsten op basis van het aantal parameters (en de bijbehorende typen). Er wordt geen rekening gehouden met de parameternamen.

Ga naar het GitHub-voorbeeld voor meer informatie.

Oorspronkelijke OAuth-handtekeningen

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

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

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

Logout = (accessToken) => ...;

Geavanceerde OAuth-handtekeningen

Opmerkingen over de geavanceerde handtekeningen:

Alle handtekeningen accepteren een clientApplication recordwaarde, die is gereserveerd voor toekomstig gebruik.
Alle handtekeningen accepteren een dataSourcePath (ook wel in resourceUrl de meeste voorbeelden genoemd).
De Refresh functie accepteert een oldCredential parameter, de vorige record geretourneerd door uw FinishLogin functie (of de vorige aanroep naar Refresh).

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

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

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

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

Microsoft Entra ID-verificatie

Het Aad verificatietype is een gespecialiseerde versie van OAuth voor Microsoft Entra-id. Deze maakt gebruik van dezelfde Microsoft Entra ID-client als de ingebouwde Power Query-connectors die ondersteuning bieden voor verificatie van organisatieaccounts. Meer informatie vindt u in de quickstartgids Microsoft Entra configureren voor een aangepaste connector .

Notitie

Als u uw eigen OAuth-stroom implementeert voor Microsoft Entra ID, kunnen gebruikers die voorwaardelijke toegang voor hun tenant hebben ingeschakeld, problemen ondervinden bij het vernieuwen met behulp van de Power BI-service. Dit heeft geen invloed op het vernieuwen op basis van een gateway, maar heeft wel invloed op een gecertificeerde connector die ondersteuning biedt voor vernieuwen vanuit de Power BI-service. Gebruikers kunnen een probleem ondervinden als gevolg van de connector met behulp van een openbare clienttoepassing bij het configureren van webreferenties via de Power BI-service. Het toegangstoken dat door deze stroom wordt gegenereerd, wordt uiteindelijk gebruikt op een andere computer (de Power BI-service in een Azure-datacenter, niet in het netwerk van het bedrijf) dan het token dat is gebruikt voor de oorspronkelijke verificatie (dat wil gezegd de computer van de gebruiker die de referenties voor de gegevensbron configureert in het bedrijfsnetwerk). Het ingebouwde type werkt rond dit probleem door een andere Microsoft Entra ID-client Aad te gebruiken bij het configureren van referenties in de Power BI-service. Deze optie is niet beschikbaar voor connectors die gebruikmaken van het OAuth verificatietype.

De meeste connectors moeten waarden voor de AuthorizationUri en Resource velden opgeven. Beide velden kunnen waarden zijn text of één argumentfunctie die een 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 die gebruikmaken van een URI-id hoeven geen waarde op te geven Resource . Standaard is de waarde gelijk aan het hoofdpad van de URI-parameter van de connector. Als de Microsoft Entra ID-resource van de gegevensbron verschilt van de domeinwaarde (bijvoorbeeld een GUID), moet er een Resource waarde worden opgegeven.

Voorbeelden van Aad-verificatietype

In het volgende geval ondersteunt de gegevensbron globale Microsoft Entra-id in de cloud met behulp van de gemeenschappelijke tenant (geen Ondersteuning voor Azure B2B). Als u het standaardbereik aanvraagt, wordt een token geretourneerd met alle eerder geautoriseerde bereiken voor de toepassings-id van de Power Query-client.

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

In het volgende geval ondersteunt de gegevensbron tenantdetectie op basis van OpenID Connect (OIDC) of een vergelijkbaar protocol. Met deze mogelijkheid kan de connector het juiste Microsoft Entra ID-eindpunt bepalen dat moet worden gebruikt op basis van een of meer parameters in het pad naar de gegevensbron. Met deze dynamische detectiebenadering kan de connector Ondersteuning bieden voor 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"
    ]
]

Andere typen verificatie

Voor informatie over andere typen verificatie die niet in dit artikel worden behandeld, zoals eenmalige aanmelding op basis van Kerberos, gaat u naar het artikel aanvullende connectorfunctionaliteit voor meer informatie.

Delen via