Verificatie verwerken

Verificatiemethoden

Een extensie kan een of meer soorten verificatie ondersteunen. Elk verificatietype is een ander type referentie. De verificatie-UI die wordt weergegeven voor eindgebruikers in Power Query, wordt aangestuurd door het type referentie(en) 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.

Soort verificatie Veld Description
Impliciet Het type Impliciete (anonieme) verificatie heeft geen velden.
Oauth StartLogin Functie die de URL en statusinformatie levert voor het starten van een OAuth-stroom.

Zie de sectie Een OAuth-Flow implementeren hieronder.
FinishLogin Functie die de access_token en andere eigenschappen met betrekking tot de OAuth-stroom extraheert.
Vernieuwen (optioneel) Functie die een nieuw toegang token op haalt uit een vernieuwings-token.
Afmelden (optioneel) Functie die het huidige toegang token van de gebruiker ongeldig maakt.
Label (optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Aad AuthorizationUri text waarde of functie die het Azure AD-autorisatie-eindpunt retourneert (bijvoorbeeld: "https://login.microsoftonline.com/common/oauth2/authorize" ).

Zie de Azure Active Directory verificatie hieronder.
Resource text waarde of functie die de Azure AD-resourcewaarde voor uw service retourneert.
UsernamePassword UsernameLabel (optioneel) Een tekstwaarde ter vervanging van het standaardlabel voor het tekstvak Gebruikersnaam in de gebruikersinterface voor referenties.
PasswordLabel (optioneel) Een tekstwaarde ter vervanging van het standaardlabel voor het tekstvak Wachtwoord in de gebruikersinterface voor referenties.
Label (optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Windows UsernameLabel (optioneel) Een tekstwaarde ter vervanging van het standaardlabel voor het tekstvak Gebruikersnaam in de gebruikersinterface voor referenties.
PasswordLabel (optioneel) Een tekstwaarde ter vervanging van het standaardlabel voor het tekstvak Wachtwoord in de gebruikersinterface voor referenties.
Label (optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.
Sleutel KeyLabel (optioneel) Een tekstwaarde ter vervanging van het standaardlabel voor het tekstvak API-sleutel in de gebruikersinterface voor referenties.
Label (optioneel) Een tekstwaarde waarmee u het standaardlabel voor dit AuthenticationKind kunt overschrijven.

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

Voorbeeld:

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

Toegang tot de huidige referenties

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

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

  • De referentie doorgeven in een aangepaste header of queryreeksparameter (bijvoorbeeld wanneer u het auth-type API-sleutel gebruikt)
  • Eigenschappen connection string ODBC- of ADO.NET instellen
  • Aangepaste eigenschappen van een OAuth-token controleren
  • De referenties gebruiken als onderdeel van een OAuth v1-stroom

De Extension.CurrentCredential() functie retourneert een recordobject. De velden die het bevat, zijn specifiek voor verificatietype. Zie de volgende tabel voor meer informatie.

Veld Description Gebruikt door
AuthenticationKind Bevat de naam van het type verificatie dat is toegewezen aan deze referentie (UsernamePassword, OAuth, etc.). Alles
Gebruikersnaam Gebruikersnaamwaarde UsernamePassword, Windows
Wachtwoord Wachtwoordwaarde. Wordt doorgaans gebruikt met UsernamePassword, maar deze wordt ook ingesteld voor Sleutel. Sleutel, UsernamePassword, Windows
access_token OAuth-toegangstekenwaarde. Oauth
Eigenschappen Een record met andere aangepaste eigenschappen voor een bepaalde referentie. Wordt doorgaans gebruikt met OAuth voor het opslaan van aanvullende eigenschappen (zoals de refresh_token) die tijdens de verificatiestroom access_token geretourneerd met de access_token. Oauth
Sleutel De waarde van de API-sleutel. Opmerking: de sleutelwaarde is ook beschikbaar in het veld Wachtwoord. Standaard voegt de mashup-engine deze in een Autorisatie-header in alsof deze waarde een eenvoudig verificatiewachtwoord (zonder gebruikersnaam) is. Als dit niet het wante gedrag is, moet u de optie ManualCredentials = true opgeven in de optiesrecord. Sleutel
EncryptConnection Een logische waarde die bepaalt of een versleutelde verbinding met de gegevensbron vereist is. Deze waarde is beschikbaar voor alle verificatiemethoden, maar wordt alleen ingesteld als EncryptConnection is opgegeven in de gegevensbrondefinitie. Alles

Het volgende codevoorbeeld heeft toegang tot de huidige referentie voor een API-sleutel en gebruikt deze om een aangepaste header () in te x-APIKey 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-Flow

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

Notitie

Power Query-extensies worden geëvalueerd in toepassingen die worden uitgevoerd op clientmachines. Gegevensconnectoren mogen geen vertrouwelijke geheimen gebruiken in hun OAuth-stromen, omdat gebruikers de extensie of het netwerkverkeer kunnen inspecteren om het geheim te leren kennen. Zie proof key for Code Exchange by OAuth Public Clients RFC (ook wel bekend als PKCE) voor meer informatie over het leveren van stromen die niet afhankelijk zijn van gedeelde geheimen. Een voorbeeld van een implementatie van deze stroom vindt u op onze GitHub site.

Er zijn twee sets OAuth-functiehandtekeningen; de oorspronkelijke handtekening die een minimaal aantal parameters bevat en een geavanceerde handtekening die aanvullende parameters accepteert. De meeste OAuth-stromen kunnen worden geïmplementeerd met behulp van de oorspronkelijke handtekeningen. U kunt ook handtekeningtypen combineren en matchen in uw implementatie. De functie-aanroepen zijn overeenkomsten op basis van het aantal parameters (en hun typen). De parameternamen worden niet in overweging genomen.

Zie 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 de resourceUrl meeste voorbeelden genoemd).
  • De Refresh functie accepteert een oldCredential parameter, die de vorige is die is record geretourneerd door uw functie FinishLogin (of de vorige aanroep van Refresh ).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

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

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

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

Verificatie via Azure Active Directory

Het Aad verificatiemiddel is een gespecialiseerde versie van OAuth voor Azure Active Directory. Deze maakt gebruik van dezelfde Azure AD-client als de ingebouwde Power Query connectors die ondersteuning bieden voor verificatie van organisatieaccounts.

Notitie

Als uw gegevensbron andere scopes vereist dan , of niet compatibel is met het gebruik van , moet u user_impersonation user_impersonation het OAuth verificatiemiddel gebruiken.

Notitie

Als u uw eigen OAuth-stroom voor Azure AD implementeert, 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 vernieuwing op basis van de gateway, maar is van invloed op een gecertificeerde connector die vernieuwing vanuit de Power BI ondersteunt. Gebruikers kunnen een probleem krijgen als gevolg van de connector met behulp van een openbare clienttoepassing bij het configureren van webreferenties via de Power BI service. Het toegangs token dat door deze stroom wordt gegenereerd, wordt uiteindelijk gebruikt op een andere computer (dat wil zeggen, de Power BI-service in een Azure-datacenter, niet in het netwerk van het bedrijf) dan het token dat is gebruikt voor de verificatie (dat wil zeggen, de computer van de gebruiker die de referenties voor de gegevensbron in het netwerk van het bedrijf configureert). Het ingebouwde type rondt dit probleem af door een andere Azure AD-client te gebruiken bij het configureren van referenties Aad in de Power BI service. Deze optie is niet beschikbaar voor connectors die gebruikmaken van het OAuth verificatie-type.

De meeste connectors moeten waarden voor de velden AuthorizationUri en Resource geven. Beide velden kunnen waarden text zijn of één argumentfunctie die een retourneert. text value

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"
AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)
Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Azure AD resource value for your service - Guid or URL
Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Connectors die gebruikmaken van een id op basis van URI hoeven geen waarde op te Resource geven. Standaard is de waarde gelijk aan het hoofdpad van de URI-parameter van de connector. Als de Azure AD-resource van de gegevensbron anders is dan de domeinwaarde (bijvoorbeeld als deze een GUID gebruikt), moet er Resource een waarde worden opgegeven.

Voorbeelden van soorten Aad-verificatie

In dit geval ondersteunt de gegevensbron wereldwijde cloud Azure AD met behulp van de gemeenschappelijke tenant (geen ondersteuning voor Azure B2B).

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002" // Azure AD resource value for your service - Guid or URL
    ]
]

In dit geval ondersteunt de gegevensbron tenantdetectie op basis van OpenID Verbinding maken (OIDC) of een vergelijkbaar protocol. Hierdoor kan de connector bepalen welk Azure AD-eindpunt moet worden gebruikt op basis van een of meer parameters in het gegevensbronpad. Dankzij deze dynamische detectie 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", // Azure AD resource value for your service - Guid or URL
    ]
]

Gegevensbronpaden

De M-engine identificeert een gegevensbron met behulp van een combinatie van type en pad. Wanneer er een gegevensbron wordt aangetroffen tijdens een query-evaluatie, probeert de M-engine overeenkomende referenties te vinden. Als er geen referenties worden gevonden, retourneert de engine een speciale fout die resulteert in een referentieprompt in Power Query.

De waarde Soort is afkomstig uit de definitie Soort gegevensbron.

De waarde Pad is afgeleid van de vereiste parameters van de gegevensbronfunctie. Optionele parameters worden niet meegenomen in de id van het gegevensbronpad. Als gevolg hiervan moeten alle gegevensbronfuncties die zijn gekoppeld aan een gegevensbron, dezelfde parameters hebben. Er is een speciale afhandeling voor functies die één parameter van het type Uri.Type hebben. Zie de sectie hieronder voor meer informatie.

U ziet een voorbeeld van hoe referenties worden opgeslagen in het dialoogvenster Instellingen voor gegevensbron in Power BI Desktop. In dit dialoogvenster wordt kind vertegenwoordigd door een pictogram en wordt de waarde Pad weergegeven als tekst.

DataSourcePaths.

Notitie

Als u de vereiste parameters van uw gegevensbronfunctie wijzigt tijdens de ontwikkeling, werken eerder opgeslagen referenties niet meer (omdat de padwaarden niet meer overeenkomen). U moet alle opgeslagen referenties verwijderen wanneer u de functieparameters van uw gegevensbron wijzigt. Als er incompatibele referenties worden gevonden, wordt er tijdens runtime mogelijk een foutbericht weergegeven.

Indeling van het gegevensbronpad

De waarde Pad voor een gegevensbron wordt afgeleid van de vereiste parameters van de gegevensbronfunctie. Vereiste parameters kunnen worden uitgesloten van het pad door toe te voegen aan de metagegevens van de functie DataSource.Path = false (zie hieronder).

Standaard ziet u de werkelijke tekenreekswaarde in het dialoogvenster Instellingen voor gegevensbron in Power BI Desktop en in de referentieprompt. Als de definitie Soort gegevensbron een waarde heeft opgenomen, ziet u in plaats Label daarvan de labelwaarde.

De gegevensbronfunctie in het voorbeeld HelloWorldWithDocs heeft bijvoorbeeld de volgende handtekening:

HelloWorldWithDocs.Contents = (message as text, optional count as number) as table => ...

De functie heeft één vereiste parameter ( ) van het type en wordt message text gebruikt om het gegevensbronpad te berekenen. De optionele parameter ( count ) wordt genegeerd. Het pad wordt weergegeven

Referentieprompt:

DataSourceCredentials.

Gebruikersinterface voor instellingen voor gegevensbron:

DataSourceSettings.

Wanneer een labelwaarde is gedefinieerd, wordt de waarde voor het gegevensbronpad niet weergegeven:

DataSourceLabel.

Notitie

We raden u momenteel aan geen Label op te nemen voor uw gegevensbron als uw functie vereiste parameters heeft, omdat gebruikers geen onderscheid kunnen maken tussen de verschillende referenties die ze hebben ingevoerd. We hopen dit in de toekomst te verbeteren (dat wil zeggen, zodat gegevensconnectoren hun eigen aangepaste gegevensbronpaden kunnen weergeven).

Vereiste parameters uitsluiten van uw gegevensbronpad

Als u wilt dat een functieparameter vereist is, maar niet moet worden opgenomen als onderdeel van uw gegevensbronpad, kunt u toevoegen aan de metagegevens van de DataSource.Path = false functiedocumentatie. Deze eigenschap kan worden toegevoegd aan een of meer parameters voor uw functie. Met dit veld wordt de waarde uit uw gegevensbronpad verwijderd (wat betekent dat deze niet meer wordt doorgegeven aan uw functie). Deze waarde mag dus alleen worden gebruikt voor parameters die niet nodig zijn om uw gegevensbron te identificeren of om onderscheid te maken tussen TestConnection gebruikersreferenties.

De connector in het voorbeeld HelloWorldWithDocs vereist bijvoorbeeld verschillende referenties voor verschillende message waarden. Als u toevoegt aan de parameter, wordt deze verwijderd uit de berekening van het gegevensbronpad, waardoor de connector een DataSource.Path = false message 'singleton' wordt. Alle HelloWorldWithDocs.Contents aanroepen naar worden behandeld als dezelfde gegevensbron en de gebruiker geeft slechts eenmaal referenties op.

HelloWorldType = type function (
    message as (type text meta [
        DataSource.Path = false,
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

Functies met een URI-parameter

Omdat gegevensbronnen met een id op basis van URI zo gebruikelijk zijn, is er speciale verwerking in de Power Query ui bij het verwerken van op URI gebaseerde gegevensbronpaden. Wanneer er een gegevensbron op basis van URI wordt aangetroffen, bevat het referentiedialoogvenster een vervolgkeuzevenster waarin de gebruiker het basispad kan selecteren in plaats van het volledige pad (en alle tussenpaden).

DataSourceUrl.

Zoals een toegekend type is in plaats van een primitief type in de M-taal, moet u de functie Uri.Type Value.ReplaceType gebruiken om aan te geven dat uw tekstparameter moet worden behandeld als een URI.

shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.Type) as any);

Aanvullende typen verificatie

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