Rahasia dalam Katalog Unity

Important

Fitur ini ada di Pratinjau Umum.

Halaman ini menjelaskan cara membuat, membaca, mengatur, dan mengelola rahasia di Katalog Unity. Rahasia Katalog Unity adalah objek yang dapat diamankan yang menyimpan materi sensitif, seperti kata sandi, token, atau kunci API. Buku catatan dan pekerjaan Anda dapat mereferensikan rahasia tanpa mengekspos nilai dalam kode.

Rahasia Katalog Unity menggunakan namespace tiga tingkat (catalog.schema.secret) dan tersedia di seluruh ruang kerja yang dilampirkan ke metastore. Izin Unity Catalog mengatur hal tersebut. Ini memungkinkan Anda menerapkan model akses dan audit yang sama dengan yang Anda gunakan untuk aset data lain ke rahasia Anda.

Note

Rahasia Unity Catalog berbeda dari rahasia Azure Databricks tingkat ruang kerja, yang diatur ke dalam cakupan rahasia. Gunakan rahasia Katalog Unity saat Anda ingin mengatur rahasia dengan hak istimewa Katalog Unity dan mereferensikannya dengan namespace tiga tingkat.

Cara kerja rahasia Katalog Unity

Rahasia Katalog Unity adalah objek yang dapat diamankan di bawah skema, dengan nama catalog.schema.secretyang sepenuhnya memenuhi syarat . Seperti objek yang dapat diamankan Katalog Unity lainnya, rahasia mendukung warisan hak istimewa dari katalog dan skema. Untuk informasi selengkapnya tentang objek yang dapat diamankan dan pewarisan, lihat referensi objek yang dapat diamankan di Unity Catalog.

Anda dapat menggunakan rahasia Katalog Unity dengan cara berikut:

• Ambil nilai dalam kode. Dengan akses READ SECRET, pengguna dapat mengambil nilai rahasia dari notebook dan job menggunakan dbutils atau REST API Unity Catalog. Mereka kemudian dapat menggunakannya untuk mengautentikasi dengan sistem eksternal atau untuk mengenkripsi dan mendekripsi data.
• Referensikan nilai dari objek Katalog Unity. Objek Katalog Unity, seperti koneksi Katalog Unity, dapat mereferensikan rahasia berdasarkan nama sehingga integrasi dapat menggunakan rahasia tanpa memberi pengguna akses ke nilai . Bergantung pada objek, mereferensikan rahasia memerlukan REFERENCE SECRET atau READ SECRET.

Azure Databricks menyimpan nilai rahasia Katalog Unity yang dienkripsi dan menerapkan redaksi rahasia untuk mengurangi paparan yang tidak disengaja dalam output dan log. Untuk melakukan rotasi secret, perbarui nilainya secara berkala di UI atau melalui REST API Unity Catalog.

Hak istimewa untuk rahasia Katalog Unity

Hak istimewa berikut mengatur rahasia. Anda dapat memberikan izin tersebut pada level katalog, skema, atau secret individual, dan izin tersebut mengikuti pewarisan hak akses di Unity Catalog.

Hak istimewa	Description
CREATE SECRET	Memungkinkan pengguna membuat rahasia dalam skema. Diberikan pada tingkat katalog atau skema.
READ SECRET	Memungkinkan pengguna untuk mengambil nilai rahasia.
WRITE SECRET	Memungkinkan pengguna memperbarui nilai rahasia.
REFERENCE SECRET	Memungkinkan pengguna untuk merujuk ke rahasia, misalnya dari koneksi Unity Catalog, tanpa memiliki akses ke nilainya.

Untuk membuat rahasia dalam skema, pengguna harus memiliki USE CATALOG izin dan memiliki skema atau memiliki CREATE SECRET dan USE SCHEMA pada skema. Untuk mempelajari cara memberikan hak istimewa, lihat Mengelola hak istimewa di Katalog Unity.

Sebelum Anda mulai

Untuk menggunakan rahasia Unity Catalog, Anda harus memenuhi persyaratan berikut:

• Ruang kerja harus diaktifkan agar dapat menggunakan Katalog Unity. Untuk pengenalan, lihat Apa itu Katalog Unity?.
• Anda harus mengakses secret melalui komputasi yang mendukung Unity Catalog. Azure Databricks merekomendasikan salah satu hal berikut:
  • Pekerjaan dan buku catatan tanpa server menggunakan lingkungan versi 4 atau lebih tinggi.
  • Komputasi klasik dalam mode akses standar yang menjalankan Databricks Runtime 17.3 LTS atau lebih tinggi.
• Untuk mengambil rahasia dengan dbutils, komputasi harus menjalankan Databricks Runtime 17.3 LTS atau lebih tinggi, atau lingkungan tanpa server versi 4 atau lebih tinggi.

Buat rahasia

Untuk membuat rahasia, Anda harus memiliki izin USE CATALOG dan memiliki skema tersebut, atau memiliki CREATE SECRET dan USE SCHEMA pada skema tersebut. Lihat Hak Istimewa untuk rahasia Katalog Unity.

Eksplorer Katalog

1. Di ruang kerja Azure Databricks Anda, klik Katalog untuk membuka Catalog Explorer.
2. Buka skema tempat Anda ingin membuat rahasia.
3. Klik Buat > Rahasia.
4. Masukkan nama dan nilai. Secara opsional, tambahkan komentar dan tanggal kedaluwarsa. Jika rahasia kedaluwarsa, Catalog Explorer memperlihatkan peringatan.
5. Klik Buat.

REST API

Jalankan perintah cURL berikut menggunakan endpoint /api/2.1/unity-catalog/secrets:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_name": "main",
    "schema_name": "default",
    "name": "example_secret",
    "value": "your_secret_value",
    "comment": "your secret description"
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Baca rahasia

Untuk membaca nilai secret, Anda harus memiliki READ SECRET pada secret tersebut atau pada katalog atau skema induknya.

Utilitas Secrets (dbutils.secrets)

Azure Databricks merekomendasikan dbutils untuk membaca rahasia, karena menerapkan redaksi rahasia. Opsi ini memerlukan Databricks Runtime 17.3 LTS atau lebih tinggi, atau lingkungan tanpa server versi 4 atau lebih tinggi.

# Read a specific secret
my_secret = dbutils.secrets.get(catalog="main", schema="default", key="example_secret")

Untuk informasi selengkapnya, lihat Utilitas rahasia (dbutils.secrets).

REST API

Warning

Nilai rahasia yang diambil melalui REST API Unity Catalog tidak tunduk pada penyamaran rahasia, meskipun akses tetap dicatat dalam log audit. Azure Databricks merekomendasikan dbutils sebagai gantinya.

Untuk mendapatkan kembali nilainya, atur include_value=true dan baca kolom effective_value pada respons:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "include_value=true" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Mengelola izin pada rahasia

Berikan CREATE SECRET di tingkat katalog atau skema untuk mengontrol siapa yang dapat membuat rahasia. Berikan READ SECRET, , WRITE SECRETatau REFERENCE SECRET di katalog, skema, atau tingkat rahasia individual untuk mengontrol akses. Pewarisan hak istimewa berlaku. Untuk mempelajari selengkapnya tentang memberikan dan mencabut hak istimewa, lihat Mengelola hak istimewa di Katalog Unity.

Memberikan kemampuan untuk membuat rahasia

Eksplorer Katalog

1. Di Catalog Explorer, buka skema.

2. Klik tab Izin.

3. Klik pada Berikan.

4. Pilih prinsipal yang akan diberikan aksesnya, lalu pilih BUAT RAHASIA.

   Jika prinsipal tidak memiliki USE SCHEMA, peringatan akan meminta Anda untuk memberikannya. USE SCHEMA juga diperlukan untuk membuat rahasia dalam skema.

5. Klik tombol Konfirmasi.

SQL

GRANT CREATE SECRET, USE SCHEMA ON SCHEMA main.default TO `user@example.com`;

REST API

Jalankan perintah cURL berikut menggunakan endpoint /api/2.1/unity-catalog/permissions/schema/{schema_name}:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["CREATE_SECRET", "READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/schema/{schema_name}"

Memberikan akses ke rahasia

Eksplorer Katalog

1. Di Catalog Explorer, buka secret lalu klik secret tersebut.
2. Klik tab Izin.
3. Klik pada Berikan.
4. Pilih prinsipal dan hak istimewa yang akan diberikan, lalu klik Konfirmasi.

SQL

GRANT READ SECRET ON SECRET main.default.example_secret TO `user@example.com`;

REST API

Jalankan perintah cURL berikut menggunakan endpoint /api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [{
      "principal": "user@example.com",
      "add": ["READ_SECRET", "REFERENCE_SECRET", "WRITE_SECRET"]
    }]
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/permissions/secret/{catalog.schema.secret}"

Mencantumkan, memperbarui, dan menghapus rahasia

Cantumkan rahasia

Eksplorer Katalog

1. Di Catalog Explorer, buka skema.
2. Di panel Gambaran Umum , klik Rahasia untuk melihat semua rahasia dalam skema.

Utilitas Secrets (dbutils.secrets)

# List all secrets in a schema
all_secrets = dbutils.secrets.list(catalog="main", schema="default")

REST API

Permintaan daftar digunakan page_size untuk mengontrol jumlah hasil:

curl -G \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  --data-urlencode "catalog_name=main" \
  --data-urlencode "schema_name=default" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets"

Memperbarui rahasia

Untuk memperbarui nilai rahasia, Anda harus memiliki WRITE SECRET pada rahasia tersebut.

Eksplorer Katalog

1. Di Penjelajah Katalog, buka skema dan klik Rahasia di panel Gambaran Umum .
2. Klik rahasia untuk memperbarui.
3. Di sudut kanan atas, klik menu kebab (titik vertikal) dan pilih Edit.
4. Masukkan nilai baru atau tanggal kedaluwarsa, lalu klik Konfirmasi.

REST API

Permintaan pembaruan memerlukan update_mask parameter . Hanya kolom yang disertakan baik dalam update_mask maupun isi permintaan yang diperbarui:

curl -X PATCH \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "new_secret_value"}' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret?update_mask=*"

Hapus rahasia

Eksplorer Katalog

1. Di Penjelajah Katalog, buka skema dan klik Rahasia di panel Gambaran Umum .
2. Klik rahasia tersebut untuk menghapusnya.
3. Di sudut kanan atas, klik menu kebab (titik vertikal) dan pilih Hapus.
4. Masukkan nama lengkap rahasia, lalu klik Hapus.

REST API

curl -X DELETE \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/secrets/main.default.example_secret"

Mengaudit peristiwa untuk rahasia Katalog Unity

Tabel system.access.audit sistem merekam peristiwa yang terkait dengan rahasia Katalog Unity. Misalnya, untuk melihat semua peristiwa rahasia untuk pengguna pada tanggal tertentu, jalankan kueri berikut:

SELECT * FROM system.access.audit
WHERE
  user_identity.email = "user@example.com"
  AND event_date = "2026-02-20"
  AND service_name = "unityCatalog"
  AND action_name LIKE "%Secret%";

Untuk informasi selengkapnya tentang log audit, lihat Referensi tabel sistem log audit.

Mengenkripsi nilai rahasia dengan kunci yang dikelola pelanggan

Secara default, Azure Databricks mengenkripsi nilai rahasia dengan kunci yang dikelola Databricks. Sebagai gantinya, Anda dapat menggunakan kunci yang dikelola pelanggan (CMK). Jika Anda mengaktifkan fitur katalog terkelola yang dienkripsi CMK dan melampirkan konfigurasi CMK ke akun Anda, Azure Databricks menggunakan CMK untuk mengenkripsi nilai rahasia. Untuk informasi selengkapnya, lihat Kunci yang dikelola pelanggan untuk Unity Catalog.

Limitations

Rahasia Unity Catalog memiliki batasan berikut:

• Tidak ada gudang SQL. Rahasia Katalog Unity tidak didukung di gudang SQL. Mereka memerlukan Databricks Runtime 17.3 LTS atau lebih tinggi pada komputasi yang mendukung Katalog Unity, atau tanpa server.
• Tidak ada penemuan global. Rahasia Katalog Unity tidak muncul dalam pencarian global.
• Tidak ada dukungan izin BROWSE. BROWSE pada katalog tidak berlaku untuk rahasia Katalog Unity. Untuk membuat rahasia dapat ditemukan, berikan READ SECRET atau REFERENCE SECRET pada rahasia individu atau skemanya.
• Tidak ada skrip init. Anda tidak dapat menggunakan rahasia Katalog Unity dalam skrip init global atau kluster. Azure Databricks merekomendasikan penggunaan fitur khusus alih-alih skrip init jika memungkinkan.
• Tidak ada skema informasi. Tabel skema informasi untuk rahasia belum tersedia. Gunakan Catalog Explorer atau REST API untuk penemuan.
• dbutils cakupan runtime. dbutils pengambilan didukung pada notebook dan pekerjaan yang didukung Databricks Runtime. Konteks runtime selain Databricks Runtime, seperti pengembangan jarak jauh atau mode menjalankan JAR yang dikompilasi, tidak didukung.
• Cakupan OAuth API. API rahasia Unity Catalog hanya dapat diakses dengan unity-catalog cakupan OAuth API. Gunakan cakupan API secrets hanya untuk rahasia Azure Databricks tingkat ruang kerja.
• Batas kuota. Hingga 100 rahasia per skema dan 1.000 per metastore.