Pengaturan autentikasi untuk Driver Databricks JDBC

Artikel
10/11/2024

Artikel ini menjelaskan cara mengonfigurasi pengaturan autentikasi Azure Databricks untuk Driver Databricks JDBC.

Untuk mengonfigurasi koneksi Azure Databricks untuk Driver Databricks JDBC, Anda harus menggabungkan pengaturan sumber daya komputasi, pengaturan kemampuan driver apa pun, dan pengaturan autentikasi berikut, ke dalam URL koneksi JDBC atau kumpulan terprogram properti koneksi JDBC.

URL koneksi JDBC menggunakan format berikut:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>[;<setting1>=<value1>;<setting2>=<value2>;<settingN>=<valueN>]

Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.
Ganti <setting>=<value> sesuai kebutuhan untuk setiap properti koneksi seperti yang tercantum di bagian berikut.
Anda juga dapat menambahkan pengaturan kemampuan driver khusus atau tingkat lanjut.

Koleksi terprogram properti koneksi JDBC dapat digunakan dalam kode Java seperti contoh berikut:

package org.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class Main {
  public static void main(String[] args) throws Exception {
    Class.forName("com.databricks.client.jdbc.Driver");
    String url = "jdbc:databricks://" + System.getenv("DATABRICKS_SERVER_HOSTNAME") + ":443";
    Properties p = new java.util.Properties();
    p.put("httpPath", System.getenv("DATABRICKS_HTTP_PATH"));
    p.put("<setting1>", "<value1");
    p.put("<setting2>", "<value2");
    p.put("<settingN>", "<valueN");
    try (Connection conn = DriverManager.getConnection(url, p)) {
      Statement stmt = conn.createStatement();
      try (ResultSet rs = stmt.executeQuery("<query>")) {
        ResultSetMetaData md = rs.getMetaData();
        String[] columns = new String[md.getColumnCount()];
        for (int i = 0; i < columns.length; i++) {
          columns[i] = md.getColumnName(i + 1);
        }
        while (rs.next()) {
          System.out.print("Row " + rs.getRow() + "=[");
          for (int i = 0; i < columns.length; i++) {
            if (i != 0) {
              System.out.print(", ");
            }
            System.out.print(columns[i] + "='" + rs.getObject(i + 1) + "'");
          }
          System.out.println(")]");
        }
      }
    }
    System.exit(0);
  }
}

Atur DATABRICKS_SERVER_HOSTNAME nilai lingkungan dan DATABRICKS_HTTP_PATH ke nilai Server Hostname dan Jalur HTTP sumber daya komputasi Azure Databricks target. Untuk mendapatkan nilai-nilai ini, lihat Pengaturan komputasi untuk Driver Databricks JDBC. Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.
Ganti <setting> dan <value> sesuai kebutuhan untuk setiap properti koneksi seperti yang tercantum di bagian berikut.
Anda juga dapat menambahkan pengaturan kemampuan driver khusus atau tingkat lanjut, biasanya sebagai tambahan <setting> dan <value> pasangan.
Untuk contoh ini, ganti <query> dengan string kueri SQL SELECT .

Apakah Anda menggunakan URL koneksi atau kumpulan properti koneksi akan bergantung pada persyaratan aplikasi target, alat, klien, SDK, atau API Anda. Contoh URL koneksi JDBC dan koleksi terprogram properti koneksi JDBC disediakan dalam artikel ini untuk setiap jenis autentikasi Azure Databricks yang didukung.

Driver Databricks JDBC mendukung jenis autentikasi Azure Databricks berikut:

Token akses pribadi Azure Databricks
Token ID Microsoft Entra
Token OAuth 2.0
Autentikasi pengguna ke komputer (U2M) OAuth
Autentikasi mesin-ke-mesin (M2M) OAuth

Token akses pribadi Azure Databricks

Untuk membuat token akses pribadi Azure Databricks, lakukan hal berikut:

Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
Klik Pengembang.
Di samping Token akses, klik Kelola.
Klik Buat token baru.
(Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
Klik Buat.
Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.

Catatan

Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.

Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau topik berikut:

Untuk mengautentikasi menggunakan token akses pribadi Azure Databricks, atur konfigurasi berikut.

Untuk URL koneksi JDBC dengan properti konfigurasi umum yang disematkan dan properti kredensial sensitif:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>

Untuk kode Java dengan properti konfigurasi umum dan properti kredensial sensitif yang diatur di luar URL koneksi JDBC:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Untuk contoh kode Java lengkap yang dapat Anda sesuaikan cuplikan kode sebelumnya dengan kebutuhan Anda sendiri, lihat contoh kode di awal artikel ini.
Dalam URL atau kode Java sebelumnya, ganti <personal-access-token> dengan token akses pribadi Databricks untuk pengguna ruang kerja Anda.
Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.

Token ID Microsoft Entra

Driver ODBC dan JDBC 2.6.15 ke atas mendukung token ID Microsoft Entra untuk pengguna Azure Databricks atau perwakilan layanan ID Microsoft Entra.

Untuk membuat token akses ID Microsoft Entra, lakukan hal berikut:

Untuk pengguna Azure Databricks, Anda dapat menggunakan Azure CLI. Lihat Mendapatkan token ID Microsoft Entra untuk pengguna dengan menggunakan Azure CLI.
Untuk perwakilan layanan ID Microsoft Entra, lihat Mendapatkan token akses ID Microsoft Entra dengan Azure CLI. Untuk membuat perwakilan layanan terkelola ID Microsoft Entra, lihat Mengelola perwakilan layanan.

Token akses ID Microsoft Entra memiliki masa pakai default sekitar 1 jam. Token akses dapat disegarkan secara terprogram untuk sesi yang ada tanpa memutuskan koneksi dengan menjalankan kode di Refresh token akses ID Microsoft Entra. Untuk petunjuk tentang cara merefresh token, lihat bagian Configuring Authentication > Using OAuth 2.0 di Panduan Driver Databricks JDBC.

Untuk mengautentikasi menggunakan token ID Microsoft Entra, atur konfigurasi berikut.

Untuk URL koneksi JDBC dengan properti konfigurasi umum yang disematkan dan properti kredensial sensitif:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<microsoft-entra-id-token>

Untuk kode Java dengan properti konfigurasi umum dan properti kredensial sensitif yang diatur di luar URL koneksi JDBC:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<microsoft-entra-id-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Untuk contoh kode Java lengkap yang dapat Anda sesuaikan cuplikan kode sebelumnya dengan kebutuhan Anda sendiri, lihat contoh kode di awal artikel ini.
Dalam URL atau kode Java sebelumnya, ganti <microsoft-entra-id-token> dengan token ID Microsoft Entra.
Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.

Untuk informasi selengkapnya, lihat bagian Token Pass-through di Panduan Driver Databricks JDBC.

Token OAuth 2.0

Driver JDBC 2.6.36 ke atas mendukung token OAuth 2.0 untuk perwakilan layanan ID Microsoft Entra. Ini juga dikenal sebagai autentikasi pass-through token OAuth 2.0.

Untuk membuat token OAuth 2.0 untuk autentikasi pass-through token untuk perwakilan layanan MICROSOFT Entra ID, lihat Membuat dan menggunakan token akses secara manual untuk autentikasi M2M OAuth. Catat nilai OAuth access_token perwakilan layanan.
Untuk membuat perwakilan layanan terkelola ID Microsoft Entra, lihat Mengelola perwakilan layanan.

Penting

Driver JDBC 2.6.36 ke atas mendukung penggunaan rahasia OAuth Azure Databricks untuk membuat token OAuth 2.0. Rahasia ID Microsoft Entra tidak didukung.

Token OAuth 2.0 memiliki masa pakai default 1 jam. Untuk menghasilkan token OAuth 2.0 baru, ulangi proses ini.

Untuk mengautentikasi menggunakan autentikasi pass-through token OAuth 2.0, atur konfigurasi berikut.

Untuk URL koneksi JDBC dengan properti konfigurasi umum yang disematkan dan properti kredensial sensitif:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>

Untuk kode Java dengan properti konfigurasi umum dan properti kredensial sensitif yang diatur di luar URL koneksi JDBC:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Untuk contoh kode Java lengkap yang dapat Anda sesuaikan cuplikan kode sebelumnya dengan kebutuhan Anda sendiri, lihat contoh kode di awal artikel ini.
Dalam URL atau kode Java sebelumnya, ganti <oauth-token> dengan token OAuth Azure Databricks. (Token ID Microsoft Entra tidak didukung untuk autentikasi pass-through token OAuth 2.0.)
Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.

Untuk informasi selengkapnya, lihat bagian Token Pass-through di Panduan Driver Databricks JDBC.

Autentikasi pengguna ke komputer (U2M) OAuth

Driver JDBC 2.6.36 ke atas mendukung autentikasi pengguna-ke-mesin (U2M) OAuth untuk pengguna Azure Databricks. Ini juga dikenal sebagai autentikasi berbasis browser OAuth 2.0.

Autentikasi berbasis browser OAuth U2M atau OAuth 2.0 tidak memiliki prasyarat. Token OAuth 2.0 memiliki masa pakai default 1 jam. Autentikasi berbasis browser OAuth U2M atau OAuth 2.0 harus menyegarkan token OAuth 2.0 yang kedaluwarsa untuk Anda secara otomatis.

Catatan

Autentikasi berbasis browser OAuth U2M atau OAuth 2.0 hanya berfungsi dengan aplikasi yang berjalan secara lokal. Ini tidak berfungsi dengan aplikasi berbasis server atau berbasis cloud.

Untuk mengautentikasi menggunakan autentikasi berbasis browser OAuth user-to-machine (U2M) atau OAuth 2.0, atur konfigurasi berikut.

Untuk URL koneksi JDBC dengan properti konfigurasi umum yang disematkan dan properti kredensial sensitif:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0

Untuk kode Java dengan properti konfigurasi umum dan properti kredensial sensitif yang diatur di luar URL koneksi JDBC:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2")
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Untuk contoh kode Java lengkap yang dapat Anda sesuaikan cuplikan kode sebelumnya dengan kebutuhan Anda sendiri, lihat contoh kode di awal artikel ini.
Di URL atau kode Java sebelumnya, ganti <passphrase> dengan frasa sandi pilihan Anda. Driver menggunakan kunci ini untuk enkripsi token refresh.
Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.

Untuk informasi selengkapnya, lihat bagian Using Browser Based Authentication di Panduan Driver Databricks JDBC.

Autentikasi mesin-ke-mesin (M2M) OAuth

Driver JDBC 2.6.36 ke atas mendukung autentikasi mesin-ke-mesin (M2M) OAuth untuk perwakilan layanan ID Microsoft Entra. Ini juga dikenal sebagai autentikasi kredensial klien OAuth 2.0.

Catatan

JDBC 2.6.40.1071 menyelesaikan masalah dalam versi lama yang menyambungkan menggunakan M2M untuk ruang kerja tautan privat tidak didukung.

Untuk mengonfigurasi autentikasi kredensial klien OAuth M2M atau OAuth 2.0, lakukan hal berikut:

Buat perwakilan layanan terkelola ID Microsoft Entra lalu tetapkan ke akun dan ruang kerja Azure Databricks. Untuk melakukan ini, lihat Mengelola perwakilan layanan.

Penting

Driver JDBC 2.6.36 ke atas mendukung rahasia OAuth Azure Databricks untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0. Rahasia ID Microsoft Entra tidak didukung.
Buat rahasia OAuth Azure Databricks untuk perwakilan layanan. Untuk melakukan ini, lihat Membuat dan menggunakan token akses secara manual untuk autentikasi M2M OAuth.
Berikan akses perwakilan layanan ke kluster atau gudang Anda. Lihat Izin komputasi atau Mengelola gudang SQL.

Untuk mengautentikasi menggunakan autentikasi kredensial klien OAuth machine-to-machine (M2M) atau OAuth 2.0, atur konfigurasi berikut.

Untuk URL koneksi JDBC dengan properti konfigurasi umum yang disematkan dan properti kredensial sensitif:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>

Untuk kode Java dengan properti konfigurasi umum dan properti kredensial sensitif yang diatur di luar URL koneksi JDBC:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Untuk contoh kode Java lengkap yang dapat Anda sesuaikan cuplikan kode sebelumnya dengan kebutuhan Anda sendiri, lihat contoh kode di awal artikel ini.
Dalam URL atau kode Java sebelumnya, ganti tempat penampung berikut:
- Ganti <service-principal-application-id> dengan nilai ID Aplikasi (klien) perwakilan layanan.
- Ganti <service-principal-oauth-secret> dengan rahasia Azure Databricks OAuth perwakilan layanan. (Rahasia ID Microsoft Entra tidak didukung untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0.)
- Untuk mendapatkan nilai untuk <server-hostname> dan <http-path>, lihat Pengaturan komputasi untuk Driver Databricks JDBC.

Untuk informasi selengkapnya, lihat bagian Using M2M Based Authentication di Panduan Driver Databricks JDBC.

Bagikan melalui

Pengaturan autentikasi untuk Driver Databricks JDBC

Token akses pribadi Azure Databricks

Token ID Microsoft Entra

Token OAuth 2.0

Autentikasi pengguna ke komputer (U2M) OAuth

Autentikasi mesin-ke-mesin (M2M) OAuth

Saran dan Komentar

Sumber Daya Tambahan: