Hantera autentisering

Autentiseringstyper

Ett tillägg kan stödja en eller flera typer av autentisering. Varje typ av autentisering är en annan typ av autentiseringsuppgifter. Användargränssnittet för autentisering som visas för slutanvändare i Power Query styrs av den typ av autentiseringsuppgifter som ett tillägg stöder.

Listan över autentiseringstyper som stöds definieras som en del av ett tilläggs definition av typ av datakälla . Varje autentiseringsvärde är en post med specifika fält. I följande tabell visas de förväntade fälten för varje typ. Alla fält krävs om de inte har markerats på annat sätt.

Följande exempel visar autentiseringsposten för en anslutningsapp som stöder autentiseringsuppgifterna OAuth, Key, Windows, Basic (användarnamn och lösenord) och Anonym.

Exempel:

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

Åtkomst till aktuella autentiseringsuppgifter

De aktuella autentiseringsuppgifterna kan hämtas med hjälp av Extension.CurrentCredential funktionen .

M-datakällans funktioner som har aktiverats för utökningsbarhet ärver automatiskt tilläggets omfång för autentiseringsuppgifter. I de flesta fall behöver du inte uttryckligen komma åt de aktuella autentiseringsuppgifterna, men det finns undantag, till exempel:

• Skicka in autentiseringsuppgifterna i en anpassad rubrik eller frågesträngsparameter (till exempel när du använder API Key-autentiseringstypen).
• Ange niska veze egenskaper för ODBC- eller ADO.NET-tillägg.
• Kontrollera anpassade egenskaper på en OAuth-token.
• Använda autentiseringsuppgifterna som en del av ett OAuth v1-flöde.

Funktionen Extension.CurrentCredential returnerar ett postobjekt. Fälten som den innehåller är specifika för autentiseringstyp. Följande tabell innehåller information.

Följande kodexempel använder den aktuella autentiseringsuppgiften för en API-nyckel och använder den för att fylla i en anpassad rubrik (x-APIKey).

Exempel:

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

Implementera ett OAuth-flöde

Med OAuth-autentiseringstypen kan ett tillägg implementera anpassad logik för tjänsten. För att göra detta tillhandahåller ett tillägg funktioner för (returnerar auktoriserings-URI:n för StartLogin att initiera OAuth-flödet) och FinishLogin (utbyte av auktoriseringskoden för en åtkomsttoken). Tillägg kan också implementera Refresh (byta ut en uppdateringstoken mot en ny åtkomsttoken) och Logout (upphör att gälla för aktuella uppdaterings- och åtkomsttoken) funktioner.

Det finns två uppsättningar med OAuth-funktionssignaturer: den ursprungliga signaturen som innehåller ett minimalt antal parametrar och en avancerad signatur som accepterar fler parametrar. De flesta OAuth-flöden kan implementeras med hjälp av de ursprungliga signaturerna. Du kan också blanda och matcha signaturtyper i implementeringen. Funktionsanropen är matchningar baserat på antalet parametrar (och deras typer). Parameternamnen beaktas inte.

Gå till GitHub-exemplet för mer information.

Ursprungliga OAuth-signaturer

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

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

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

Logout = (accessToken) => ...;

Avancerade OAuth-signaturer

Information om avancerade signaturer:

• Alla signaturer accepterar ett clientApplication postvärde som är reserverat för framtida användning.
• Alla signaturer accepterar en dataSourcePath (kallas även för resourceUrl i de flesta exempel).
• Funktionen Refresh accepterar en oldCredential parameter, som är den tidigare record som returnerades av funktionen FinishLogin (eller föregående anrop till Refresh).

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

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

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

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

Microsoft Entra ID-autentisering

Autentiseringstyp Aad är en specialiserad version av OAuth för Microsoft Entra-ID. Den använder samma Microsoft Entra-ID-klient som de inbyggda Power Query-anslutningsapparna som stöder autentisering av organisationskonton. Mer information finns i snabbstartsguiden Konfigurera Microsoft Entra för en anpassad anslutningsapp .

De flesta anslutningsappar måste ange värden för fälten AuthorizationUri och Resource . Båda fälten kan vara text värden eller en enskild argumentfunktion som returnerar 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)

Anslutningsappar som använder en URI-baserad identifierare behöver inte ange något Resource värde. Som standard är värdet lika med rotsökvägen för anslutningsappens URI-parameter. Om datakällans Microsoft Entra-ID-resurs skiljer sig från domänvärdet (till exempel använder den ett GUID) måste ett Resource värde anges.

Exempel på Aad-autentiseringstyp

I följande fall stöder datakällan microsoft entra-ID för globalt moln med hjälp av den gemensamma klientorganisationen (inget Stöd för Azure B2B). Om du begär .default-omfånget returneras en token med alla tidigare auktoriserade omfång för Power Query-klientprogrammets ID.

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öljande fall stöder datakällan klientidentifiering baserat på OpenID Connect (OIDC) eller liknande protokoll. Med den här möjligheten kan anslutningsappen fastställa rätt Microsoft Entra-ID-slutpunkt som ska användas baserat på en eller flera parametrar i datakällsökvägen. Med den här metoden för dynamisk identifiering kan anslutningsappen stödja 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"
    ]
]

Andra typer av autentisering

Mer information om andra typer av autentisering som inte omfattas av den här artikeln, till exempel Kerberos-baserad enkel inloggning, finns i artikeln om ytterligare anslutningsfunktioner för mer information.