Unity 카탈로그의 비밀

이 페이지에서는 Unity Catalog에서 보안 비밀을 생성하고, 읽고, 제어하고, 관리하는 방법을 설명합니다. Unity 카탈로그 비밀은 암호, 토큰 또는 API 키와 같은 중요한 자료를 저장하는 보안 개체입니다. 노트북과 작업은 코드에 값을 노출하지 않고도 비밀 정보를 참조할 수 있습니다.

Unity 카탈로그 비밀은 3단계 네임스페이스(catalog.schema.secret)를 사용하며 메타스토어에 연결된 작업 영역에서 사용할 수 있습니다. Unity 카탈로그 권한은 이를 제어합니다. 이렇게 하면 다른 데이터 자산에 사용하는 것과 동일한 액세스 모델 및 감사를 비밀에 적용할 수 있습니다.

메모

Unity 카탈로그 비밀은 비밀 범위로 구성된 작업 영역 수준 Azure Databricks 비밀과 다릅니다. Unity 카탈로그 권한으로 비밀을 제어하고 3단계 네임스페이스를 사용하여 참조하려는 경우 Unity 카탈로그 비밀을 사용합니다.

Unity 카탈로그 비밀 작동 방식

Unity 카탈로그 암호는 스키마 아래의 보안 개체이며 정규화된 이름을 catalog.schema.secret사용합니다. 다른 Unity 카탈로그 보안 개체와 마찬가지로 비밀은 카탈로그 및 스키마의 권한 상속을 지원합니다. 보안 개체 및 상속에 대한 자세한 내용은 Unity 카탈로그 보안 개체 참조를 참조하세요.

다음과 같은 방법으로 Unity 카탈로그 비밀을 사용할 수 있습니다.

코드에서 값을 검색합니다. READ SECRET 액세스 권한이 있으면 사용자는 dbutils 또는 Unity Catalog REST API를 사용해 노트북 및 작업에서 비밀 값을 검색할 수 있습니다. 그런 다음 이를 사용하여 외부 시스템으로 인증하거나 데이터를 암호화 및 암호 해독할 수 있습니다.
세션 범위가 설정된 Python이나 Scala UDF에서 값을 사용하세요. 세션 범위 UDF를 참조하세요.
Unity 카탈로그 Python UDF에서 값을 사용하세요. 스칼라 또는 배치 UDF는 자신의 SECRETS 절에 각 비밀을 선언합니다. Python UDF를 참고하세요.
Unity 카탈로그 Scala UDF에서 값을 사용하세요. 스칼라 UDF는 각 비밀을 절 SECRETS 내에서 선언합니다. Scala UDF를 참고하세요.

UDF 유형 전반에 걸친 요구사항과 권한 동작에 대해서는 UDF 요구사항 및 권한 항목을 참조하세요.

UDF는 Azure Databricks가 관리하는 비밀 또는 외부 비밀 관리자가 지원하는 비밀을 사용할 수 있습니다. Unity 카탈로그의 외부 비밀을 참조하세요.

UDF 요구사항 및 권한

요구사항과 권한 동작은 세션 범위와 Unity 카탈로그 UDF에 따라 다릅니다.

세션 범위의 UDF

세션 범위의 Python UDF는 databricks.secrets.get()로 시크릿을 가져오고, 세션 범위의 Scala UDF는 com.databricks.Secrets.get()로 시크릿을 가져옵니다. 비밀 접근은 발신자의 권한을 사용합니다.

비밀 접근을 위한 계산 요구사항은 UDF 언어에 따라 다릅니다:

서버리스 컴퓨트에서는 Python과 Scala UDF를 위해 노트북이나 작업 세션이 환경 버전 6 이상을 사용해야 합니다.
클래식 컴퓨트에서는 세션 범위 Python UDF를 사용하려면 표준 또는 전용 액세스 모드에서 Databricks Runtime 19 이상이 필요합니다.
클래식 컴퓨트에서는 세션 범위 Scala UDF를 사용하려면 표준 액세스 모드에서 Databricks Runtime 19 이상이 필요합니다.

Unity 카탈로그 UDF들

스칼라 및 배치 Unity Catalog Python UDF와 스칼라 Unity Catalog Scala UDF는 SECRETS 절에서 시크릿을 선언하며, 6을 명시적으로 environment_version 이상으로 설정해야 합니다. 서버리스 컴퓨트, 서버리스 SQL 웨어하우스, 그리고 표준 접근 모드와 함께 Databricks Runtime 19 이상을 실행하는 클래식 컴퓨트를 지원합니다.

프로 SQL 웨어하우스는 비밀을 사용하는 스칼라 및 배치 Unity 카탈로그 Python UDF를 지원합니다. Unity Catalog Scala UDF가 비밀을 사용하는 것은 프로 SQL 웨어하우스에서 지원되지 않습니다.

secret을 선언하는 UDF를 생성하거나 대체하려면, 해당 문을 실행하는 주체는 secret에 대한 USE CATALOG 권한과 상위 카탈로그 및 스키마에 대한 USE SCHEMA 및 READ SECRET 권한이 있어야 합니다. 런타임에 UDF는 현재 함수 소유자의 권한을 사용합니다. 호출자에게는 EXECUTE를 포함한 일반적인 함수 권한이 필요하지만, 선언된 시크릿에 직접 접근할 필요는 없습니다. 함수 소유자가 선언된 비밀을 읽을 권한을 잃으면 UDF가 실패합니다.

전용 컴퓨팅에서 열 마스크에 secret 지원 UDF를 사용하세요

SECRETS 절을 사용하는 Unity Catalog Python 또는 Scala UDF는 전용 액세스 모드 컴퓨팅에서 직접 호출할 수 없습니다. 하지만 Unity 카탈로그 SQL 함수를 만들어 비밀 활성화된 UDF를 호출하고, SQL 함수를 속성 기반 접근 제어(ABAC) 열 마스크로 사용할 수 있습니다. 쿼리가 전용 컴퓨트에서 실행될 때, Azure Databricks는 컬럼 마스크 강제를 서버 없는 컴퓨트에 위임합니다. 이 예외는 컬럼 마스크를 강제할 때만 적용되며; 전용 컴퓨팅에서 비밀 활성화된 UDF를 직접 호출할 수 있게 하지는 않습니다. 지원되지 않는 컴퓨팅 버전을 참조하세요.

Warning

비밀 값은 UDF 구현 내에서만 사용하세요. 비밀 값을 반환하거나 UDF 결과에 포함하지 마세요. 비밀 편집은 오류와 로그에서의 우발적 노출을 줄이지만, UDF 코드가 쿼리 결과에서 비밀 자료를 노출하는 것을 막지는 못합니다.

Azure Databricks 암호화된 Unity 카탈로그 비밀 값을 저장하고 비밀 수정을 적용하여 출력 및 로그의 실수로 인한 노출을 줄입니다. 비밀을 회전하려면 UI 또는 Unity 카탈로그 REST API를 사용하여 주기적으로 해당 값을 업데이트합니다.

Unity 카탈로그 비밀에 대한 권한

다음 권한은 비밀을 제어합니다. 카탈로그, 스키마 또는 개별 비밀 수준에서 부여할 수 있으며 Unity 카탈로그 권한 상속을 따릅니다.

특권	설명
`CREATE SECRET`	사용자가 스키마에서 비밀을 만들 수 있습니다. 카탈로그 또는 스키마 수준에서 부여됩니다.
`READ SECRET`	사용자가 비밀 값을 검색할 수 있습니다.
`WRITE SECRET`	사용자가 비밀 값을 업데이트할 수 있습니다.
`REFERENCE SECRET`	사용자가 값에 접근하지 않고도 비밀을 참조할 수 있게 합니다.

스키마에 비밀 정보를 생성하려면 사용자에게 USE CATALOG 권한이 있어야 하며, 해당 스키마를 소유하고 있거나 해당 스키마에 대해 CREATE SECRET 및 USE SCHEMA 권한이 있어야 합니다. 권한을 부여하는 방법을 알아보려면 Unity 카탈로그에서 권한 관리를 참조하세요.

Requirements

Unity 카탈로그 비밀을 사용하려면 다음 요구 사항을 충족해야 합니다.

작업 영역이 Unity 카탈로그에 대해 사용 가능하도록 설정되어야 합니다. 소개는 Unity 카탈로그란?을 참조하세요.
Unity Catalog가 활성화된 컴퓨팅에서 시크릿에 액세스해야 합니다. Azure Databricks 다음 중 하나를 권장합니다.
- 환경 버전 4 이상을 사용하는 서버리스 작업 및 노트북
- Databricks Runtime 17.3 LTS 이상을 실행하는 표준 액세스 모드 의 클래식 컴퓨팅입니다.
dbutils로 보안 비밀을 가져오려면 컴퓨팅 리소스는 Databricks Runtime 17.3 LTS 이상 또는 서버리스 환경 버전 4 이상에서 실행되어야 합니다.

비밀 만들기

비밀을 생성하려면 USE CATALOG 권한이 있고 스키마를 소유하고 있거나, 스키마에 대한 CREATE SECRET 및 USE SCHEMA 권한이 있어야 합니다. Unity 카탈로그 비밀에 대한 권한을 참조하세요.

카탈로그 탐색기

Azure Databricks 작업 영역에서 카탈로그를 클릭하여 카탈로그 탐색기를 엽니다.
비밀을 만들 스키마로 이동합니다.
비밀 만들기>를 클릭합니다.
이름과값을 입력합니다. 필요에 따라 메모 와 만료 날짜를 추가합니다. 비밀이 만료되면 카탈로그 탐색기에 경고가 표시됩니다.
만들기를 클릭합니다.

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /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"

비밀 읽기

비밀 값을 읽으려면 해당 비밀이나 상위 카탈로그 또는 스키마에 대해 READ SECRET 권한이 있어야 합니다.

비밀 관리 유틸리티(dbutils.secrets)

Azure Databricks는 비밀 값 마스킹이 적용되므로 비밀을 읽을 때 dbutils를 사용하는 것을 권장합니다. 이 옵션을 사용하려면 Databricks Runtime 17.3 LTS 이상 또는 서버리스 환경 버전 4 이상이 필요합니다.

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

자세한 내용은 비밀 유틸리티(dbutils.secrets)를 참조하세요.

REST API

Warning

Unity 카탈로그 REST API를 사용하여 검색된 비밀 값은 비밀 수정의 대상이 아니지만 감사 로그에 액세스가 기록됩니다. Azure Databricks 대신 권장합니다dbutils.

값을 반환하려면 응답에서 include_value=true 필드를 설정하고 effective_value 읽습니다.

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

코드에 비밀을 사용하세요

Unity 카탈로그 비밀 dbutils.secrets.get을 읽은 후 반환된 값을 애플리케이션 코드에 전달합니다. dbutils 셀 출력과 로그에서 값을 삭제하므로, 노출하지 않고 사용할 수 있습니다.

다음 예시는 비밀을 베어러 토큰으로 사용하여 외부 API를 호출합니다:

import requests

api_key = dbutils.secrets.get(catalog="main", schema="default", key="service_api_key")

response = requests.get(
    "https://api.example.com/v1/resource",
    headers={"Authorization": f"Bearer {api_key}"},
)
response.raise_for_status()

다음 예시는 비밀 값을 가져와 AWS SDK용 boto3 세션을 구성하는 데 전달 dbutils.credentials.getServiceCredentialsProvider 합니다. 서비스 자격 증명 이름 자체는 민감하지 않으므로, 이 예시는 시크릿 안에 하나를 저장하여 검색한 시크릿 값을 다른 SDK 호출에 연결하는 방식을 보여줍니다. 서비스 자격 증명에 대한 자세한 내용은 Unity 카탈로그 서비스 자격 증명 사용에 대해 외부 클라우드 서비스에 연결하기를 참조하세요.

import boto3

credential_name = dbutils.secrets.get(catalog="main", schema="default", key="service_credential_name")

boto3_session = boto3.Session(
    botocore_session=dbutils.credentials.getServiceCredentialsProvider(credential_name),
    region_name="your-aws-region",
)
sm = boto3_session.client("secretsmanager")

비밀에 대한 권한 관리

카탈로그 또는 스키마 수준에서 권한을 부여 CREATE SECRET 하여 비밀을 만들 수 있는 사용자를 제어합니다. 카탈로그, 스키마 또는 개별 시크릿 수준에서 액세스를 제어하기 위해 READ SECRET, WRITE SECRET 또는 REFERENCE SECRET를 부여합니다. 권한 상속이 적용됩니다. 권한 부여 및 취소에 대한 자세한 내용은 Unity 카탈로그에서 권한 관리를 참조하세요.

비밀을 만들 수 있는 권한 부여

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동합니다.
권한 탭을 클릭합니다.
Grant를 클릭합니다.
액세스 권한을 부여할 보안 주체를 선택한 다음, CREATE SECRET을 선택합니다.

보안 주체에 USE SCHEMA이(가) 없으면 이를 부여하라는 경고 메시지가 표시됩니다. USE SCHEMA 는 스키마에서 비밀을 만드는 데도 필요합니다.
확인을 클릭합니다.

SQL

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

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /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}"

비밀에 대한 액세스 권한 부여

카탈로그 탐색기

카탈로그 탐색기에서 보안 암호로 이동한 후 해당 항목을 클릭합니다.
권한 탭을 클릭합니다.
Grant를 클릭합니다.
보안 주체 및 부여할 권한을 선택한 다음 확인을 클릭합니다.

SQL

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

REST API

엔드포인트를 사용하여 다음 cURL 명령을 실행합니다 /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}"

비밀 나열, 업데이트 및 삭제

비밀 목록 작성

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동합니다.
개요 창에서 비밀을 클릭하여 스키마의 모든 비밀을 확인합니다.

비밀 관리 유틸리티(dbutils.secrets)

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

REST API

페이지당 결과 수를 조절하는 데 사용 page_size 하세요. 더 많은 결과가 있을 경우, 응답에는 다음과 같이 포함됩니다:next_page_token

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

다음 페이지를 가져오려면, 이전 응답의 값을 매개변수로 page_token 전달 next_page_token 합니다:

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

비밀 업데이트

비밀 값을 업데이트하려면 해당 비밀에 대해 WRITE SECRET 권한이 있어야 합니다.

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동하고 개요 창에서 비밀을 클릭합니다.
업데이트하려면 시크릿을 클릭하세요.
오른쪽 위 모서리에서 케밥 메뉴(세로 점)를 클릭하고 편집을 선택합니다.
새 값 또는 만료 날짜를 입력한 다음 확인을 클릭합니다.

REST API

업데이트 요청에는 매개 변수가 update_mask 필요합니다. 둘 다 update_mask 에 포함된 필드와 요청 본문만 업데이트됩니다.

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=*"

비밀 삭제

카탈로그 탐색기

카탈로그 탐색기에서 스키마로 이동하고 개요 창에서 비밀을 클릭합니다.
삭제할 비밀을 클릭합니다.
오른쪽 위 모서리에서 케밥 메뉴(세로 점)를 클릭하고 삭제를 선택합니다.
비밀의 전체 이름을 입력한 다음 삭제를 클릭합니다.

REST API

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

Unity 카탈로그 시크릿에 대한 감사 이벤트

시스템 테이블은 system.access.audit Unity 카탈로그 비밀과 관련된 이벤트를 기록합니다. 예를 들어 특정 날짜에 사용자에 대한 모든 비밀 이벤트를 보려면 다음 쿼리를 실행합니다.

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%";

감사 로그에 대한 자세한 내용은 감사 로그 시스템 테이블 참조를 참조하세요.

고객 관리형 키를 사용하여 비밀 값 암호화

기본적으로 Azure Databricks Databricks 관리형 키를 사용하여 비밀 값을 암호화합니다. 대신 CMK(고객 관리형 키)를 사용할 수 있습니다. CMK 암호화 관리 카탈로그 기능을 사용하도록 설정하고 계정에 CMK 구성을 연결하는 경우 Azure Databricks CMK를 사용하여 비밀 값을 암호화합니다. 자세한 내용은 Unity 카탈로그에 대한 고객 관리형 키를 참조하세요.

외부 비밀 관리자를 사용해 비밀 관리하기

Azure Databricks가 비밀 값을 저장하는 대신, 외부 비밀 관리자로 스키마를 백업하여 값은 클라우드 비밀 관리자에 남으면서도 Unity 카탈로그에서 관리할 수 있습니다. AWS Secrets Manager on AWS 및 Azure Key Vault on Azure가 지원됩니다. 외부 비밀이 어떻게 작동하는지에 대해서는 Unity 카탈로그의 외부 비밀을 참조하세요. 외부 비밀 관리자가 있는 스키마를 지원하려면 Unity 카탈로그에서 외부 비밀 설정 항목을 참조하세요.

Limitations

Unity 카탈로그 비밀에는 다음과 같은 제한 사항이 있습니다.

SQL 웨어하우스에서의 직접 접근 제한. Unity 카탈로그 비밀은 SQL 웨어하우스에서 직접 가져올 수 없습니다. 스칼라 및 배치 Unity Catalog Python UDF는 Pro 및 서버리스 SQL 웨어하우스에서 해당 SECRETS 절에 선언된 보안 비밀에 액세스할 수 있습니다. Scalar Unity Catalog Scala UDF는 서버리스 SQL 웨어하우스에서만 선언된 비밀에 접근할 수 있습니다.
전용 컴퓨트에서는 직접 SECRETS UDF 호출이 없습니다. 전용 액세스 모드 컴퓨트에서는 SECRETS 절을 사용하는 스칼라 또는 배치 Unity Catalog Python UDF나 스칼라 Unity Catalog Scala UDF를 직접 호출할 수 없습니다. 열 마스크 예외에 대해서는 전용 컴퓨트의 열 마스크에서 비밀 지원 UDF 사용을 참조하세요.
전역 검색 기능이 없습니다. Unity 카탈로그 비밀은 전역 검색에 표시되지 않습니다.
BROWSE 권한 지원이 없습니다.카탈로그에 대한 BROWSE는 Unity Catalog 시크릿에는 적용되지 않습니다. 비밀을 검색 가능하게 하려면 개별 비밀 또는 해당 스키마에 대해 READ SECRET 또는 REFERENCE SECRET 권한을 부여하세요.
init 스크립트가 없습니다. 전역 또는 클러스터 초기화 스크립트에서는 Unity 카탈로그 비밀을 사용할 수 없습니다. Azure Databricks에서는 가능하면 초기화 스크립트 대신 전용 기능을 사용할 것을 권장합니다.
정보 스키마가 없습니다. 비밀에 대한 정보 스키마 테이블은 아직 사용할 수 없습니다. 검색을 위해 카탈로그 탐색기 또는 REST API를 사용합니다.
dbutils 런타임 범위. dbutils 검색 기능은 Databricks Runtime 기반 노트북 및 작업에서 지원됩니다. 원격 개발 또는 컴파일된 JAR 실행 모드와 같은 비 Databricks 런타임 컨텍스트는 지원되지 않습니다.
OAuth API 범위입니다. Unity 카탈로그 비밀 API는 OAuth API 범위에서 unity-catalog 만 액세스할 수 있습니다. 작업 영역 수준의 Azure Databricks 비밀에만 secrets API 스코프를 사용하세요.
할당량 한도입니다. 각 스키마당 최대 100개의 시크릿, 메타스토어당 최대 1,000개의 시크릿.

피드백

이 페이지가 도움이 되었나요?

2026-10-06 에 마지막으로 업데이트됨

Unity 카탈로그의 비밀

Unity 카탈로그 비밀 작동 방식

UDF 요구사항 및 권한

세션 범위의 UDF

Unity 카탈로그 UDF들

전용 컴퓨팅에서 열 마스크에 secret 지원 UDF를 사용하세요

Unity 카탈로그 비밀에 대한 권한

Requirements

비밀 만들기

카탈로그 탐색기

REST API

비밀 읽기

비밀 관리 유틸리티(dbutils.secrets)

REST API

코드에 비밀을 사용하세요

비밀에 대한 권한 관리

비밀을 만들 수 있는 권한 부여

카탈로그 탐색기

SQL

REST API

비밀에 대한 액세스 권한 부여

카탈로그 탐색기

SQL

REST API

비밀 나열, 업데이트 및 삭제

비밀 목록 작성

카탈로그 탐색기

비밀 관리 유틸리티(dbutils.secrets)

REST API

비밀 업데이트

카탈로그 탐색기

REST API

비밀 삭제

카탈로그 탐색기

REST API

Unity 카탈로그 시크릿에 대한 감사 이벤트

고객 관리형 키를 사용하여 비밀 값 암호화

외부 비밀 관리자를 사용해 비밀 관리하기

Limitations

피드백

추가 리소스