A hitelesítés kezelése

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ú azonosító. 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 szakterület Description
Névtelen A névtelen (más néven Implicit) hitelesítési típusnak nincs mezője.
OAuth Indítás Bejelentkezés 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 .
BefejezésBejelentkezés Az OAuth-folyamathoz kapcsolódó access_token és egyéb tulajdonságokat kinyerő függvény.
Felfrissít (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 .
Resource text érték vagy egyváltozós függvény, amely a szolgáltatás Microsoft Entra-azonosítójának erőforrás-értékét adja vissza.
Scope (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.
FelhasználónévJelszó Felhasználónév címke (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.
JelszóCímke (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 Felhasználónév címke (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.
JelszóCímke (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.
Key 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.

Example:

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).
  • Kapcsolati sztring tulajdonságainak beállítása ODBC- vagy ADO.NET-bővítményekhez.
  • 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.

szakterület Description Felhasználta:
AuthenticationKind A hitelesítő adatokhoz (UsernamePassword, OAuth stb.) rendelt hitelesítési típus nevét tartalmazza. All
Felhasználónév Felhasználónév értéke FelhasználónévJelszó, Windows
Jelszó Jelszóérték. Általában a UsernamePassword-hez használatos, de a Kulcshoz is be van állítva. Kulcs, Felhasználónév és Jelszó, 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
Key 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ú viselkedés nem az, amit szeretne, meg kell adnia a ManualCredentials = true beállítást a beállítási rekordban. Key
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. All

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.

Example:

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 opcionálisan megvalósíthatják a Refresh (egy frissítési jogkivonat egy új hozzáférési jogkivonatra cserélése) és a Logout (az aktuális frissítési és hozzáférési jogkivonatok érvényességének megszüntetése) funkciókat is.

Megjegyzé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.
  • Az összes aláírás elfogad egy dataSourcePath-t (amit a legtöbb mintában resourceUrl-ként is említenek).
  • A Refresh függvény elfogad egy oldCredential paramétert, amely a korábbi record által visszaadott érték, amit az ön FinishLogin függvénye vagy az előző Refresh hívás adott vissza.
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.

Megjegyzés:

Ha saját OAuth-folyamatot implementál Microsoft Entra ID számára, a bérlőhöz feltételes hozzáférést engedélyező felhasználók problémákba ütközhetnek a Power BI szolgáltatás használatával végzett frissítéskor. Ez a probléma nem befolyásolja az átjáróalapú frissítést, de hatással van egy hitelesített összekötőre, amely támogatja a Power BI szolgáltatás frissítését. Előfordulhat, hogy a felhasználók egy nyilvános ügyfélalkalmazás használatával az összekötőből eredő problémába ütköznek, amikor webes hitelesítő adatokat konfigurálnak a Power BI szolgáltatáson keresztül. A folyamat által létrehozott hozzáférési jogkivonatot végső soron egy másik számítógépen (vagyis egy Azure adatközpontban lévő Power BI szolgáltatás, nem pedig a vállalat hálózatán) használják, 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 típus egy másik Microsoft Entra ID-ügyfél Aad használatával oldja meg ezt a problémát, amikor hitelesítő adatokat konfigurál a Power BI szolgáltatásban. 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 AuthorizationUri és Resource mezők értékeit. 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 = "44445555-eeee-6666-ffff-7777aaaa8888"   // 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 megadniuk Resource . 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

A következő esetben az adatforrás a Microsoft Entra ID globális felhőszolgáltatást támogatja a közös bérlő használatával (nincs Azure B2B támogatás). A alapértelmezett hatókör kérése egy tokent ad vissza a Power Query-ügyfélalkalmazás összes korábban engedélyezett hatókörével.

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

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.

  • Last updated on