Hantera autentisering

Artikel
03/19/2024

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.

Typ av autentisering	Fält	beskrivning
Anonym		Autentiseringstyp anonym (kallas `Implicit`även ) har inga fält.
OAuth	StartLogin	Funktion som tillhandahåller URL och tillståndsinformation för att starta ett OAuth-flöde. Gå till avsnittet Implementera ett OAuth-flöde .
	FinishLogin	Funktion som extraherar access_token och andra egenskaper som är relaterade till OAuth-flödet.
	Uppdatera	(valfritt) Funktion som hämtar en ny åtkomsttoken från en uppdateringstoken.
	Utloggning	(valfritt) Funktion som ogiltigförklarar användarens aktuella åtkomsttoken.
	Etikett	(valfritt) Ett textvärde som gör att du kan åsidosätta standardetiketten för denna AuthenticationKind.
Aad	AuthorizationUri	`text` värde eller unary-funktion som returnerar Microsoft Entra ID-auktoriseringsslutpunkten (exempel: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Gå till avsnittet Microsoft Entra-ID-autentisering .
	Resurs	`text` värde eller unary-funktion som returnerar Microsoft Entra ID-resursvärdet för din tjänst.
	Omfattning	(valfritt) `text` värde eller unary-funktion som returnerar listan över omfång som ska begäras som en del av autentiseringsflödet. Flera omfångsvärden ska avgränsas med ett blanksteg. Omfångsvärdet ska vara omfångsnamnet, utan en program-ID-URI (exempel: `Data.Read`). När det inte anges begärs omfånget `user_impersonation` .
UsernamePassword	UsernameLabel	(valfritt) Ett textvärde som ersätter standardetiketten för textrutan Användarnamn i användargränssnittet för autentiseringsuppgifter.
	PasswordLabel	(valfritt) Ett textvärde som ersätter standardetiketten för textrutan Lösenord i användargränssnittet för autentiseringsuppgifter.
	Etikett	(valfritt) Ett textvärde som gör att du kan åsidosätta standardetiketten för denna AuthenticationKind.
Windows	UsernameLabel	(valfritt) Ett textvärde som ersätter standardetiketten för textrutan Användarnamn i användargränssnittet för autentiseringsuppgifter.
	PasswordLabel	(valfritt) Ett textvärde som ersätter standardetiketten för textrutan Lösenord i användargränssnittet för autentiseringsuppgifter.
	Etikett	(valfritt) Ett textvärde som gör att du kan åsidosätta standardetiketten för denna AuthenticationKind.
Nyckel	KeyLabel	(valfritt) Ett textvärde som ersätter standardetiketten för textrutan API-nyckel i användargränssnittet för autentiseringsuppgifter.
	Etikett	(valfritt) Ett textvärde som gör att du kan åsidosätta standardetiketten för denna AuthenticationKind.

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ält	beskrivning	Används av
AuthenticationKind	Innehåller namnet på den autentiseringstyp som tilldelats den här autentiseringsuppgiften (UsernamePassword, OAuth och så vidare).	Alla
Username	Användarnamnsvärde	UsernamePassword, Windows
Lösenord	Lösenordsvärde. Används vanligtvis med UsernamePassword, men det är också inställt för Nyckel.	Key, UsernamePassword, Windows
access_token	OAuth-åtkomsttokenvärde.	OAuth
Egenskaper	En post som innehåller andra anpassade egenskaper för en viss autentiseringsuppgift. Används vanligtvis med OAuth för att lagra andra egenskaper (till exempel refresh_token) som returneras med access_token under autentiseringsflödet.	OAuth
Nyckel	API-nyckelvärdet. Observera att nyckelvärdet också är tillgängligt i fältet Lösenord. Som standard infogar kombinationsmotorn den här nyckeln i ett auktoriseringshuvud som om det här värdet var ett grundläggande autentiseringslösenord (utan användarnamn). Om den här typen av beteende inte är det du vill använda måste du ange alternativet ManualCredentials = true i alternativposten.	Nyckel
EncryptConnection	Ett logiskt värde som fastställde om en krypterad anslutning till datakällan ska krävas. Det här värdet är tillgängligt för alla autentiseringstyper, men anges bara om EncryptConnection anges i definitionen för datakälla .	Alla

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.

Kommentar

Power Query-tillägg utvärderas i program som körs på klientdatorer. Data connectors bör inte använda konfidentiella hemligheter i sina OAuth-flöden, eftersom användarna kan inspektera tillägget eller nätverkstrafiken för att lära sig hemligheten. Gå till Proof Key for Code Exchange by OAuth Public Clients RFC (även kallat PKCE) för ytterligare information om att tillhandahålla flöden som inte förlitar sig på delade hemligheter. En exempelimplementering av det här flödet finns på vår GitHub-webbplats.

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 .

Kommentar

Om du implementerar ditt eget OAuth-flöde för Microsoft Entra-ID kan användare som har aktiverat villkorlig åtkomst för sin klientorganisation stöta på problem när de uppdaterar med hjälp av usluga Power BI. Detta påverkar inte gatewaybaserad uppdatering, men skulle påverka en certifierad anslutningsapp som stöder uppdatering från usluga Power BI. Användare kan stöta på ett problem som härrör från anslutningsappen med hjälp av ett offentligt klientprogram när de konfigurerar webbaserade autentiseringsuppgifter via usluga Power BI. Åtkomsttoken som genereras av det här flödet kommer slutligen att användas på en annan dator (d.v.s. den usluga Power BI i ett Azure-datacenter, inte i företagets nätverk) än den som användes för att ursprungligen autentisera (det vill: datorn för den användare som konfigurerar autentiseringsuppgifterna för datakällan i företagets nätverk). Den inbyggda Aad typen fungerar kring det här problemet genom att använda en annan Microsoft Entra-ID-klient när du konfigurerar autentiseringsuppgifter i usluga Power BI. Det här alternativet är inte tillgängligt för anslutningsappar som använder autentiseringstyp OAuth .

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.

Dela via