Проверка подлинности для агентов

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

На этой странице рассматриваются методы проверки подлинности для агентов, развернутых в приложениях Databricks. Сведения об агентах, развернутых в конечных точках обслуживания моделей, см. в разделе "Проверка подлинности" для агентов (обслуживание моделей).

Databricks Apps предоставляет два метода проверки подлинности для агентов. Каждый метод обслуживает различные варианты использования:

Метод Описание Когда использовать
Авторизация приложения Агент авторизуется с помощью автоматически созданного служебного принципала с согласованными разрешениями. Ранее называлась проверка подлинности основного объекта службы. Наиболее распространенный вариант использования. Используйте, когда у всех пользователей должен быть одинаковый доступ к ресурсам.
Авторизация пользователей Агент проверяет подлинность с помощью удостоверения пользователя, выполняющего запрос. Ранее именовалась On-Behalf-Of (OBO) аутентификация. Используйте, если вам нужны разрешения для конкретных пользователей, следы аудита или точное управление доступом с помощью каталога Unity.

Оба метода можно объединить в одном агенте. Например, используйте авторизацию приложения для доступа к общему индексу поиска ИИ при использовании авторизации пользователя для запроса таблиц, относящихся к пользователю.

Настройка проверки подлинности с помощью пользовательского интерфейса рабочей области или наборов декларативной автоматизации

Все параметры проверки подлинности можно настроить двумя способами:

  • Пользовательский интерфейс рабочей области: изменение приложения и управление ресурсами и областями на шаге "Настройка ". Рекомендуется выполнять итерацию в одном приложении в рабочей области.
  • Декларативные пакеты автоматизации: объявление ресурсов, областей и переменных среды в databricks.yml файле и развертывание с помощью databricks bundle deploy. Рекомендуется, если требуется управление версиями на основе Git, CI/CD или развертывание одного и того же агента в разных рабочих областях. Все шаблоны агентов поставляются с databricks.yml.

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

Чтобы добавить ресурс в приложение через любой путь, необходимо иметь Can Manage разрешение как на ресурс, так и на приложение.

Полный справочник по пакету см. в разделе "Ресурс приложения " и "app.resources". Пошаговое руководство по пакету см. в разделе "Управление приложениями Databricks с помощью декларативных пакетов автоматизации".

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

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

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

Подробные сведения об авторизации приложения см. в разделе "Авторизация приложений".

Предоставление разрешений эксперименту MLflow

Агенту требуется доступ к эксперименту MLflow для регистрации трассировок и результатов оценки. Предоставьте субъекту-службе Can Edit разрешение на эксперимент.

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

  1. Щелкните "Изменить" на домашней странице приложения.
  2. Перейдите к шагу "Настройка ".
  3. В разделе "Ресурсы приложения" добавьте ресурс эксперимента MLflow с разрешением Can Edit .

См. статью "Добавление ресурса эксперимента MLflow" в приложение Databricks.

Декларативные пакеты автоматизации

  1. Объявите эксперимент в resourcesсписке databricks.yml приложения. Назначенное вами name ресурсу будет позже использоваться при настройке переменных среды.

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Повторное развертывание пакета:

    databricks bundle deploy
databricks bundle run my_agent

См. app.resources.experiment для всех полей.

Предоставление разрешений другим ресурсам Databricks

Если агент использует другие ресурсы Databricks, такие как агенты Genie, индексы поиска ИИ или хранилища SQL, предоставьте субъекту-службе разрешения для каждого из них.

Чтобы получить доступ к реестру запросов, предоставить CREATE FUNCTION, EXECUTE, и MANAGE разрешения на схему каталога Unity для хранения запросов.

При предоставлении доступа к ресурсам каталога Unity необходимо также предоставить разрешения всем подчиненным ресурсам. Например, если вы предоставляете доступ к агенту Genie, необходимо также предоставить доступ к своим базовым таблицам, хранилищам SQL и функциям каталога Unity.

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

Добавьте ресурсы в приложение с помощью раздела "Ресурсы приложений " при создании или изменении приложения в рабочей области Databricks.

  1. Щелкните "Изменить" на домашней странице приложения.
  2. Перейдите к шагу "Настройка ".
  3. В ресурсах приложения нажмите кнопку +Добавить ресурс для каждого ресурса, который агент использует и задает разрешение.

Полный список поддерживаемых ресурсов и снимков экрана см. в разделе Добавление ресурсов в приложение Databricks.

Декларативные пакеты автоматизации

  1. Объявите каждый ресурс, который агент использует, в списке resources под вашим приложением в databricks.yml. В приведенном ниже примере показан агент, использующий эксперимент MLflow, конечную точку обслуживания, агент Genie, хранилище SQL, индекс поиска ИИ, функцию каталога Unity и экземпляр Lakebase. Каждый ресурс name упоминается через config.env и value_from, чтобы агент получал разрешенный идентификатор во время выполнения.

    bundle:
  name: my_agent

resources:
  apps:
    my_agent:
      name: 'my-agent'
      description: 'Custom agent deployed on Databricks Apps'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
          - name: LAKEBASE_INSTANCE_NAME
            value_from: 'database'

      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

        - name: 'sales-genie'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

        - name: 'warehouse'
          sql_warehouse:
            id: '<warehouse-id>'
            permission: 'CAN_USE'

        - name: 'docs-index'
          uc_securable:
            securable_full_name: 'main.docs.chunks_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'lookup-function'
          uc_securable:
            securable_full_name: 'main.tools.order_lookup'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

        - name: 'database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'databricks_postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

targets:
  dev:
    mode: development
    default: true

    Это важно

    Каждое значение value_from в config.env должно соответствовать полю name в списке resources. Несоответствия сводят к None значение переменной среды в развернутом приложении.

  2. Разверните и запустите пакет:

    databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent

    bundle deploy отправляет источник и настраивает ресурсы. bundle run запускает или перезапускает приложение с помощью последнего источника. Аргументом bundle run является ключ YAML под resources.apps (в данном случае my_agent), а не поле name развернутого приложения.

Полную схему каждого подтипа ресурсов см. в разделе app.resources.

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

Тип ресурса Разрешение пользовательского интерфейса рабочего пространства Декларативные пакеты автоматизации: ресурсы и разрешения
Хранилище SQL Can Use sql_warehouse с CAN_USE
Конечная точка обслуживания модели Can Query serving_endpoint с CAN_QUERY
Функция каталога Unity Can Execute uc_securable с securable_type: FUNCTION и EXECUTE
Агент Genie Can Run genie_space с CAN_RUN
Индекс поиска ИИ Can Select uc_securable с securable_type: TABLE и SELECT
Таблица каталога Unity SELECT uc_securable с securable_type: TABLE и SELECT
Подключение каталога Unity Use Connection uc_securable с securable_type: CONNECTION и USE_CONNECTION
Том каталога Unity Can Read или Can Read and Write uc_securable с securable_type: VOLUME и READ_VOLUME или WRITE_VOLUME
Lakebase (подготовлено) Can Connect and Create database с CAN_CONNECT_AND_CREATE
Lakebase (автомасштабирование) Can Connect and Create postgres с CAN_CONNECT_AND_CREATE

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

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

Это важно

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

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

  • Доступ к конфиденциальным данным на пользователя
  • Тонкозернистый контроль данных, реализуемый Unity Catalog
  • Следы аудита для конкретного пользователя
  • Автоматическое применение фильтров на уровне строк и маски столбцов

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

Как работает авторизация пользователей

При настройке авторизации пользователя для агента:

  1. Добавьте области API в приложение: определите, какие API Databricks приложение может получить доступ от имени пользователей. См. статью "Добавление областей в приложение".
  2. Учетные данные пользователя ограничены: Databricks принимает учетные данные пользователя и ограничивает их только определенными областями API.
  3. Перенаправление токенов: суженный токен становится доступным вашему приложению через x-forwarded-access-token заголовок HTTP.
  4. MLflow AgentServer сохраняет маркер: сервер агента автоматически сохраняет этот маркер на запрос для удобного доступа в коде агента.

Настройте авторизацию пользователя, добавив области в пользовательский интерфейс Databricks Apps при создании или редактировании приложения или программно с помощью API. Подробные инструкции см. в статье "Добавление областей в приложение".

Агенты с авторизацией пользователя могут получить доступ к следующим ресурсам Databricks:

  • Хранилище SQL
  • Агент Genie
  • Файлы и каталоги
  • Конечная точка обслуживания модели
  • Индекс поиска ИИ
  • Подключения каталога Unity
  • Таблицы каталога Unity

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

Чтобы реализовать авторизацию пользователя, необходимо добавить области авторизации в приложение. Области действия ограничивают возможности приложения от имени пользователя. Список доступных областей и семантики областей см. в разделе "Безопасность на основе областей" и "Эскалация привилегий".

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

  1. В пользовательском интерфейсе Databricks перейдите к параметрам авторизации приложения.
  2. В разделе "Авторизация пользователя" нажмите кнопку "+ Добавить область " и выберите области, необходимые приложению для доступа к ресурсам от имени пользователя.
  3. Сохраните изменения и перезапустите приложение.

Декларативные пакеты автоматизации

  1. Объявление областей в user_api_scopes ресурсе приложения в databricks.yml:

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      user_api_scopes:
        - sql
        - genie
        - model-serving
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Повторно разверните пакет и перезапустите приложение:

    databricks bundle deploy
databricks bundle run my_agent

    Note

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

Чтобы настроить авторизацию пользователя в коде агента, получите заголовок этого запроса из AgentServer и создайте клиент рабочей области с этими учетными данными.

  1. Импортируйте утилиту аутентификации в ваш код агента.

    При использовании одного из предоставленных шаблонов из databricks/app-templates импортируйте предоставленную программу:

    from databricks_app.utils import get_user_workspace_client

    В противном случае импортируйте из утилит сервера-агента:

    from agent_server.utils import get_user_workspace_client

    Функция get_user_workspace_client() использует сервер агента для записи x-forwarded-access-token заголовка и создания клиента рабочей области с этими учетными данными пользователя, обработки проверки подлинности между пользователем, приложением и сервером агента.

  2. Инициализировать клиент рабочей области во время запроса, а не во время запуска приложения:

    Это важно

    Вызов get_user_workspace_client() внутри invoke и stream обработчиков, а не в __init__ или при запуске приложения. Учетные данные пользователя доступны только во время запроса, когда пользователь выполняет запрос. Инициализация во время запуска приложения приведет к ошибке, так как контекст пользователя еще не существует.

    # In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Полное руководство по добавлению областей и пониманию безопасности на основе областей см. в разделе "Безопасность на основе областей " и "Повышение привилегий". Запрашивайте только минимальные области, необходимые агенту, и регистрируйте каждое действие, выполняемое от имени пользователя; См. рекомендации по авторизации пользователей.

Проверка авторизации пользователя

После добавления областей и вызова get_user_workspace_client()убедитесь, что агент запускается как вызывающий объект, а не субъект-служба приложения. Если перенаправленный маркер отсутствует, get_user_workspace_client() возвращается к субъекту-службе без вызова, поэтому агент может вернуть обычный ответ, выполняя все еще роль приложения. Чтобы проверить, добавьте инструмент whoami и вызовите его от своего имени. Если он возвращает имя пользователя, авторизация пользователя работает.

current_user.me() охватывается областью по умолчанию iam.current-user:read , поэтому вам не нужно добавлять области для этого теста.

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

Повторно разверните агент. См . статью "Создание агента" и его развертывание в Приложениях Databricks.

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

Тест пользовательского интерфейса рабочей области — самая быстрая базовая проверка и не требует токенов OAuth.

  1. Изменения области действия вступают в силу немедленно, но обновление внутренних кэшей может занять до 5 минут — подождите это время перед тестированием (перезапускать приложение не требуется). Всегда очищайте файлы cookie браузера для URL-адреса приложения (см. раскрывающийся список ниже для шагов), в противном случае сеанс повторно использует маркеры, выданные до изменения области.
  2. Убедитесь, что у вас есть CAN USE разрешение на приложение. См. настройку разрешений для приложения Databricks.
  3. Откройте URL-адрес приложения в браузере. При первом входе примите запрос на предоставление согласия для запрошенных областей доступа.
  4. В чате попросите Who am I? и подтвердите, что агент возвращает имя пользователя (например, you@your-company.com).
Очистка файлов cookie в Chrome
  1. Откройте devTools: нажмите клавишу F12 или Cmd+Option+I в macOS или CTRL+SHIFT+I в Windows или Linux.
  2. Откройте вкладку "Приложение ".
  3. В разделе Хранилище>Файлы cookie выберите URL-адрес приложения.
  4. Щелкните правой кнопкой мыши каждый файл cookie и выберите пункт "Удалить".

Chrome DevTools с вкладкой

Python

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

  1. Изменения области действия вступают в силу немедленно, но обновление внутренних кэшей может занять до 5 минут, поэтому подождите перед тестированием (перезапуск приложения не требуется).

  2. Вызовите агента от своего имени:

    from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

app_name = "<your-app-name>"
prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]

w = WorkspaceClient(profile="<your-profile>")
client = DatabricksOpenAI(workspace_client=w)
response = client.responses.create(model=f"apps/{app_name}", input=prompt)
print(response.output_text)

    Выходные данные должны быть вашим именем пользователя, например you@your-company.com.

Если инструмент возвращает UUID вместо имени пользователя, значит, x-forwarded-access-token заголовок не передаётся инструменту, и агент использовал в качестве резервного варианта субъект-службу приложения (UUID — это идентификатор клиента субъект-службы приложения). Чтобы диагностировать, подтвердите каждое из следующих действий:

  1. Авторизация пользователя включена в рабочей области.
  2. Для приложения настроены области действия.
  3. get_user_workspace_client() вызывается внутри обработчика @invoke или @stream не при запуске приложения.
  4. Код используется get_user_workspace_client() и не WorkspaceClient().

Несколько моментов, на которые стоит обратить внимание:

  • Удалите whoami инструмент перед выпуском в эксплуатацию. Это предназначено только для диагностики и раскрывает личность пользователя любому, кто может вызвать агента.
  • Тестирование со вторым пользователем. Проверка с одним пользователем подтверждает, что токен передаётся; вторая сторона, выполняющая вызов, подтверждает, что каждый запрос получает собственную идентичность, а не общую резервную идентичность.
  • Никогда не записывайте в журнал пересланный токен. Ознакомьтесь с рекомендациями по авторизации пользователей.
  • Чтобы проверить определенную область, замените current_user.me() вызовом, требующим этой области. Например, оператор SELECT current_user() к хранилищу задействует всю область sql от начала до конца.

Аутентификация на серверах Databricks MCP

Управляемые серверы MCP Databricks предоставляют индексы поиска ИИ и функции каталога Unity в качестве инструментов с помощью URL-адресов формы https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> и https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Префикс устаревшего /api/2.0/mcp/vector-search/ URL-адреса продолжает работать для обратной совместимости. Список доступных серверов и шаблоны их URL-адресов см. в разделе Управляемые серверы MCP в Azure Databricks.

Чтобы пройти проверку подлинности, предоставьте субъекту-службе агента (или пользователю, если используется авторизация пользователя) доступ к каждому нижестоящему ресурсу в этих схемах.

Например, если агент использует следующие URL-адреса сервера MCP:

  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/customer_support
  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/billing
  • https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Необходимо предоставить доступ ко всем индексам AI Search в prod.customer_support и prod.billing, а также ко всем функциям Unity Catalog в prod.billing.

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

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

Декларативные пакеты автоматизации

  1. Добавьте по одной записи для каждого индекса и каждой функции в список uc_securable вашего приложения:

    resources:
  apps:
    my_agent:
      resources:
        - name: 'support-index'
          uc_securable:
            securable_full_name: 'prod.customer_support.tickets_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'billing-index'
          uc_securable:
            securable_full_name: 'prod.billing.invoices_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'refund-function'
          uc_securable:
            securable_full_name: 'prod.billing.process_refund'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

  2. Повторное развертывание пакета:

    databricks bundle deploy
databricks bundle run my_agent

Пользовательские серверы MCP, размещенные в качестве собственных приложений Databricks (имена приложений с префиксом mcp-) пока не поддерживаются как составные ресурсы. Предоставьте учетной записи службы Can Use агента вручную на приложении сервера MCP с помощью databricks apps update-permissions. См. навык пользовательского mcp-server в репозитории шаблонов агентов.

Дальнейшие действия

  • Last updated on