A hitelesítés kezelése

Cikk
07/04/2024

Hitelesítési típusok

A bővítmények támogathatnak egy vagy több típusú hitelesítést. Minden hitelesítési típus más típusú hitelesítő adat. A Power Queryben a végfelhasználók számára megjelenített hitelesítési felhasználói felületet a bővítmény által támogatott hitelesítő adatok típusa vezérli.

A támogatott hitelesítési típusok listája a bővítmény adatforrástípus-definíciójának részeként van definiálva. Minden hitelesítési érték egy adott mezőkkel rendelkező rekord. Az alábbi táblázat az egyes típusokhoz tartozó várt mezőket sorolja fel. Az összes mező kötelező, kivéve, ha másként van megjelölve.

Hitelesítési típus	Mező	Leírás
Névtelen		A névtelen (más néven `Implicit`) hitelesítési típusnak nincs mezője.
OAuth	StartLogin	Az OAuth-folyamat elindításához szükséges URL-címet és állapotinformációt biztosító függvény. Nyissa meg az OAuth Flow implementálási szakaszát .
	FinishLogin	Az OAuth-folyamathoz kapcsolódó access_token és egyéb tulajdonságokat kinyerő függvény.
	Frissítés	(nem kötelező) Függvény, amely egy új hozzáférési jogkivonatot kér le egy frissítési jogkivonatból.
	Kijelentkezés	(nem kötelező) A felhasználó aktuális hozzáférési jogkivonatát érvénytelenítő függvény.
	Címke	(nem kötelező) Szöveges érték, amely lehetővé teszi az AuthenticationKind alapértelmezett címke felülbírálását.
Aad	AuthorizationUri	`text` érték vagy unary függvény, amely a Microsoft Entra ID engedélyezési végpontját adja vissza (például: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Nyissa meg a Microsoft Entra ID hitelesítési szakaszt.
	Erőforrás	`text` érték vagy unary függvény, amely a Szolgáltatás Microsoft Entra-azonosítójának erőforrás-értékét adja vissza.
	Hatókör	(nem kötelező) `text` érték vagy unary függvény, amely a hitelesítési folyamat részeként kérendő hatókör(ek) listáját adja vissza. Több hatókörértéket szóközzel kell elválasztani. A hatókör értékének a hatókör nevének kell lennie, alkalmazásazonosító URI nélkül (például: `Data.Read`). Ha nincs megadva, a rendszer kéri a `user_impersonation` hatókört.
UsernamePassword	UsernameLabel	(nem kötelező) A hitelesítő adatok felhasználói felületén található Felhasználónév szövegmező alapértelmezett címkéjének lecserélésére szolgáló szöveges érték.
	PasswordLabel	(nem kötelező) A hitelesítő adatok felhasználói felületén található Jelszó szövegmező alapértelmezett címkéjének lecserélésére szolgáló szöveges érték.
	Címke	(nem kötelező) Szöveges érték, amely lehetővé teszi az AuthenticationKind alapértelmezett címke felülbírálását.
Windows	UsernameLabel	(nem kötelező) A hitelesítő adatok felhasználói felületén található Felhasználónév szövegmező alapértelmezett címkéjének lecserélésére szolgáló szöveges érték.
	PasswordLabel	(nem kötelező) A hitelesítő adatok felhasználói felületén található Jelszó szövegmező alapértelmezett címkéjének lecserélésére szolgáló szöveges érték.
	Címke	(nem kötelező) Szöveges érték, amely lehetővé teszi az AuthenticationKind alapértelmezett címke felülbírálását.
Kulcs	KeyLabel	(nem kötelező) A hitelesítő adatok felhasználói felületén található API-kulcs szövegmezőjének alapértelmezett címkéjét lecserélő szöveges érték.
	Címke	(nem kötelező) Szöveges érték, amely lehetővé teszi az AuthenticationKind alapértelmezett címke felülbírálását.

Az alábbi minta egy olyan összekötő hitelesítési rekordját mutatja be, amely támogatja az OAuth, a Kulcs, a Windows, az Alapszintű (Felhasználónév és jelszó) és a Névtelen hitelesítő adatokat.

Példa:

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

Az aktuális hitelesítő adatok elérése

Az aktuális hitelesítő adatok a Extension.CurrentCredential függvény használatával kérhetők le.

A bővíthetőség érdekében engedélyezett M adatforrásfüggvények automatikusan öröklik a bővítmény hitelesítőadat-hatókörét. A legtöbb esetben nem kell explicit módon hozzáférnie az aktuális hitelesítő adatokhoz, azonban vannak kivételek, például:

A hitelesítő adatok átadása egyéni fejlécben vagy lekérdezési sztringparaméterben (például az API-kulcs hitelesítési típusának használatakor).
Az ODBC- vagy ADO.NET-bővítmények kapcsolati sztring tulajdonságainak beállítása.
Egyéni tulajdonságok ellenőrzése egy OAuth-jogkivonaton.
A hitelesítő adatok használata egy OAuth v1-folyamat részeként.

A Extension.CurrentCredential függvény egy rekordobjektumot ad vissza. A benne található mezők hitelesítési típusspecifikusak. Az alábbi táblázat részleteket tartalmaz.

Mező	Leírás	Felhasználta:
AuthenticationKind	A hitelesítő adatokhoz (UsernamePassword, OAuth stb.) rendelt hitelesítési típus nevét tartalmazza.	Mind
Felhasználónév	Felhasználónév értéke	UsernamePassword, Windows
Jelszó	Jelszóérték. Általában a UsernamePassword-hez használatos, de a Kulcshoz is be van állítva.	Key, UsernamePassword, Windows
access_token	OAuth hozzáférési jogkivonat értéke.	OAuth
Tulajdonságok	Egy adott hitelesítő adat egyéb egyéni tulajdonságait tartalmazó rekord. Az OAuth általában a access_token által visszaadott egyéb tulajdonságok (például a refresh_token) tárolására szolgál a hitelesítési folyamat során.	OAuth
Kulcs	Az API-kulcs értéke. Vegye figyelembe, hogy a kulcs értéke a Jelszó mezőben is elérhető. Alapértelmezés szerint a egyesítési motor úgy szúrja be ezt a kulcsot egy engedélyezési fejlécbe, mintha ez az érték alapszintű hitelesítési jelszó (felhasználónév nélkül). Ha ez a viselkedéstípus nem az, amit szeretne, meg kell adnia a Manuális hitelesítő adatok = igaz beállítást a beállításrekordban.	Kulcs
EncryptConnection	Logikai érték, amely meghatározta, hogy szükséges-e titkosított kapcsolat az adatforráshoz. Ez az érték minden hitelesítési típushoz elérhető, de csak akkor van beállítva, ha a EncryptConnection az adatforrás definíciójában van megadva.	Mind

Az alábbi kódminta hozzáfér egy API-kulcs aktuális hitelesítő adataihoz, és azt használja egy egyéni fejléc (x-APIKey) feltöltéséhez.

Példa:

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

OAuth-folyamat implementálása

Az OAuth-hitelesítés típusa lehetővé teszi, hogy a bővítmény egyéni logikát implementáljon a szolgáltatáshoz. Ehhez a bővítmény függvényeket StartLogin biztosít (az OAuth-folyamat elindításához szükséges engedélyezési URI visszaadása) és FinishLogin (a hozzáférési jogkivonat engedélyezési kódjának cseréje). A bővítmények igény szerint implementálhatók Refresh (új hozzáférési jogkivonatok frissítési jogkivonatának cseréje) és Logout (az aktuális frissítési és hozzáférési jogkivonatok lejárata) is.

Feljegyzés

A Power Query-bővítmények kiértékelése az ügyfélszámítógépeken futó alkalmazásokban történik. Az adatösszekötők nem használhatnak bizalmas titkos kulcsokat az OAuth-folyamatokban, mivel a felhasználók megvizsgálhatják a bővítményt vagy a hálózati forgalmat a titkos kód megismeréséhez. Az OAuth nyilvános ügyfelek RFC-je (más néven PKCE) által használt Kódcsere ellenőrzőkulcsa című témakörben további információt talál a megosztott titkos kódokra nem támaszkodó folyamatok biztosításáról. Ennek a folyamatnak a minta implementációja megtalálható a GitHub-webhelyen.

Az OAuth-függvények aláírásának két halmaza van: az eredeti aláírás, amely minimális számú paramétert tartalmaz, és egy speciális aláírás, amely több paramétert fogad el. A legtöbb OAuth-folyamat az eredeti aláírásokkal implementálható. Az implementációban az aláírástípusok is keverhetők és egyeztethetők. A függvényhívások a paraméterek száma (és típusuk) alapján egyezések. A paraméternevek nem kerülnek figyelembevételre.

További részletekért nyissa meg a GitHub-mintát .

Eredeti OAuth-aláírások

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

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

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

Logout = (accessToken) => ...;

Speciális OAuth-aláírások

Megjegyzések a speciális aláírásokról:

Minden aláírás elfogad egy rekordértéket clientApplication , amely későbbi használatra van fenntartva.
Minden aláírás elfogad egy dataSourcePath (más néven a resourceUrl legtöbb mintában).
A Refresh függvény elfogad egy paramétertoldCredential, amely a függvény által visszaadott (recordvagy az előző hívás) Refresháltal FinishLogin visszaadott paraméter.

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

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

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

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

Microsoft Entra ID-hitelesítés

A Aad hitelesítési típus a Microsoft Entra ID OAuth speciális verziója. Ugyanazt a Microsoft Entra ID-ügyfelet használja, mint a szervezeti fiókhitelesítést támogató beépített Power Query-összekötők. További információkért tekintse meg a Microsoft Entra egyéni összekötőkhöz való konfigurálását ismertető rövid útmutatót.

Feljegyzés

Ha saját OAuth-folyamatot implementál a Microsoft Entra-azonosítóhoz, azok a felhasználók, akik engedélyezték a feltételes hozzáférést a bérlőjük számára, problémákat tapasztalhatnak a Power BI szolgáltatás használatával történő frissítéskor. Ez nem befolyásolja az átjáróalapú frissítést, de hatással lenne egy hitelesített összekötőre, amely támogatja a Power BI szolgáltatás frissítését. A felhasználók a webes hitelesítő adatok Power BI szolgáltatás keresztüli konfigurálásakor előfordulhatnak, hogy az összekötőből eredő probléma egy nyilvános ügyfélalkalmazás használatával jelentkezik. A folyamat által létrehozott hozzáférési jogkivonatot végső soron egy másik számítógépen (azaz egy Azure-adatközpontban lévő Power BI szolgáltatás, nem a vállalat hálózatán) fogja használni, mint az eredeti hitelesítéshez használt (vagyis az adatforrás hitelesítő adatait a vállalat hálózatán konfiguráló felhasználó számítógépén). A beépített Aad típus egy másik Microsoft Entra ID-ügyfél használatával oldja meg ezt a problémát, amikor hitelesítő adatokat konfigurál a Power BI szolgáltatás. Ez a beállítás nem érhető el a OAuth hitelesítési típust használó összekötők számára.

A legtöbb összekötőnek meg kell adnia a mezők és Resource a mezők értékeitAuthorizationUri. Mindkét mező lehet text érték, vagy egyetlen argumentumfüggvény, amely egy text valueértéket ad vissza.

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)

Az Uri-alapú azonosítót használó összekötőknek nem kell értéket megadniukResource. Alapértelmezés szerint az érték megegyezik az összekötő Uri paraméterének gyökérútvonalával. Ha az adatforrás Microsoft Entra-azonosító erőforrása eltér a tartományértékétől (például GUID-t használ), akkor meg kell adni egy Resource értéket.

Aad-hitelesítési típusú minták

Az alábbi esetben az adatforrás a microsoft entra-azonosító globális felhőbeli azonosítóját támogatja a közös bérlő használatával (nincs Azure B2B-támogatás). Az alapértelmezett hatókör kérése egy jogkivonatot ad vissza a Power Query-ügyfélalkalmazás-azonosító összes korábban engedélyezett hatókörével.

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

Az alábbi esetben az adatforrás az OpenID Connect (OIDC) vagy hasonló protokoll alapján támogatja a bérlőfelderítést. Ez a képesség lehetővé teszi az összekötő számára, hogy az adatforrás elérési útjának egy vagy több paramétere alapján meghatározza a megfelelő Microsoft Entra ID-végpontot. Ez a dinamikus felderítési módszer lehetővé teszi, hogy az összekötő támogassa az Azure B2B-t.


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

Egyéb típusú hitelesítés

Az ebben a cikkben nem szereplő más típusú hitelesítésről, például a Kerberos-alapú egyszeri bejelentkezésről további információt az összekötők további funkcióiról szóló cikkben talál.

Megosztás a következőn keresztül: