Mengonfigurasi otorisasi di aplikasi Databricks

Model otorisasi Aplikasi Databricks didasarkan pada OAuth 2.0 dan menggabungkan izin yang ditetapkan ke aplikasi dengan pengguna yang mengaksesnya. Karena aplikasi mengakses data dan layanan di dalam workspace, mereka harus menggunakan autentikasi dan otorisasi yang menegakkan kontrol akses data dan menghormati izin pengguna.

Untuk mendukung kerangka kerja ini, Databricks Apps menggunakan dua model identitas pelengkap:

• Otorisasi aplikasi memberi aplikasi identitasnya sendiri dengan serangkaian izin yang konsisten.
• Otorisasi pengguna memungkinkan aplikasi untuk menggunakan identitas dan izin pengguna yang berinteraksi dengannya.

Otorisasi aplikasi

Setiap aplikasi Azure Databricks memiliki perwakilan layanan service khusus yang bertindak sebagai identitasnya saat mengakses sumber daya Azure Databricks. Principal layanan ini unik untuk instans aplikasi dan tidak dapat digunakan kembali antar aplikasi. Anda tidak dapat mengubah perwakilan layanan yang ditetapkan ke aplikasi atau menentukan perwakilan layanan yang ada selama pembuatan aplikasi. Azure Databricks menggunakan identitas ini untuk mengevaluasi izin aplikasi secara independen dari pengguna mana pun, sehingga aplikasi hanya dapat mengakses sumber daya yang secara eksplisit diberikan kepadanya, bahkan di luar konteks interaksi pengguna.

Pemisahan ini menegakkan batasan keamanan antar aplikasi. Ini juga membuat aktivitas aplikasi dapat diaudit dan mendukung skenario seperti pemrosesan latar belakang atau tugas otomatis.

Prinsipal layanan diwakili oleh ID yang unik. Salin dari tab Otorisasi aplikasi:

Saat Anda membuat aplikasi, Azure Databricks secara otomatis memprovisikan perwakilan layanan khusus untuk aplikasi. Prinsipal layanan tetap sama di semua penyebaran aplikasi. Saat Anda menghapus aplikasi, Azure Databricks menghapus prinsipal layanan.

Gunakan principal layanan untuk tindakan yang dilakukan oleh aplikasi itu sendiri, tanpa memerlukan konteks pengguna individual. Kasus penggunaan umum meliputi:

• Menjalankan tugas latar belakang
• Membaca atau menulis konfigurasi atau metadata bersama
• Aktivitas pengelogan atau metrik penggunaan
• Memanggil layanan eksternal melalui titik akhir yang aman

Semua tindakan yang dimulai oleh aplikasi menggunakan izin perwakilan layanan. Berikan akses perwakilan layanan ke sumber daya tertentu menggunakan pengaturan izin standar. Namun, ini tidak mendukung kontrol akses tingkat pengguna. Semua pengguna yang berinteraksi dengan aplikasi memiliki izin yang sama yang ditentukan untuk principal layanan, yang mencegah aplikasi menerapkan kebijakan terperinci berdasarkan identitas pengguna individu.

Contoh berikut menunjukkan bagaimana aplikasi menggunakan perwakilan layanannya untuk mengkueri data di Unity Catalog:

Dalam hal ini, perwakilan layanan memerlukan akses eksplisit ke gudang SQL dan tabel Katalog Unity yang dikuerinya.

Model ini berfungsi dengan baik ketika Anda ingin semua pengguna aplikasi melihat data yang sama atau ketika aplikasi melakukan operasi bersama yang tidak terkait dengan kontrol akses khusus pengguna.

Ambil kredensial otorisasi aplikasi

Untuk otorisasi aplikasi, Azure Databricks secara otomatis menyuntikkan kredensial perwakilan layanan ke lingkungan aplikasi. Variabel lingkungan berikut menyimpan nilai klien OAuth yang diperlukan:

Variable	Description
DATABRICKS_CLIENT_ID	ID klien OAuth perwakilan layanan
DATABRICKS_CLIENT_SECRET	Rahasia klien OAuth perwakilan layanan

Azure Databricks mengatur variabel lingkungan secara otomatis dalam runtime aplikasi. Aplikasi ini menggunakan variabel ini saat mengautentikasi sebagai dirinya sendiri.

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

JavaScript

const clientId = process.env.DATABRICKS_CLIENT_ID;
const clientSecret = process.env.DATABRICKS_CLIENT_SECRET;

Note

Jika Anda menggunakan SDK Databricks, Anda biasanya tidak perlu mengakses variabel lingkungan ini secara manual. SDK mengikuti autentikasi terpadu dan secara otomatis mendeteksi kredensial di lingkungan.

Contoh: Kueri dengan otorisasi aplikasi

Python

Contoh ini menggunakan objek Konfigurasi SDK, yang menarik kredensial perwakilan layanan dari variabel lingkungan dan melakukan otorisasi OAuth.

from databricks import sql
from databricks.sdk.core import Config

cfg = Config()

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    credentials_provider=lambda: cfg.authenticate,
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

Contoh ini menggunakan variabel lingkungan untuk mengautentikasi dengan perwakilan layanan menggunakan OAuth dan menjalankan kueri dengan Driver SQL Databricks untuk Node.js.

import { DBSQLClient } from '@databricks/sql';

const client = new DBSQLClient();

const connection = await client.connect({
  authType: 'databricks-oauth',
  host: process.env.DATABRICKS_SERVER_HOSTNAME,
  path: process.env.DATABRICKS_HTTP_PATH,
  oauthClientId: process.env.DATABRICKS_CLIENT_ID,
  oauthClientSecret: process.env.DATABRICKS_CLIENT_SECRET,
});

const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
const cursor = await connection.cursor(query);

const rows = [];
for await (const row of cursor) {
  rows.push(row);
}

console.log(rows.slice(0, 5)); // Like df.head()

await connection.close();

Otorisasi pengguna

Otorisasi pengguna, terkadang disebut sebagai otorisasi atas nama pengguna, memungkinkan aplikasi Aplikasi Databricks bertindak dengan identitas pengguna aplikasi. Azure Databricks meneruskan token akses pengguna ke aplikasi, yang menggunakan token untuk mengakses sumber daya atas nama pengguna. Azure Databricks memberlakukan semua izin berdasarkan kebijakan Unity Catalog pengguna yang sudah ada.

Untuk mengelola risiko keamanan aplikasi yang bertindak atas nama pengguna, Azure Databricks menggunakan cakupan untuk membatasi tindakan apa yang dapat dilakukan aplikasi melalui otorisasi pengguna.

Terapkan otorisasi pengguna saat aplikasi perlu menghormati izin pengguna individual. Kasus penggunaan umum meliputi:

• Mengkueri tabel atau volume
• Mengakses gudang atau komputasi SQL
• Menjalankan pekerjaan atau alur kerja yang terkait dengan tindakan pengguna

Semua tindakan menggunakan izin Katalog Unity yang ada dari pengguna:

Otorisasi pengguna memungkinkan kontrol akses halus dengan menerapkan fitur Katalog Unity seperti filter tingkat baris dan masker kolom ke aktivitas aplikasi. Pendekatan ini menjaga kontrol akses tetap konsisten dengan tata kelola ruang kerja dan menghindari memasukkan logika izin secara langsung ke dalam aplikasi.

Izin akses terperinci dengan otorisasi pengguna

Saat Anda menambahkan otorisasi pengguna ke aplikasi, aplikasi memberlakukan izin Unity Catalog pengguna yang sudah ada, termasuk:

• Filter tingkat baris untuk membatasi baris yang terlihat
• Masker kolom untuk menyunting atau mengubah data sensitif

Karena Azure Databricks mengevaluasi permintaan otorisasi pengguna dengan identitas pengguna, kebijakan ini berlaku secara otomatis saat aplikasi mengakses data. Misalnya, jika tabel menyertakan filter baris yang membatasi visibilitas menurut wilayah, aplikasi hanya mengembalikan baris yang diizinkan untuk dikueri pengguna. Tidak diperlukan logika pemfilteran tambahan di aplikasi.

Pendekatan ini menghindari duplikasi logika kontrol akses dalam kode aplikasi dan memastikan konsistensi dengan tata kelola tingkat ruang kerja. Saat admin memperbarui kebijakan Katalog Unity, aplikasi secara otomatis menghormati perubahan tersebut.

Kontrol berbasis cakupan dan eskalasi hak istimewa

Aplikasi yang menggunakan otorisasi pengguna harus menyatakan cakupan otorisasi tertentu untuk membatasi apa yang dapat dilakukan aplikasi atas nama pengguna. Cakupan membatasi akses ke API atau jenis sumber daya tertentu, seperti:

• sql untuk mengkueri gudang SQL
• genie untuk mengelola Agen Genie Anda
• files untuk mengelola file dan direktori Anda

Jika Anda tidak memilih cakupan apa pun, Azure Databricks menetapkan set default yang memungkinkan aplikasi untuk mengambil informasi identitas pengguna dasar:

• iam.access-control:read
• iam.current-user:read

Default ini diperlukan untuk mendukung fungsionalitas otorisasi pengguna, tetapi tidak mengizinkan akses ke data atau sumber daya komputasi. Tambahkan cakupan tambahan saat Anda membuat atau mengedit aplikasi.

Ruang lingkup memberlakukan prinsip hak akses minimum. Pastikan untuk mengonfigurasi aplikasi untuk meminta hanya cakupan yang dibutuhkannya. Azure Databricks memblokir akses ke fungsionalitas apa pun di luar cakupan yang disetujui, bahkan jika pengguna memiliki izin. Misalnya, jika aplikasi hanya meminta cakupan sql, aplikasi tidak dapat mengakses titik akhir penyajian model, bahkan jika pengguna bisa mengaksesnya dari luar aplikasi.

Ketika pengguna pertama kali mengakses aplikasi, Azure Databricks meminta mereka memberikan izin kepada aplikasi untuk bertindak dalam setiap lingkup yang diminta. Setelah memberikan persetujuan, pengguna tidak dapat mencabutnya. Admin dapat secara opsional memberikan persetujuan atas nama pengguna untuk menyelaraskan akses dengan kebijakan organisasi.

Menambahkan cakupan ke aplikasi

Tambahkan cakupan otorisasi di Azure Databricks UI atau dengan Databricks CLI.

Antarmuka Pengguna

Konfigurasikan otorisasi pengguna saat Anda membuat atau mengedit aplikasi di antarmuka pengguna Azure Databricks.

Di bawah otorisasi Pengguna, klik +Tambahkan cakupan dan pilih cakupan yang menentukan API atau sumber daya Azure Databricks mana yang dapat diakses aplikasi atas nama pengguna. Azure Databricks memberlakukan cakupan ini pada runtime dan memerlukan persetujuan pengguna atau admin sebelum memberikan akses.

CLI

Pass user_api_scopes saat membuat atau memperbarui aplikasi:

databricks apps create <app-name> \
  --json '{
    "user_api_scopes": ["sql", "files"]
  }'

databricks apps create-update <app-name> \
  --json '{
    "update_mask": "user_api_scopes",
    "app": {
      "user_api_scopes": ["sql", "files"]
    }
  }'

Untuk contoh lengkapnya, lihat demo otorisasi Aplikasi Databricks pada GitHub. Contoh aplikasi menunjukkan cara menggunakan model otorisasi aplikasi dan pengguna, dan menyertakan instruksi penyiapan dan contoh kueri dengan otorisasi pengguna.

Cakupan yang didukung

Azure Databricks Apps mendukung cakupan API Azure Databricks berikut:

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (menjalankan kueri SQL baca-saja)

Azure Databricks Apps juga mendukung cakupan SDK berikut. Scope-scope ini dapat menggunakan pengubah :read untuk membatasi akses ke titik akhir GET.

• catalog.catalogs
• catalog.connections
• catalog.schemas
• catalog.tables
• workspace.workspace

Cakupan berikut sudah usang. Gunakan cakupan saat ini sebagai gantinya.

Ruang lingkup yang sudah tidak digunakan lagi	Ruang lingkup saat ini
dashboards.genie	genie
files.files	files
serving.serving-endpoints	model-serving
serving.serving-endpoints-data-plane	model-serving
sql.alerts	sql
sql.alerts-legacy	sql
sql.dashboards	sql
sql.data-sources	sql
sql.dbsql-permissions	sql
sql.queries	sql
sql.queries-legacy	sql
sql.query-history	sql
sql.statement-execution	sql
sql.warehouses	sql
vectorsearch.vector-search-endpoints	vector-search
vectorsearch.vector-search-indexes	vector-search

Membatasi cakupan otorisasi pengguna

Admin ruang kerja dapat mengontrol cakupan OAuth mana yang diizinkan untuk ditambahkan oleh pengembang aplikasi ke aplikasi di ruang kerja tersebut.

Antarmuka Pengguna

1. Klik nama pengguna Anda di bilah atas ruang kerja Azure Databricks dan pilih Settings.
2. Klik Pengembangan.
3. Di bawah Aplikasi, temukan setelan Batasi cakupan OAuth untuk aplikasi ke nilai yang dipilih dan konfigurasikan daftar yang diizinkan.
4. Refresh halaman agar perubahan diterapkan.

Nilai bawaan adalah All APIs, yang memungkinkan semua scope yang didukung. Memilih Tidak Ada menonaktifkan otorisasi pengguna.

CLI

Gunakan CLI Databricks untuk mendapatkan atau memperbarui daftar izin lingkup.

Untuk mendapatkan pengaturan saat ini:

databricks workspace-settings-v2 get-public-workspace-setting allowedAppsUserApiScopes

Untuk mengatur cakupan spesifik yang diizinkan:

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["sql", "files"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Untuk mengizinkan semua cakupan (default):

databricks workspace-settings-v2 patch-public-workspace-setting allowedAppsUserApiScopes \
  --json '{
    "allowed_apps_user_api_scopes": {
      "allowed_scopes": ["*"]
    },
    "name": "allowedAppsUserApiScopes"
  }'

Untuk menonaktifkan otorisasi pengguna, atur allowed_scopes ke array kosong ([]).

Admin akun dapat menambahkan cakupan ke aplikasi meskipun cakupan tersebut tidak berada dalam daftar izin ruang kerja.

Note

Aplikasi yang sudah berjalan terus berjalan dengan cakupan yang ada. Anda tidak dapat memulai, menyebarkan, atau memperbarui aplikasi hingga Anda menghapus cakupan yang tidak diizinkan.

Ambil kredensial otorisasi pengguna

Untuk otorisasi pengguna, Azure Databricks meneruskan identitas pengguna dan token akses ke aplikasi di header HTTP. Aplikasi harus mengekstrak header ini untuk bertindak atas nama pengguna.

Cara Anda mengambil header ini tergantung pada kerangka kerja yang Anda gunakan.

Streamlit

import streamlit as st
user_access_token = st.context.headers.get('x-forwarded-access-token')

Gradio

import gradio as gr

def query_fn(message, history, request: gr.Request):
    access_token = request.headers.get("x-forwarded-access-token")
    ...

Gradio secara otomatis menyuntikkan objek permintaan ke fungsi aplikasi Anda jika Anda mendeklarasikannya sebagai parameter. Anda tidak perlu membuat atau mengambil permintaan secara manual.

Dash dan Flask

from flask import request

headers = request.headers
user_token = headers.get('x-forwarded-access-token')

Shiny

user_token = session.http_conn.headers.get('x-forwarded-access-token')

Ekspres

import express from 'express';

const userAccessToken = req.header('x-forwarded-access-token');

Contoh: Kueri dengan otorisasi pengguna

Dalam hal ini, aplikasi meneruskan token akses pengguna langsung ke konektor, dan Azure Databricks menerapkan izin pengguna ke kueri.

Python

from databricks import sql
from databricks.sdk.core import Config
from flask import request

cfg = Config()
user_token = request.headers.get("x-forwarded-access-token")

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    access_token=user_token
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

JavaScript

import { DBSQLClient } from '@databricks/sql';
import express from 'express';

const app = express();

app.get('/', async (req, res) => {
  const userToken = req.header('x-forwarded-access-token');

  const client = new DBSQLClient();
  const connection = await client.connect({
    authType: 'access-token',
    host: process.env.DATABRICKS_SERVER_HOSTNAME,
    path: process.env.DATABRICKS_HTTP_PATH,
    token: userToken,
  });

  const query = 'SELECT * FROM main.sandbox.sales_customers LIMIT 1000';
  const cursor = await connection.cursor(query);

  const rows = [];
  for await (const row of cursor) {
    rows.push(row);
  }

  console.log(rows.slice(0, 5));
  await connection.close();

  res.send('Query complete');
});

app.listen(3000);

Praktik terbaik untuk otorisasi pengguna

Saat Anda membuat aplikasi yang melakukan tindakan atas nama pengguna, ikuti praktik terbaik ini untuk memastikan akses yang aman dan dapat diaudit:

• Simpan kode aplikasi di folder yang hanya dapat diakses oleh pemilik aplikasi atau sekumpulan kecil pengguna tepercaya.
• Berikan CAN MANAGE izin hanya kepada pengembang senior tepercaya yang bertanggung jawab atas pemeliharaan dan peninjauan aplikasi. Berikan CAN USE izin hanya kepada pengguna atau grup tertentu yang disetujui untuk menjalankan aplikasi.
• Jangan mencetak, mencatat, atau menulis token ke file. Ini berlaku untuk semua pernyataan pencatatan log, alat debugging, dan penanganan kesalahan. Misalnya, alih-alih print(f"User token: {token}") menggunakan headers = {"Authorization": f"Bearer {token}"}.
• Konfigurasikan setiap aplikasi untuk meminta hanya cakupan otorisasi minimum yang diperlukan untuk fungsionalitasnya.
• Selama peninjauan kode, verifikasi bahwa cakupan dan pengaturan izin selaras dengan persyaratan keamanan dan tidak memberikan akses yang tidak perlu.
• Terapkan tinjauan serekan untuk semua kode aplikasi sebelum menyebarkan ke lingkungan produksi.
• Catat log audit terstruktur untuk setiap tindakan yang dilakukan aplikasi Anda atas nama pengguna, termasuk identitas pengguna, jenis tindakan, sumber daya target, dan status.

Metode autentikasi

Untuk mendapatkan token untuk Aplikasi Databricks, pengguna dan perwakilan layanan mengautentikasi menggunakan alur OAuth 2.0 standar. Metode ini tergantung pada apakah pemanggil adalah pengguna atau beban kerja otomatis.

Untuk login ruang kerja (hanya pengguna):

• Akses menyeluruh (SSO): Pengguna mengautentikasi melalui penyedia identitas Anda saat akses menyeluruh (SSO) dikonfigurasi.
• Kata sandi satu kali (OTP): Pengguna menerima kata sandi sementara jika SSO tidak dikonfigurasi.

Untuk alur OAuth (aplikasi dan beban kerja):

• OAuth pengguna-ke-mesin (U2M): Pengguna mengautentikasi, dan token yang dihasilkan memungkinkan otorisasi pengguna sehingga aplikasi dapat bertindak atas nama pengguna.
• Mesin-ke-mesin (M2M) OAuth: Perwakilan layanan mengautentikasi menggunakan kredensial atau federasi klien. Token ini mendukung otorisasi aplikasi, di mana aplikasi bertindak sebagai dirinya sendiri alih-alih pengguna.

Untuk petunjuk memanggil aplikasi Databricks menggunakan autentikasi token, lihat Menyambungkan ke aplikasi API Databricks menggunakan autentikasi token.

Membandingkan dan menggabungkan model

Aplikasi Databricks dapat menggunakan otorisasi aplikasi dan pengguna secara independen atau bersama-sama. Model-model ini melayani tujuan yang berbeda dan dirancang untuk bekerja secara paralel.

Model otorisasi	Kapan harus menggunakan	Contoh kasus penggunaan
Otorisasi aplikasi	Saat aplikasi melakukan operasi yang tidak bergantung pada identitas pengguna	Menulis log, mengakses konfigurasi bersama, memanggil layanan eksternal
Otorisasi pengguna	Saat aplikasi perlu mengakses sumber daya dalam konteks pengguna saat ini	Mengkueri data Katalog Unity, meluncurkan komputasi, memberlakukan izin tingkat baris
Both	Saat aplikasi melakukan operasi bersama dan khusus pengguna	Mencatat metrik dengan identitas aplikasi, mengkueri data yang difilter dengan identitas pengguna