AI 에이전트는 작업을 완료하기 위해 다른 리소스에 인증해야 하는 경우가 많습니다. 예를 들어 배포된 에이전트는 구조화되지 않은 데이터, 기본 모델을 호출하는 서비스 엔드포인트 또는 사용자 지정 논리를 실행하는 Unity 카탈로그 함수를 쿼리하기 위해 Vector Search 인덱스에 액세스해야 할 수 있습니다.
이 페이지에서는 Databricks Apps에 배포된 에이전트에 대한 인증 방법을 설명합니다. 모델 서비스 엔드포인트에 배포된 에이전트는 AI 에이전트에 대한 인증(모델 서비스)을 참조하세요.
Databricks 앱은 에이전트에 대해 두 가지 인증 방법을 제공합니다. 각 메서드는 다음과 같은 다양한 사용 사례를 제공합니다.
| 메서드 | Description | 사용 시기 |
|---|---|---|
| 앱 권한 부여 | 에이전트는 일관된 사용 권한으로 자동으로 생성된 서비스 주체를 사용하여 인증합니다. 이전에 서비스 주체 인증이라고 했습니다. | 가장 일반적인 사용 사례입니다. 모든 사용자가 리소스에 대해 동일한 액세스 권한을 가져야 하는 경우에 사용합니다. |
| 사용자 권한 부여 | 에이전트는 요청을 만드는 사용자의 ID를 사용하여 인증합니다. 이전에 OBO(On-Behalf-Of) 인증이라고 했습니다. | Unity 카탈로그를 사용하여 사용자별 권한, 감사 내역 또는 세분화된 액세스 제어가 필요한 경우에 사용합니다. |
두 메서드를 단일 에이전트로 결합할 수 있습니다. 예를 들어, 사용자별 테이블을 쿼리할 때에는 사용자 권한 부여를 사용하고, 공유 Vector Search 인덱스에 액세스할 때에는 앱 권한 부여를 사용합니다.
작업 영역 UI 또는 선언적 자동화 번들을 사용하여 인증 구성
다음 두 가지 방법으로 모든 인증 설정을 구성할 수 있습니다.
- 작업 영역 UI: 구성 단계에서 앱을 편집하고 리소스 및 범위를 관리합니다. 작업 공간에서 단일 앱을 개발하거나 수정할 때 권장됩니다.
-
선언적 자동화 번들:
databricks.yml파일에서 리소스, 범위 및 환경 변수를 선언하고databricks bundle deploy으로 배포합니다. Git 기반 버전 관리, CI/CD를 사용하거나 작업 영역에서 동일한 에이전트를 제공하려는 경우에 권장됩니다. 모든 에이전트 템플릿은databricks.yml과 함께 제공됩니다.
두 경로 모두 동일한 런타임 구성을 생성합니다. 이 페이지의 나머지 부분에는 각 지침을 두 가지 형식으로 모두 표시하므로, 하나를 선택하여 프로젝트 내에서 일관성을 유지할 수 있습니다.
두 경로를 통해 앱에 리소스를 추가하려면 리소스와 앱 모두에 대한 권한이 있어야 합니다 Can Manage .
전체 번들 참조는 앱 리소스 및 app.resources를 참조하세요. 엔드투엔드 번들 안내는 선언적 자동화 번들로 Databricks 앱 관리하기를 참조하세요.
앱 권한 부여
기본적으로 Databricks 앱은 앱 권한 부여를 사용하여 인증합니다. Databricks는 앱을 만들 때 자동으로 서비스 주체를 만들고 앱의 ID 역할을 합니다.
앱과 상호 작용하는 모든 사용자는 서비스 주체에 대해 정의된 것과 동일한 권한을 공유합니다. 이 모델은 모든 사용자가 동일한 데이터를 보도록 하거나 앱이 사용자별 액세스 제어에 연결되지 않은 공유 작업을 수행할 때 잘 작동합니다.
앱 권한 부여에 대한 자세한 내용은 앱 권한 부여를 참조하세요.
MLflow 실험에 사용 권한 부여
에이전트는 추적 및 평가 결과를 기록하기 위해 MLflow 실험에 액세스해야 합니다. 실험에 대한 서비스 주체 Can Edit 권한을 부여합니다.
작업 영역 UI
- 앱 홈페이지에서 편집 을 클릭합니다.
- 구성 단계로 이동합니다.
-
앱 리소스 섹션에서 사용 권한이 있는 MLflow 실험 리소스를
Can Edit추가합니다.
Databricks 앱에 MLflow 실험 리소스 추가를 참조하세요.
선언적 자동화 번들
앱의
resourcesdatabricks.yml목록 아래에 실험을 선언합니다.name리소스에 할당한 내용은 나중에 환경 변수를 연결할 때 참조됩니다.resources: apps: my_agent: name: 'my-agent' source_code_path: ./ resources: - name: 'experiment' experiment: experiment_id: '<experiment-id>' permission: 'CAN_EDIT'번들을 다시 배포합니다.
databricks bundle deploy databricks bundle run my_agent
모든 필드에 대한 app.resources.experiment 을 참조하세요.
다른 Databricks 리소스에 사용 권한 부여
에이전트가 Genie Spaces, Vector Search 인덱스 또는 SQL 웨어하우스와 같은 다른 Databricks 리소스를 사용하는 경우 각 리소스에 대한 서비스 주체 권한을 부여합니다.
프롬프트 레지스트리에 액세스하려면 프롬프트를 저장하기 위해 Unity 카탈로그 스키마에 CREATE FUNCTION, EXECUTE, 및 MANAGE 권한을 부여합니다.
Unity 카탈로그 리소스에 대한 액세스 권한을 부여할 때 모든 다운스트림 종속 리소스에 대한 사용 권한도 부여해야 합니다. 예를 들어 Genie Space에 대한 액세스 권한을 부여하는 경우 기본 테이블, SQL 웨어하우스 및 Unity 카탈로그 함수에 대한 액세스 권한도 부여해야 합니다.
작업 영역 UI
Databricks 작업 영역에서 앱을 만들거나 편집할 때 앱 리소스 섹션을 통해 앱에 리소스를 추가합니다.
- 앱 홈페이지에서 편집 을 클릭합니다.
- 구성 단계로 이동합니다.
- 앱 리소스에서 에이전트가 사용하는 각 리소스에 대해 + 리소스 추가를 클릭하고 사용 권한을 설정합니다.
지원되는 리소스 및 스크린샷의 전체 목록은 Databricks 앱 에 리소스 추가를 참조하세요.
선언적 자동화 번들
앱 내의
resources에서 에이전트가 사용하는 모든 리소스를databricks.yml에 선언하십시오. 아래 예제에서는 MLflow 실험, 서비스 엔드포인트, 지니 공간, SQL 웨어하우스, 벡터 검색 인덱스, Unity 카탈로그 함수 및 Lakebase 인스턴스를 사용하는 에이전트를 보여 줍니다. 각 리소스name는config.envvalue_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로 확정됩니다.번들을 배포하고 시작합니다.
databricks bundle validate databricks bundle deploy databricks bundle run my_agentbundle deploy는 원본을 업로드하고 리소스를 구성합니다.bundle run는 최신 원본을 사용하여 앱을 시작하거나 다시 시작합니다. 인수bundle run는 배포된 앱의 필드가 아니라 아래(여기resources.apps)의 YAML 키my_agent입니다name.
모든 리소스 하위 형식의 전체 스키마는 app.resources를 참조하세요.
다음 표에서는 위의 예제에 사용된 최소 사용 권한과 각 리소스 종류에 해당하는 선언적 자동화 번들 값을 나열합니다.
| 리소스 종류 | 워크스페이스 UI 권한 | 선언적 자동화 번들 리소스 및 권한 |
|---|---|---|
| SQL Warehouse | Can Use |
sql_warehouse와 CAN_USE |
| 모델 서비스 접속점 | Can Query |
serving_endpoint와 CAN_QUERY |
| Unity 카탈로그 함수 | Can Execute |
uc_securable와 함께 securable_type: FUNCTION 및 EXECUTE |
| 지니 공간 | 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 |
| 유니티 카탈로그 볼륨 |
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 |
최소 권한 원칙을 따릅니다. 서비스 주체에게 에이전트에 필요한 권한만 부여하고 앱당 전용 서비스 주체를 사용합니다. 전체 목록은 보안 모범 사례를 참조하세요.
사용자 권한 부여
중요합니다
사용자 권한 부여는 공개 미리 보기로 제공됩니다. 사용자 권한 부여를 사용하려면 먼저 작업 영역 관리자가 사용하도록 설정해야 합니다.
사용자 권한 부여를 사용하면 에이전트가 요청을 수행하는 사용자의 ID로 작업할 수 있습니다. 다음을 제공합니다.
- 중요한 데이터에 대한 사용자별 액세스
- Unity 카탈로그에 의해 적용되는 세분화된 데이터 컨트롤
- 사용자별 감사 내역
- 행 수준 필터 및 열 마스크 자동 강제 적용
에이전트가 앱의 서비스 주체 대신 요청 중인 사용자의 ID를 사용하여 리소스에 액세스해야 하는 경우 사용자 권한 부여를 사용합니다.
사용자 권한 부여의 작동 방식
에이전트에 대한 사용자 권한 부여를 구성하는 경우:
- 앱에 API 범위 추가: 앱이 사용자를 대신하여 액세스할 수 있는 Databricks API를 정의합니다. 앱에 범위 추가를 참조하세요.
- 사용자 자격 증명 범위가 축소됩니다. Databricks는 사용자의 자격 증명을 가져와서 정의한 API 범위로만 제한합니다.
- 토큰 전달: HTTP 헤더를 통해 앱에서 다운스코프 토큰을 사용할 수 있습니다.
- MLflow AgentServer 는 토큰을 저장합니다. 에이전트 서버는 에이전트 코드에서 편리한 액세스를 위해 요청당 이 토큰을 자동으로 저장합니다.
앱을 만들거나 편집할 때 Databricks Apps UI에 범위를 추가하거나 API를 사용하여 프로그래밍 방식으로 사용자 권한 부여를 구성합니다. 자세한 지침 은 앱에 범위 추가 를 참조하세요.
사용자 권한 부여를 사용하는 에이전트는 다음 Databricks 리소스에 액세스할 수 있습니다.
- SQL Warehouse
- 지니 공간
- 파일 및 디렉터리
- 엔드포인트를 제공하는 모델
- 벡터 검색 인덱스
- Unity 카탈로그 연결
- Unity 카탈로그 테이블
사용자 권한 부여 구현
사용자 권한 부여를 구현하려면 앱에 권한 부여 범위를 추가해야 합니다. 범위는 앱이 사용자를 대신하여 수행할 수 있는 작업을 제한합니다. 사용 가능한 범위 및 범위 의미 체계 목록은 범위 기반 보안 및 권한 에스컬레이션을 참조하세요.
작업 영역 UI
- Databricks UI에서 앱의 권한 부여 설정으로 이동합니다.
- 사용자 권한 부여에서 + 범위 추가를 클릭하고 앱이 사용자를 대신하여 리소스에 액세스하는 데 필요한 범위를 선택합니다.
- 변경 내용을 저장하고 앱을 다시 시작합니다.
선언적 자동화 번들
다음의 앱 리소스에서
user_api_scopes범위를 선언합니다.databricks.ymlresources: apps: my_agent: name: 'my-agent' source_code_path: ./ user_api_scopes: - sql - dashboards.genie - serving.serving-endpoints resources: - name: 'experiment' experiment: experiment_id: '<experiment-id>' permission: 'CAN_EDIT'번들을 다시 배포하고 앱을 다시 시작합니다.
databricks bundle deploy databricks bundle run my_agent메모
작업 영역에서 사용자 권한 부여를 처음으로 사용하도록 설정한 후에는 기존 앱을 다시 시작하여야 하며, 그 후에야 비로소 해당 앱들이 스코프를 사용할 수 있습니다. 앱에 범위 추가를 참조하세요.
에이전트 코드에서 사용자 권한 부여를 구성하려면 AgentServer에서 이 요청에 대한 헤더를 검색하고 해당 자격 증명을 사용하여 작업 영역 클라이언트를 생성합니다.
에이전트 코드에서 인증 유틸리티를 가져옵니다.
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캡처하고 해당 사용자 자격 증명을 사용하여 작업 영역 클라이언트를 생성하여 사용자, 앱 및 에이전트 서버 간의 인증을 처리합니다.앱 시작 시가 아니라 쿼리 시 작업 영역 클라이언트를 초기화합니다.
중요합니다
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)
범위를 추가하고 범위 기반 보안을 이해하는 방법에 대한 전체 가이드는 범위 기반 보안 및 권한 에스컬레이션을 참조하세요. 에이전트에 필요한 최소 범위만 요청하고 사용자를 대신하여 수행된 모든 작업을 기록합니다. 사용자 권한 부여에 대한 모범 사례를 참조하세요.
Databricks MCP 서버에 인증
Databricks에서 관리하는 MCP 서버는 URL https://<workspace>/api/2.0/mcp/vector-search/<catalog>/<schema> 및 https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema> 형식으로 벡터 검색 인덱스와 Unity 카탈로그 함수를 도구로 제공합니다. 사용 가능한 서버 및 해당 URL 패턴 목록은 Databricks 관리형 MCP 서버 사용을 참조하세요.
인증하려면 에이전트의 서비스 주체(또는 사용자 권한 부여를 사용하는 경우 사용자)에게 해당 스키마의 모든 다운스트림 리소스에 대한 액세스 권한을 부여합니다.
예를 들어 에이전트가 다음 MCP 서버 URL을 사용하는 경우:
https://<your-workspace>/api/2.0/mcp/vector-search/prod/customer_supporthttps://<your-workspace>/api/2.0/mcp/vector-search/prod/billinghttps://<your-workspace>/api/2.0/mcp/functions/prod/billing
prod.customer_support 및 prod.billing의 모든 벡터 검색 인덱스와 prod.billing의 모든 Unity 카탈로그 함수에 대한 액세스 권한을 부여해야 합니다.
작업 영역 UI
각 인덱스를 추가하고 앱 리소스 아래에 리소스로 작동합니다. 다른 Databricks 리소스에 권한 부여와 동일한 단계를 수행합니다.
선언적 자동화 번들
앱
uc_securable목록 아래에 인덱스 및 함수당 하나의resources항목을 추가합니다.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'번들을 다시 배포합니다.
databricks bundle deploy databricks bundle run my_agent
자체 Databricks 앱으로 호스트되는 사용자 지정 MCP 서버(접두사로 지정된 mcp-앱 이름)는 아직 번들 리소스로 지원되지 않습니다. 를 사용하여 MCP 서버 앱에서 에이전트의 서비스 주체 Can Use 에게 databricks apps update-permissions수동으로 권한을 부여합니다. 에이전트 템플릿 리포지토리에서 사용자 지정 mcp-server 기술을 참조하세요.