Kimlik doğrulamasını işleme

Makale
01/17/2024

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ü	Alan	Açıklama
Anonim		Anonim (aynı zamanda olarak da adlandırılır `Implicit`) kimlik doğrulama türünün hiçbir alanı yoktur.
OAuth	StartLogin	OAuth akışı başlatmak için URL ve durum bilgilerini sağlayan işlev. OAuth Akışı Uygulama bölümüne gidin.
	FinishLogin	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.
Acar	AuthorizationUri	`text` değeri veya Microsoft Entra Id yetkilendirme uç noktasını döndüren birli işlev (örnek: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Microsoft Entra Id kimlik doğrulaması bölümüne gidin.
	Kaynak	`text` değeri veya hizmetiniz için Microsoft Entra Id kaynak değerini döndüren birli işlev.
	Kapsam	(isteğe bağlı)`text` value veya birli işlev, kimlik doğrulama akışının bir parçası olarak istenecek kapsamların listesini döndürü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 kapsam `user_impersonation` istenir.
UsernamePassword	UsernameLabel	(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.
	PasswordLabel	(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	UsernameLabel	(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.
	PasswordLabel	(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.
Anahtar	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.

Örnek:

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

Geçerli kimlik bilgilerine erişme

Geçerli kimlik bilgileri işlevi kullanılarak Extension.CurrentCredential 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.

Alan	Açıklama	Kullanan
AuthenticationKind	Bu kimlik bilgilerine atanan kimlik doğrulama türünün adını içerir (UsernamePassword, OAuth vb.).	Tümünü
Username	Kullanıcı adı değeri	UsernamePassword, Windows
Parola	Parola değeri. Genellikle UsernamePassword ile kullanılır, ancak Anahtar için de ayarlanır.	Key, UsernamePassword, Windows
access_token	OAuth erişim belirteci değeri.	OAuth
Properties	Belirli bir kimlik bilgisi için diğer özel özellikleri içeren kayıt. Kimlik doğrulama akışı sırasında access_token döndürülen diğer özellikleri (refresh_token gibi) depolamak için genellikle OAuth ile kullanılır.	OAuth
Anahtar	API anahtar değeri. Anahtar değerinin Parola alanında da kullanılabilir olduğunu unutmayın. Varsayılan olarak, karma altyapısı bu anahtarı bir Yetkilendirme üst bilgisine, bu değer temel bir kimlik doğrulama parolasıymış gibi (kullanıcı adı olmadan) ekler. İstediğiniz davranış bu tür değilse, seçenekler kaydında ManualCredentials = true seçeneğini belirtmeniz gerekir.	Anahtar
Şifreleme Bağlan	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 Şifreleme Bağlan ion belirtilirse ayarlanır.	Tümünü

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.

Örnek:

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ışı 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 Logout (geçerli yenileme ve erişim belirteçlerinin süresinin dolması) işlevlerini de uygulayabilir Refresh .

Not

Power Query uzantıları, istemci makinelerinde çalışan uygulamalarda değerlendirilir. Kullanıcılar gizli diziyi öğrenmek için uzantıyı veya ağ trafiğini inceleyebileceği için veri Bağlan örleri OAuth akışlarında gizli gizli dizileri kullanmamalıdır. Paylaşılan gizli dizileri temel almayan akışlar sağlama hakkında daha fazla bilgi için OAuth Genel İstemcileri RFC (PKCE olarak da bilinir) tarafından Kod Değişimi için Yazım Denetleme Anahtarı'na 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 ).
İşlevRefresh, işlevinizin FinishLogin (veya önceki çağrısı ) tarafından döndürülen önceki record parametreyi Refreshkabul ederoldCredential.

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.

Not

Microsoft Entra Id için kendi OAuth akışınızı uygularsanız, kiracıları için Koşullu Erişim'i etkinleştiren kullanıcılar, Power BI hizmeti kullanarak yenileme yaparken sorunlarla karşılaşabilir. Bu, ağ geçidi tabanlı yenilemeyi etkilemez, ancak Power BI hizmeti 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 (şirketin ağında değil, azure veri merkezindeki Power BI hizmeti) kullanılır. Yerleşik Aad tür, Power BI hizmeti 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ının ve Resource alanları için AuthorizationUri değer sağlaması gerekir. Her iki alan da değerler veya döndüren tek bir text valuebağımsız değişken işlevi olabilirtext.

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)

kullanan Bağlan orlar Uri tabanlı tanımlayıcını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 = "77256ee0-fe79-11ea-adc1-0242ac120002", // Entra Application ID URI or app guid
        Scope = ".default"
    ]
]

Aşağıdaki durumda, veri kaynağı OpenID Bağlan (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.