Menangani autentikasi

Artikel
07/04/2024

Jenis autentikasi

Ekstensi dapat mendukung satu atau beberapa jenis Autentikasi. Setiap jenis autentikasi adalah jenis kredensial yang berbeda. UI autentikasi yang ditampilkan kepada pengguna akhir di Power Query didorong oleh jenis kredensial yang didukung ekstensi.

Daftar jenis autentikasi yang didukung didefinisikan sebagai bagian dari definisi Jenis Sumber Data ekstensi. Setiap nilai Autentikasi adalah rekaman dengan bidang tertentu. Tabel berikut mencantumkan bidang yang diharapkan untuk setiap jenis. Semua bidang diperlukan kecuali ditandai sebaliknya.

Jenis Autentikasi	Bidang	Deskripsi
Anonim		Jenis autentikasi Anonim (juga disebut `Implicit`) tidak memiliki bidang apa pun.
OAuth	StartLogin	Fungsi yang menyediakan URL dan informasi status untuk memulai alur OAuth. Buka bagian Menerapkan Alur OAuth.
	FinishLogin	Fungsi yang mengekstrak access_token dan properti lain yang terkait dengan alur OAuth.
	Refresh	(opsional) Fungsi yang mengambil token akses baru dari token refresh.
	Keluar	(opsional) Fungsi yang membatalkan token akses pengguna saat ini.
	Label	(opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.
Aad	AuthorizationUri	`text` nilai atau fungsi unary yang mengembalikan titik akhir otorisasi ID Microsoft Entra (misalnya: `"https://login.microsoftonline.com/common/oauth2/authorize"`). Buka bagian autentikasi ID Microsoft Entra.
	Sumber daya	`text` nilai atau fungsi unary yang mengembalikan nilai sumber daya ID Microsoft Entra untuk layanan Anda.
	Cakupan	(opsional) `text` nilai atau fungsi unary yang mengembalikan daftar cakupan untuk diminta sebagai bagian dari alur autentikasi. Beberapa nilai cakupan harus dipisahkan oleh spasi. Nilai cakupan harus berupa nama cakupan, tanpa URI ID Aplikasi (misalnya: `Data.Read`). Ketika tidak disediakan, `user_impersonation` cakupan diminta.
Nama penggunaPassword	Nama penggunaLabel	(opsional) Nilai teks untuk mengganti label default untuk kotak teks Nama pengguna pada antarmuka pengguna kredensial.
	PasswordLabel	(opsional) Nilai teks untuk mengganti label default untuk kotak teks Kata Sandi pada antarmuka pengguna kredensial.
	Label	(opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.
Windows	Nama penggunaLabel	(opsional) Nilai teks untuk mengganti label default untuk kotak teks Nama pengguna pada antarmuka pengguna kredensial.
	PasswordLabel	(opsional) Nilai teks untuk mengganti label default untuk kotak teks Kata Sandi pada antarmuka pengguna kredensial.
	Label	(opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.
Tombol	KeyLabel	(opsional) Nilai teks untuk mengganti label default untuk kotak teks Kunci API pada antarmuka pengguna kredensial.
	Label	(opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.

Sampel berikut menunjukkan catatan Autentikasi untuk konektor yang mendukung kredensial OAuth, Kunci, Windows, Dasar (Nama Pengguna dan Kata Sandi), dan Anonim.

Contoh:

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

Mengakses kredensial saat ini

Kredensial saat ini dapat diambil menggunakan Extension.CurrentCredential fungsi .

Fungsi sumber data M yang telah diaktifkan untuk ekstensibilitas secara otomatis mewarisi cakupan kredensial ekstensi Anda. Dalam kebanyakan kasus, Anda tidak perlu secara eksplisit mengakses kredensial saat ini, namun, ada pengecualian, seperti:

Meneruskan kredensial di header kustom atau parameter string kueri (seperti saat Anda menggunakan jenis autentikasi Kunci API).
Mengatur properti string koneksi untuk ekstensi ODBC atau ADO.NET.
Memeriksa properti kustom pada token OAuth.
Menggunakan kredensial sebagai bagian dari alur OAuth v1.

Fungsi Extension.CurrentCredential mengembalikan objek rekaman. Bidang yang dikandungnya adalah jenis autentikasi tertentu. Tabel berikut berisi detail.

Bidang	Deskripsi	Digunakan Oleh
AuthenticationKind	Berisi nama jenis autentikasi yang ditetapkan ke kredensial ini (UsernamePassword, OAuth, dan sebagainya).	Semua
Nama Pengguna	Nilai nama pengguna	UsernamePassword, Windows
Kata sandi	Nilai kata sandi. Biasanya digunakan dengan UsernamePassword, tetapi juga diatur untuk Key.	Kunci, UsernamePassword, Windows
access_token	Nilai token akses OAuth.	OAuth
Properti	Rekaman yang berisi properti kustom lainnya untuk kredensial tertentu. Biasanya digunakan dengan OAuth untuk menyimpan properti lain (seperti refresh_token) yang dikembalikan dengan access_token selama alur autentikasi.	OAuth
Tombol	Nilai kunci API. Perhatikan, nilai kunci juga tersedia di bidang Kata Sandi juga. Secara default, mesin mashup menyisipkan kunci ini di header Otorisasi seolah-olah nilai ini adalah kata sandi autentikasi dasar (tanpa nama pengguna). Jika jenis perilaku ini bukan yang Anda inginkan, Anda harus menentukan opsi ManualCredentials = true dalam rekaman opsi.	Tombol
EncryptConnection	Nilai logis yang menentukan apakah memerlukan koneksi terenkripsi ke sumber data. Nilai ini tersedia untuk semua Jenis Autentikasi, tetapi hanya diatur jika EncryptConnection ditentukan dalam definisi Sumber Data.	Semua

Sampel kode berikut mengakses kredensial saat ini untuk kunci API dan menggunakannya untuk mengisi header kustom (x-APIKey).

Contoh:

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

Menerapkan alur OAuth

Jenis autentikasi OAuth memungkinkan ekstensi untuk menerapkan logika kustom untuk layanan mereka. Untuk melakukan ini, ekstensi menyediakan fungsi untuk StartLogin (mengembalikan URI otorisasi untuk memulai alur OAuth) dan FinishLogin (bertukar kode otorisasi untuk token akses). Ekstensi dapat secara opsional menerapkan Refresh (bertukar token refresh untuk token akses baru) dan Logout (kedaluwarsa refresh saat ini dan token akses) juga.

Catatan

Ekstensi Power Query dievaluasi dalam aplikasi yang berjalan pada komputer klien. Konektor Data tidak boleh menggunakan rahasia rahasia dalam alur OAuth mereka, karena pengguna dapat memeriksa ekstensi atau lalu lintas jaringan untuk mempelajari rahasia tersebut. Buka Proof Key for Code Exchange oleh OAuth Public Clients RFC (juga dikenal sebagai PKCE) untuk detail lebih lanjut tentang menyediakan alur yang tidak bergantung pada rahasia bersama. Contoh implementasi alur ini dapat ditemukan di situs GitHub kami.

Ada dua set tanda tangan fungsi OAuth: tanda tangan asli yang berisi jumlah parameter minimal, dan tanda tangan lanjutan yang menerima lebih banyak parameter. Sebagian besar alur OAuth dapat diimplementasikan menggunakan tanda tangan asli. Anda juga dapat mencampur dan mencocokkan jenis tanda tangan dalam implementasi Anda. Panggilan fungsi cocok berdasarkan jumlah parameter (dan jenisnya). Nama parameter tidak dipertimbangkan.

Buka sampel GitHub untuk detail selengkapnya.

Tanda tangan OAuth asli

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

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

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

Logout = (accessToken) => ...;

Tanda tangan OAuth tingkat lanjut

Catatan tentang tanda tangan tingkat lanjut:

Semua tanda tangan menerima clientApplication nilai rekaman, yang dicadangkan untuk digunakan di masa mendatang.
Semua tanda tangan menerima dataSourcePath (juga disebut sebagai resourceUrl dalam sebagian besar sampel).
Fungsi Refresh menerima oldCredential parameter, yang sebelumnya record dikembalikan oleh fungsi Anda FinishLogin (atau panggilan sebelumnya ke Refresh).

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

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

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

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

Autentikasi ID Microsoft Entra

Jenis Aad autentikasi adalah versi khusus OAuth untuk ID Microsoft Entra. Ini menggunakan klien ID Microsoft Entra yang sama dengan konektor Power Query bawaan yang mendukung autentikasi akun organisasi. Informasi selengkapnya dapat ditemukan di panduan mulai cepat Mengonfigurasi Microsoft Entra untuk konektor kustom.

Catatan

Jika Anda menerapkan alur OAuth Anda sendiri untuk ID Microsoft Entra, pengguna yang telah mengaktifkan Akses Bersyar untuk penyewa mereka mungkin mengalami masalah saat melakukan refresh menggunakan layanan Power BI. Ini tidak akan memengaruhi refresh berbasis gateway, tetapi akan berdampak pada konektor bersertifikat yang mendukung refresh dari layanan Power BI. Pengguna mungkin mengalami masalah yang berasal dari konektor menggunakan aplikasi klien publik saat mengonfigurasi kredensial berbasis web melalui layanan Power BI. Token akses yang dihasilkan oleh alur ini pada akhirnya akan digunakan pada komputer yang berbeda (yaitu, layanan Power BI di pusat data Azure, bukan di jaringan perusahaan) daripada yang digunakan untuk mengautentikasi awalnya (yaitu, komputer pengguna yang mengonfigurasi kredensial sumber data di jaringan perusahaan). Jenis bawaan Aad mengatasi masalah ini dengan menggunakan klien ID Microsoft Entra yang berbeda saat mengonfigurasi kredensial di layanan Power BI. Opsi ini tidak akan tersedia untuk konektor yang menggunakan OAuth jenis autentikasi.

Sebagian besar konektor perlu menyediakan nilai untuk AuthorizationUri bidang dan Resource . Kedua bidang dapat berupa text nilai, atau fungsi argumen tunggal yang mengembalikan 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)

Konektor yang menggunakan pengidentifikasi berbasis Uri tidak perlu memberikan Resource nilai. Secara default, nilainya sama dengan jalur akar parameter Uri konektor. Jika sumber daya ID Microsoft Entra sumber data berbeda dari nilai domain (misalnya, sumber daya menggunakan GUID), nilai Resource perlu disediakan.

Sampel jenis autentikasi Aad

Dalam kasus berikut, sumber data mendukung ID Microsoft Entra cloud global menggunakan penyewa umum (tidak ada dukungan Azure B2B). Meminta cakupan .default mengembalikan token dengan semua cakupan yang diotorisasi sebelumnya untuk ID aplikasi klien Power Query.

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

Dalam kasus berikut, sumber data mendukung penemuan penyewa berdasarkan OpenID Connect (OIDC) atau protokol serupa. Kemampuan ini memungkinkan konektor untuk menentukan titik akhir ID Microsoft Entra yang benar untuk digunakan berdasarkan satu atau beberapa parameter di jalur sumber data. Pendekatan penemuan dinamis ini memungkinkan konektor untuk mendukung 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"
    ]
]

Jenis autentikasi lainnya

Untuk informasi tentang jenis autentikasi lain yang tidak tercakup dalam artikel ini, seperti akses menyeluruh berbasis Kerberos, kunjungi artikel fungsionalitas konektor tambahan untuk mempelajari lebih lanjut.

Bagikan melalui