Aracılığıyla paylaş

Kimlik doğrulamasını işleme

Kimlik doğrulama türleri

Bir uzantı bir veya daha fazla Kimlik Doğrulaması türünü destekleyebilir. Her kimlik doğrulama türü farklı bir kimlik bilgisi türüdür. Power Query'de son kullanıcılara görüntülenen kimlik doğrulama kullanıcı arabirimi, bir uzantının desteklediği kimlik bilgileri türüne göre yönlendirilir.

Desteklenen kimlik doğrulama türlerinin listesi, uzantının Veri Kaynağı Türü tanımının bir parçası olarak tanımlanır. Her Kimlik Doğrulama değeri, belirli alanlara sahip bir kayıttır. Aşağıdaki tabloda her tür için beklenen alanlar listelenmektedir. Aksi işaretlenmediği sürece tüm alanlar gereklidir.

Kimlik Doğrulama Türü Veri Alanı Description
Anonim Anonim (aynı zamanda olarak da adlandırılır Implicit) kimlik doğrulama türünün hiçbir alanı yoktur.
OAuth GirişBaşlat OAuth akışı başlatmak için URL ve durum bilgilerini sağlayan işlev.

OAuth Akışı Uygulama bölümüne gidin.
OturumuTamamla access_token ve OAuth akışıyla ilgili diğer özellikleri ayıklayan işlev.
Yenile (isteğe bağlı) Yenileme belirtecinden yeni erişim belirteci alan işlev.
Oturumu kapatma (isteğe bağlı) Kullanıcının geçerli erişim belirtecini geçersiz kıldığını belirten işlev.
Etiket (isteğe bağlı) Bu AuthenticationKind için varsayılan etiketi geçersiz kılmanıza olanak tanıyan bir metin değeri.
Aad AuthorizationUri text değeri veya Microsoft Entra ID yetkilendirme uç noktasını döndüren unary function (örnek: "https://login.microsoftonline.com/common/oauth2/authorize").

Microsoft Entra Id kimlik doğrulaması bölümüne gidin.
Resource text değeri veya hizmetiniz için Microsoft Entra ID kaynak değerini döndüren birincil işlev.
Scope (isteğe bağlı)text değer veya tekli işlev, kimlik doğrulama akışının bir parçası olarak istenecek kapsamların listesini döndürmek için kullanılır. Birden çok kapsam değeri boşlukla ayrılmalıdır. Kapsam değeri, Uygulama Kimliği URI'si olmadan kapsam adı olmalıdır (örnek: Data.Read). Sağlanmadığında, user_impersonation kapsamı talep edilir.
KullanıcıAdıParola Kullanıcı Adı Etiketi (isteğe bağlı) Kimlik bilgileri kullanıcı arabirimindeki Kullanıcı adı metin kutusunun varsayılan etiketini değiştirmek için bir metin değeri.
Şifre Etiketi (isteğe bağlı) Kimlik bilgileri kullanıcı arabirimindeki Parola metin kutusunun varsayılan etiketini değiştirmek için bir metin değeri.
Etiket (isteğe bağlı) Bu AuthenticationKind için varsayılan etiketi geçersiz kılmanıza olanak tanıyan bir metin değeri.
Windows Kullanıcı Adı Etiketi (isteğe bağlı) Kimlik bilgileri kullanıcı arabirimindeki Kullanıcı adı metin kutusunun varsayılan etiketini değiştirmek için bir metin değeri.
Parola Etiketi (isteğe bağlı) Kimlik bilgileri kullanıcı arabirimindeki Parola metin kutusunun varsayılan etiketini değiştirmek için bir metin değeri.
Etiket (isteğe bağlı) Bu AuthenticationKind için varsayılan etiketi geçersiz kılmanıza olanak tanıyan bir metin değeri.
Key KeyLabel (isteğe bağlı) Kimlik bilgileri kullanıcı arabirimindeki API Anahtarı metin kutusunun varsayılan etiketini değiştirmek için bir metin değeri.
Etiket (isteğe bağlı) Bu AuthenticationKind için varsayılan etiketi geçersiz kılmanıza olanak tanıyan bir metin değeri.

Aşağıdaki örnekte OAuth, Key, Windows, Basic (Kullanıcı adı ve Parola) ve Anonim kimlik bilgilerini destekleyen bir bağlayıcı için Kimlik Doğrulama kaydı gösterilmektedir.

Example:

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

Geçerli kimlik bilgilerine erişme

Geçerli kimlik bilgileri Extension.CurrentCredential işlevi kullanılarak alınabilir.

Genişletilebilirlik için etkinleştirilen M veri kaynağı işlevleri, uzantınızın kimlik bilgisi kapsamını otomatik olarak devralır. Çoğu durumda, geçerli kimlik bilgilerine açıkça erişmeniz gerekmez, ancak aşağıdakiler gibi özel durumlar vardır:

  • Kimlik bilgilerini özel üst bilgi veya sorgu dizesi parametresinde geçirme (örneğin, API Anahtarı kimlik doğrulaması türünü kullanırken).
  • ODBC veya ADO.NET uzantıları için bağlantı dizesi özelliklerini ayarlama.
  • OAuth belirtecinde özel özellikleri denetleme.
  • Kimlik bilgilerini OAuth v1 akışının bir parçası olarak kullanma.

Extension.CurrentCredential İşlev bir kayıt nesnesi döndürür. İçeren alanlar kimlik doğrulama türüne özgü. Aşağıdaki tabloda ayrıntılar yer alır.

Veri Alanı Description Kullanan
AuthenticationKind (Kimlik Doğrulama Türü) Bu kimlik bilgilerine atanan kimlik doğrulama türünün adını içerir (UsernamePassword, OAuth vb.). Tümü
Kullanıcı adı Kullanıcı adı değeri Kullanıcı Adı Şifresi, Windows
Şifre Parola değeri. Genellikle UsernamePassword ile kullanılır, ancak Anahtar için de ayarlanır. Anahtar, Kullanıcı Adı ve Şifre, Windows
access_token OAuth erişim belirteci değeri. OAuth
Özellikler Belirli bir kimlik bilgisi için diğer özel özellikleri içeren kayıt. Genellikle kullanılır OAuth ile kimlik doğrulama akışı sırasında access_token'la birlikte döndürülen diğer özellikleri depolamak için (örneğin, refresh_token). OAuth
Key API anahtar değeri. Anahtar değerinin Parola alanında da kullanılabilir olduğunu unutmayın. Varsayılan olarak, birleştirme motoru bu anahtarı, bu değer temel bir kimlik doğrulama parolasıymış gibi (kullanıcı adı olmadan) bir Yetkilendirme üst bilgisine ekler. İstediğiniz davranış bu tür değilse, seçenekler kaydında ManualCredentials = true seçeneğini belirtmeniz gerekir. Key
EncryptConnection Veri kaynağına şifreli bağlantı gerekip gerekmediğini belirleyen mantıksal değer. Bu değer tüm Kimlik Doğrulama Türleri için kullanılabilir, ancak yalnızca Veri Kaynağı tanımında EncryptConnection belirtilirse ayarlanır. Tümü

Aşağıdaki kod örneği, bir API anahtarının geçerli kimlik bilgilerine erişir ve bunu özel bir üst bilgiyi (x-APIKey ) doldurmak için kullanır.

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 akışını uygulama

OAuth kimlik doğrulama türü, bir uzantının kendi hizmeti için özel mantık uygulamasına olanak tanır. Bunu yapmak için uzantı , (OAuth akışını başlatmak için StartLogin yetkilendirme URI'sini döndürme) ve FinishLogin (erişim belirteci için yetkilendirme kodunun değişmesi) işlevleri sağlar. Uzantılar isteğe bağlı olarak (yeni erişim belirteci için yenileme belirteci alışverişi) ve Refresh (geçerli yenileme ve erişim belirteçlerinin süresinin dolması) işlevlerini de uygulayabilir Logout .

Uyarı

Power Query uzantıları, istemci makinelerinde çalışan uygulamalarda değerlendirilir. Kullanıcılar gizli bilgileri öğrenmek için uzantıyı veya ağ trafiğini inceleyebileceği için Veri Bağlayıcıları OAuth akışlarında gizli bilgileri kullanmamalıdır. Paylaşılan gizli bilgilere dayanmayan akışlar sunma hakkında daha fazla bilgi için OAuth Genel Kullanıcılar için Kod Değişimi Kanıt Anahtarı (PKCE olarak da bilinir) RFC’ye gidin. Bu akışın örnek bir uygulaması GitHub sitemizde bulunabilir.

İki OAuth işlevi imzası kümesi vardır: en az sayıda parametre içeren özgün imza ve daha fazla parametre kabul eden gelişmiş imza. Çoğu OAuth akışı özgün imzalar kullanılarak uygulanabilir. Ayrıca, uygulamanızdaki imza türlerini karıştırabilir ve eşleştirebilirsiniz. İşlev çağrıları, parametre sayısına (ve türlerine) göre eşleşir. Parametre adları dikkate alınmaz.

Diğer ayrıntılar için GitHub örneğine gidin.

Özgün OAuth imzaları

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

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

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

Logout = (accessToken) => ...;

Gelişmiş OAuth imzaları

Gelişmiş imzalar hakkında notlar:

  • Tüm imzalar, gelecekte kullanmak üzere ayrılmış bir clientApplication kayıt değeri kabul eder.
  • Tüm imzalar bir dataSourcePath değerini kabul eder (çoğu örnekte de denir resourceUrl ).
  • İşlev Refresh, işlevinizin (veya önceki Refresh çağrısı) tarafından döndürülen önceki record parametresi olan FinishLogin kabul eder.
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

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

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

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

Microsoft Entra Id kimlik doğrulaması

Aad Kimlik doğrulama türü, Microsoft Entra Id için OAuth'un özel bir sürümüdür. Kuruluş hesabı kimlik doğrulamasını destekleyen yerleşik Power Query bağlayıcılarıyla aynı Microsoft Entra ID istemcisini kullanır. Özel bağlayıcı için Microsoft Entra yapılandırma hızlı başlangıç kılavuzunda daha fazla bilgi bulabilirsiniz.

Uyarı

Microsoft Entra Id için kendi OAuth akışınızı uygularsanız, kiracıları için Koşullu Erişimi etkinleştirmiş kullanıcılar Power BI hizmetini kullanarak yenileme yaparken sorunlarla karşılaşabilir. Bu, ağ geçidi tabanlı yenilemeyi etkilemez, ancak Power BI hizmetinden yenilemeyi destekleyen sertifikalı bir bağlayıcıyı etkiler. Kullanıcılar, Power BI hizmeti aracılığıyla web tabanlı kimlik bilgilerini yapılandırırken genel istemci uygulaması kullanarak bağlayıcıdan kaynaklanan bir sorunla karşılaşabilir. Bu akış tarafından oluşturulan erişim belirteci, başlangıçta kimlik doğrulaması yapmak için kullanılandan (yani şirketin ağında veri kaynağı kimlik bilgilerini yapılandıran kullanıcının bilgisayarında) farklı bir bilgisayarda (yani, şirketin ağında değil, azure veri merkezindeki Power BI hizmetinde) kullanılır. Yerleşik Aad tür, Power BI hizmetinde kimlik bilgilerini yapılandırırken farklı bir Microsoft Entra ID istemcisi kullanarak bu soruna geçici bir çözüm sağlar. Bu seçenek, kimlik doğrulama türünü kullanan OAuth bağlayıcılar tarafından kullanılamaz.

Çoğu bağlayıcı, AuthorizationUri ve Resource alanları için değer sağlamalıdır. Her iki alan da text değerleri olabilir veya text value döndüren tek bir bağımsız değişken işlevi.

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)

Uri tabanlı tanımlayıcı kullanan bağlayıcıların bir Resource değer sağlaması gerekmez. Varsayılan olarak, değer bağlayıcının Uri parametresinin kök yoluna eşittir. Veri kaynağının Microsoft Entra Id kaynağı etki alanı değerinden farklıysa (örneğin GUID kullanıyorsa) bir Resource değer sağlanması gerekir.

Aad kimlik doğrulama türü örnekleri

Aşağıdaki durumda, veri kaynağı ortak kiracıyı kullanarak genel bulut Microsoft Entra ID'yi destekler (Azure B2B desteği yoktur). .default kapsamını istemek, Power Query istemci uygulaması kimliği için daha önce yetkilendirilmiş tüm kapsamlara sahip bir belirteç döndürür.

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

Aşağıdaki durumda, veri kaynağı OpenID Connect (OIDC) veya benzer bir protokole göre kiracı bulmayı destekler. Bu özellik, bağlayıcının veri kaynağı yolundaki bir veya daha fazla parametreye göre kullanılacak doğru Microsoft Entra Id uç noktasını belirlemesine olanak tanır. Bu dinamik bulma yaklaşımı bağlayıcının Azure B2B'yi desteklemesini sağlar.


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

Diğer kimlik doğrulama türleri

Kerberos tabanlı çoklu oturum açma gibi bu makalede ele alınmayan diğer kimlik doğrulama türleri hakkında daha fazla bilgi edinmek için ek bağlayıcı işlevselliği makalesini ziyaret edin.

  • Last updated on