Настройка авторизации в приложении Databricks

Модель авторизации Databricks Apps основана на OAuth 2.0 и объединяет разрешения, назначенные приложению, с разрешениями пользователей, которые к нему обращаются. Поскольку приложения получают доступ к данным и сервисам внутри рабочего пространства, они должны использовать аутентификацию и авторизацию, которые обеспечивают контроль доступа к данным и уважают права пользователей.

Для поддержки этой платформы Databricks Apps использует две дополнительные модели удостоверений:

• Авторизация приложения предоставляет приложению собственное удостоверение с согласованным набором разрешений.
• Авторизация пользователя позволяет приложению использовать удостоверение и разрешения пользователя, взаимодействующего с ним.

Авторизация приложения

Каждое приложение Azure Databricks имеет выделенный основной служебный объект службы, который выступает в качестве удостоверения при доступе к ресурсам Azure Databricks. Этот служебный принципал является уникальным для экземпляра приложения и не может повторно использоваться для других приложений. Вы не можете изменить субъект-службу, назначенный приложению, или указать существующий субъект-службу во время создания приложения. Azure Databricks использует эту идентичность для оценки прав приложений независимо от любого пользователя, поэтому приложение может получать доступ только к ресурсам, явно предоставленным ему, даже вне контекста взаимодействия пользователя.

Это разделение устанавливает границы безопасности между приложениями. Это также делает активность приложений подлежащей аудиту и поддерживает такие сценарии, как обработка фона или автоматизированные задачи.

Субъект-служба представлен уникальным идентификатором. Скопируйте его содержимое из вкладки Авторизация в приложении.

При создании приложения Azure Databricks автоматически подготавливает выделенную учетную запись службы для приложения. Служебный принципал остается неизменным во всех развертываниях приложения. При удалении приложения Azure Databricks удаляет субъект-службу.

Используйте учетную запись службы для действий, которые приложение выполняет самостоятельно, не требуя пользовательского контекста. Распространенные варианты использования:

• Выполнение фоновых задач
• Чтение или запись общей конфигурации или метаданных
• Ведение журнала или метрики использования
• Вызов внешних служб через безопасные конечные точки

Все действия, инициированные приложением, используют разрешения субъекта-службы. Предоставьте служебному принципалу доступ к конкретным ресурсам путем стандартного назначения разрешений. Однако он не поддерживает управление доступом на уровне пользователя. Все пользователи, взаимодействующие с приложением, имеют одинаковые разрешения, определенные для представителя службы, что не позволяет приложению применять более детальные политики на основе отдельной идентификации пользователя.

В следующем примере показано, как приложение использует служебный принципал для запроса данных в Unity Catalog.

В этом случае субъект-служба нуждается в явном доступе как к хранилищу SQL, так и к таблице каталога Unity.

Эта модель хорошо работает, если все пользователи приложения будут видеть одни и те же данные или когда приложение выполняет общие операции, не привязанные к элементам управления доступом для определенных пользователей.

Получить учетные данные для авторизации приложения

Для авторизации приложения Azure Databricks автоматически внедряет учетные данные сервисного принципала в среду приложения. Следующие переменные среды содержат необходимые значения клиента OAuth:

Variable	Description
DATABRICKS_CLIENT_ID	Идентификатор клиента OAuth для сервис-принципала
DATABRICKS_CLIENT_SECRET	Секрет клиента OAuth субъекта-службы

Azure Databricks автоматически задает переменные среды в среде выполнения приложения. Приложение использует эти переменные, когда аутентифицируется от своего имени.

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

Если вы используете пакеты SDK Databricks, обычно вам не нужно вручную обращаться к этим переменным среды. Пакеты SDK следуют единой проверке подлинности и автоматически обнаруживают учетные данные в среде.

Пример: запрос с авторизацией приложения

Python

В этом примере используется объект конфигурации пакета SDK, который извлекает учетные данные субъекта-службы из переменных среды и выполняет авторизацию 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

В этом примере используются переменные среды для аутентификации с помощью учётной записи службы через OAuth и выполнения запроса с использованием SQL-драйвера Databricks для 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();

Авторизация пользователей

Авторизация пользователей, иногда называемая авторизацией от имени пользователя, позволяет приложению Databricks Apps действовать с удостоверением пользователя приложения. Azure Databricks пересылает маркер доступа пользователя в приложение, которое использует маркер для доступа к ресурсам от имени пользователя. Azure Databricks применяет все разрешения на основе существующих политик Unity Catalog.

Для управления рисками безопасности приложений, действующих от имени пользователя, Azure Databricks использует области, чтобы ограничить действия, которые может выполнять приложение с помощью авторизации пользователя.

Примените авторизацию пользователей, если приложению необходимо соблюдать отдельные разрешения пользователей. Типичные варианты использования:

• Выполнение запросов к таблицам или томам
• Доступ к хранилищам SQL или вычислительным ресурсам
• Выполнение заданий или рабочих процессов, привязанных к действиям пользователя

Все действия используют существующие разрешения каталога Unity пользователя:

Авторизация пользователей обеспечивает точное управление доступом, применяя функции каталога Unity, такие как фильтры на уровне строк и маски столбцов к действиям приложения. Этот подход обеспечивает согласованность управления доступом с управлением рабочими областями и позволяет избежать жесткой логики разрешений в приложении.

Гибко настраиваемые права доступа с авторизацией пользователей

При добавлении авторизации пользователя в приложение он применяет существующие разрешения каталога Unity пользователя, в том числе:

• Фильтры на уровне строк для ограничения видимых строк
• Маски столбцов для изменения или преобразования конфиденциальных данных

Так как Azure Databricks оценивает запросы авторизации пользователей с удостоверением пользователя, эти политики применяются автоматически при доступе к данным приложения. Например, если таблица содержит фильтр строк, ограничивающий видимость по регионам, приложение возвращает только строки, которые пользователь может запрашивать. В приложении не требуется дополнительная логика фильтрации.

Этот подход позволяет избежать дублирования логики управления доступом в коде приложения и обеспечения согласованности с управлением на уровне рабочей области. Когда администраторы обновляют политики каталога Unity, приложение автоматически учитывает эти изменения.

Безопасность на основе области и повышение привилегий

Приложения, использующие авторизацию пользователя, должны объявлять определенные области авторизации, чтобы ограничить возможности приложения от имени пользователя. Области ограничивают доступ к определенным API или типам ресурсов, например:

• sql для запросов к хранилищам SQL
• genie для управления вашим агентом Genie
• files для управления вашими файлами и каталогами

Если вы не выбираете области, Azure Databricks назначает набор по умолчанию, позволяющий приложению получать основные сведения об удостоверениях пользователя:

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

Эти значения по умолчанию необходимы для поддержки функций авторизации пользователей, но они не разрешают доступ к данным или вычислительным ресурсам. Добавьте дополнительные области при создании или изменении приложения.

Области доступа применяют принцип наименьшей привилегии. Обязательно настройте приложение, чтобы запросить только области, необходимые ему. Azure Databricks блокирует доступ к любым функциям за пределами утвержденных областей, даже если у пользователя есть разрешение. Например, если приложение запрашивает только sql сферу, оно не может получить доступ к конечным точкам обслуживания модели, даже если пользователь может сделать это за пределами приложения.

Когда пользователь впервые получает доступ к приложению, Azure Databricks просит предоставить приложению разрешение действовать в рамках каждого запрошенного диапазона. После предоставления согласия пользователи не могут отменить его. Администраторы могут предоставить согласие от имени пользователей для согласования доступа с политиками организации.

Добавление областей в приложение

Добавьте области авторизации в интерфейсе Azure Databricks или с помощью CLI Databricks.

Пользовательский интерфейс

Настройте авторизацию пользователей при создании или изменении приложения в пользовательском интерфейсе Azure Databricks.

В разделе авторизация пользователя щелкните +Добавить область и выберите области, определяющие, к каким API или ресурсам Azure Databricks приложение может получить доступ от имени пользователя. Azure Databricks применяет эти области во время выполнения и требует согласия пользователя или администратора перед предоставлением доступа.

CLI

Пропускайте user_api_scopes при создании или обновлении приложения:

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

Полный пример см. в демонстрации авторизации Databricks Apps на GitHub. В примере приложения показано, как использовать модели авторизации приложений и пользователей, а также инструкции по настройке и примеры запросов с авторизацией пользователя.

Поддерживаемые области

Azure Databricks Apps поддерживает следующие области API Azure Databricks:

• ai-gateway
• apps
• files
• genie
• model-serving
• postgres
• sql
• vector-search
• sql:restricted-query (выполнение SQL-запросов только для чтения)

Azure Databricks Apps также поддерживает следующие области SDK. Эти области действия могут использовать модификатор :read, чтобы ограничить доступ к конечным точкам GET.

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

Следующие области устарели. Используйте текущий телескоп вместо этого.

Устаревший объем действия	Текущая область
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

Ограничение областей авторизации пользователей

Администраторы рабочей области могут контролировать, какие области действия OAuth разработчикам приложений разрешено добавлять в приложения в рабочей области.

Пользовательский интерфейс

1. Кликните на своё имя пользователя в верхней панели рабочей области Azure Databricks и выберите параметры.
2. Щелкните "Разработка".
3. В разделе Приложения найдите параметр Ограничить области OAuth для приложений выбранными значениями и настройте список разрешённых значений.
4. Обновите страницу, чтобы изменения вступают в силу.

Значение по умолчанию — All API, что позволяет использовать все поддерживаемые области. При выборе "Нет" отключается авторизация пользователя.

CLI

Используйте CLI Databricks для получения или обновления списка разрешений на область действия.

Чтобы узнать текущие настройки:

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

Чтобы установить конкретные допустимые диапазоны:

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

Чтобы разрешить все области действия (по умолчанию):

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

Чтобы отключить авторизацию пользователя, установите allowed_scopes в пустой массив ([]).

Администраторы учетных записей могут добавлять области в приложения, даже если эти области не входят в список разрешений рабочей области.

Note

Уже запущенные приложения продолжают работу с существующими областями действия. Вы не можете запускать, развертывать или обновлять приложение, пока не удалите не разрешенные области.

Получить учетные данные авторизации пользователя

Для авторизации пользователя Azure Databricks пересылает удостоверение пользователя и маркер доступа в приложение в заголовках HTTP. Приложение должно извлечь эти заголовки, чтобы действовать от имени пользователя.

Получение этих заголовков зависит от используемого фреймворка.

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 автоматически внедряет объект запроса в функцию приложения при объявлении его в качестве параметра. Вам не нужно создавать или запрашивать запрос вручную.

Dash и 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')

Express

import express from 'express';

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

Пример: запрос с авторизацией пользователя

В этом случае приложение передает маркер доступа пользователя непосредственно соединителю, а Azure Databricks применяет разрешения пользователя к запросу.

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);

Лучшие практики авторизации пользователя

При создании приложений, выполняющих действия от имени пользователей, следуйте приведенным ниже рекомендациям, чтобы обеспечить безопасный и проверяемый доступ:

• Храните код приложения в папках, доступных только владельцу приложения или небольшому набору доверенных пользователей.
• Предоставьте CAN MANAGE разрешения только доверенным старшим разработчикам, которые отвечают за обслуживание и проверку приложений. Предоставьте CAN USE разрешения только определенным пользователям или группам, утвержденным для запуска приложения.
• Не печатайте, не ведите лог и не записывайте токены в файлы. Это относится ко всем операторам ведения журнала, средствам отладки и обработчикам ошибок. Например, вместо print(f"User token: {token}") используйте headers = {"Authorization": f"Bearer {token}"}.
• Настройте каждое приложение, чтобы запросить только минимальные необходимые области авторизации, необходимые для ее функциональных возможностей.
• Во время проверки кода убедитесь, что параметры области и разрешений соответствуют требованиям безопасности и не предоставляют ненужный доступ.
• Принудительное применение одноранговой проверки для всех кодов приложений перед развертыванием в рабочих средах.
• Записывайте структурированные журналы аудита для каждого действия, которое ваше приложение выполняет от имени пользователей, включая идентификацию пользователя, тип действия, целевой ресурс и статус.

Методы проверки подлинности

Чтобы получить токены для приложений Databricks, пользователи и служебные субъекты проходят аутентификацию с помощью стандартных потоков OAuth 2.0. Метод зависит от того, является ли вызывающий пользователь или автоматизированная рабочая нагрузка.

Для входа в рабочую область (только пользователи):

• Единый вход (SSO): Пользователи проходят проверку подлинности через поставщика идентификации при настройке единого входа (SSO).
• Одноразовый пароль (OTP): Пользователи получают временный пароль, если единый вход не настроен.

Для потоков OAuth (приложений и рабочих нагрузок):

• OAuth для взаимодействия пользователя с устройством (U2M): Пользователи проходят аутентификацию, а полученные токены обеспечивают авторизацию, чтобы приложение могло действовать от имени пользователя.
• OAuth на компьютере (M2M): Субъекты-службы проходят проверку подлинности с помощью учетных данных клиента или федерации. Эти токены лежат в основе авторизации приложения, где приложение действует как само по себе, а не как пользователь.

Инструкции по вызову приложения Databricks с использованием проверки подлинности токена, см. в разделе «Подключение к приложению API Databricks с использованием проверки подлинности токена».

Сравнение и объединение моделей

Приложения Databricks могут использовать авторизацию приложений и пользователей независимо или вместе. Эти модели служат различным целям и предназначены для параллельной работы.

Модель авторизации	Когда следует использовать	Примеры вариантов использования
Авторизация приложения	Когда приложение выполняет операции, которые не зависят от удостоверения пользователя	Запись журналов, доступ к общей конфигурации, вызов внешних служб
Авторизация пользователей	Когда приложению необходимо получить доступ к ресурсам в контексте текущего пользователя	Запрос данных каталога Unity, запуск вычислений, применение разрешений на уровне строк
Both	Когда приложение выполняет как общие, так и пользовательские операции	Запись метрик с помощью идентификатора приложения и запрос отфильтрованных данных с помощью идентификатора пользователя