Bagikan melalui

Menangani otentikasi

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 catatan dengan kolom tertentu. Tabel berikut mencantumkan bidang yang diharapkan untuk setiap jenis. Semua bidang diperlukan kecuali ditandai sebaliknya.

Jenis Autentikasi Bidang Description
Anonim Jenis autentikasi Anonim (juga disebut Implicit) tidak memiliki bidang apa pun.
OAuth MulaiLogin Fungsi yang menyediakan URL dan informasi status untuk memulai alur OAuth.

Buka bagian Menerapkan Alur OAuth .
SelesaikanLogin Fungsi yang mengekstrak access_token dan properti lain yang terkait dengan alur OAuth.
Muat Ulang (opsional) Fungsi yang mengambil token akses baru dari token refresh.
Keluar (opsional) Fungsi yang membatalkan token akses pengguna saat ini.
Etiket (opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.
Aad UriOtorisasi 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.
Ruang lingkup (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, cakupan user_impersonation 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.
Etiket (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.
Label Kata Sandi (opsional) Nilai teks untuk mengganti label default untuk kotak teks Kata Sandi pada antarmuka pengguna kredensial.
Etiket (opsional) Nilai teks yang memungkinkan Anda mengambil alih label default untuk AuthenticationKind ini.
Key KeyLabel (opsional) Nilai teks untuk mengganti label default untuk kotak teks Kunci API pada antarmuka pengguna kredensial.
Etiket (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.

Example:

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

Mengakses kredensial saat ini

Kredensial saat ini dapat diperoleh menggunakan fungsi Extension.CurrentCredential.

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 informasi kredensial di header khusus atau parameter string kueri (misalnya saat menggunakan autentikasi tipe 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 Description Digunakan Oleh
AuthenticationKind Berisi nama jenis autentikasi yang ditetapkan ke kredensial ini (UsernamePassword, OAuth, dan sebagainya). All
Nama pengguna Nilai nama pengguna NamaPenggunaKataSandi, Windows
Kata sandi Nilai kata sandi. Biasanya digunakan dengan UsernamePassword, tetapi juga diatur untuk Kunci. Kunci, Nama Pengguna dan Kata Sandi, Windows
access_token Nilai token akses OAuth. OAuth
Karakteristik 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
Key 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. Key
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 . All

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

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

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). Secara opsional, ekstensi dapat mengimplementasikan Refresh (menukar token penyegaran dengan token akses baru) dan Logout (mengakhiri masa berlaku kedua token penyegaran dan akses saat ini) juga.

Nota

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 dilakukan berdasarkan kecocokan 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 signature menerima nilai catatan clientApplication, yang dicadangkan untuk penggunaan di masa mendatang.
  • Semua tanda tangan menerima dataSourcePath (juga disebut sebagai resourceUrl dalam sebagian besar sampel).
  • Fungsi Refresh menerima parameter oldCredential, yang merupakan record sebelumnya yang dikembalikan oleh fungsi FinishLogin Anda (atau pemanggilan sebelumnya ke Refresh).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

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

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

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

Microsoft Entra ID otentikasi

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 .

Nota

Jika Anda menerapkan alur OAuth Anda sendiri untuk Microsoft Entra ID, pengguna yang telah mengaktifkan Conditional Access untuk tenant mereka mungkin mengalami masalah saat menyegarkan 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 bidang AuthorizationUri 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 = "44445555-eeee-6666-ffff-7777aaaa8888"   // 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 Microsoft Entra ID dari sumber data berbeda dari nilai domain (misalnya, menggunakan GUID), maka 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 akan mengembalikan token dengan semua cakupan yang sudah diotorisasi sebelumnya untuk ID aplikasi klien Power Query.

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

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.

  • Last updated on