Skip to main content
이 페이지에서는 두 가지 인증 방법을 다룹니다. Personal Access Token(PAT) 은 가장 오래된 Databricks 인증 방식으로, 간단하지만 보안 한계가 있습니다. OAuth Token Federation 은 가장 최신 방식으로, Secret 관리 부담을 완전히 제거합니다.

​
Part 1: Personal Access Token (PAT)

​
PAT란

PAT(Personal Access Token)는 워크스페이스 레벨에서 발급되는 문자열 기반 토큰 입니다. HTTP 요청의 Authorization: Bearer <token> 헤더에 포함하여 인증합니다. Databricks 초기부터 지원된 가장 단순한 인증 방식입니다.

​
언제 PAT를 사용하는가

주의 Databricks는 PAT 대신 OAuth를 강력히 권장합니다. PAT는 다음과 같은 제한적 상황에서만 사용하세요.
상황사유
빠른 API 테스트curl로 즉시 테스트, 프로덕션 전환 시 OAuth로 교체
레거시 시스템 연동OAuth를 지원하지 않는 구형 도구/라이브러리
학습/교육 목적인증 개념을 이해하기 위한 가장 단순한 예시

​
PAT 생성

​
UI에서 생성

  1. Workspace > Settings > Developer > Access tokens 이동
  2. Generate new token 클릭
  3. Comment(설명)와 Lifetime(수명) 입력
  4. Generate 클릭 → 토큰이 한 번만 표시됨

​
CLI로 생성

# 사용자 본인의 PAT 생성
databricks tokens create \
  --comment "API 테스트용" \
  --lifetime-seconds 86400 \
  --profile DEV

# 출력 예시
# {
#   "token_info": {
#     "token_id": "dapi...",
#     "creation_time": 1712563200000,
#     "expiry_time": 1712649600000,
#     "comment": "API 테스트용"
#   },
#   "token_value": "dapi1234567890abcdef..."
# }

​
Service Principal용 OBO Token

Service Principal은 직접 UI에 로그인할 수 없으므로, 관리자가 On-Behalf-Of(OBO) 방식으로 SP의 PAT를 대리 발급합니다. 
# SP 대신 PAT 생성 (관리자 권한 필요)
databricks token-management create-obo-token \
  --application-id <sp-application-id> \
  --comment "CI/CD 파이프라인용" \
  --lifetime-seconds 7776000 \
  --profile ADMIN
참고 OBO Token vs OAuth M2M: SP용 PAT(OBO Token)보다는 OAuth M2M(client_credentials)을 권장합니다. OAuth M2M은 토큰 자동 갱신을 지원하고, Secret 로테이션이 더 유연합니다.

​
Scoped PAT (권한 범위 제한)

PAT는 기본적으로 사용자의 전체 권한 으로 동작합니다. Scoped PAT를 사용하면 특정 API 범위로만 제한할 수 있습니다. 지원되는 scope는 다음과 같습니다.
Scope접근 가능 API
sqlSQL Warehouse, Query 실행
unity-catalogUnity Catalog 메타데이터 관리
scim사용자/그룹 관리 (SCIM API)
clusters클러스터 생성/관리
workspace노트북, 디렉토리 관리
Scoped PAT를 사용하면, 토큰이 유출되더라도 지정된 API 범위 밖의 작업은 수행할 수 없어 피해를 제한할 수 있습니다.

​
PAT 보안 관리

​
자동 폐기 정책

Databricks는 90일간 미사용된 PAT를 자동 폐기 합니다. 이는 “잊혀진 토큰”이 무한히 유효한 상태로 남는 것을 방지합니다.

​
워크스페이스 관리자 정책

관리자는 다음을 설정할 수 있습니다.
정책설명
PAT 비활성화워크스페이스 전체에서 PAT 사용 금지
최대 수명 제한예: 최대 90일까지만 유효한 토큰 발급 허용
특정 사용자만 허용PAT 발급 권한을 관리자에게만 제한
# 워크스페이스의 PAT 정책 확인
databricks workspace-conf get-status \
  --keys "enableTokensConfig,maxTokenLifetimeDays" \
  --profile DEV

​
토큰 모니터링

# 현재 활성 토큰 목록 (관리자)
databricks token-management list --profile ADMIN

# 특정 사용자의 토큰
databricks token-management list \
  --created-by-id <user-id> \
  --profile ADMIN

​
PAT vs OAuth: 상세 비교

아래 테이블은 PAT와 OAuth의 핵심 차이를 비교합니다.
항목PATOAuth (U2M/M2M)
토큰 수명사용자 지정 (무기한 가능)1시간 (고정)
자동 갱신❌ 수동 재발급✅ 자동
Account 레벨❌ 워크스페이스만✅ Account + Workspace
토큰 저장평문 문자열 (파일, 환경변수)OS 보안 저장소 (U2M) 또는 메모리 (M2M)
유출 시 피해토큰 수명 동안 무제한 접근최대 1시간 (자동 만료)
감사 추적토큰 ID로 추적OAuth 세션으로 추적
멀티 워크스페이스워크스페이스별 별도 토큰프로파일로 통합 관리
PKCE 보호❌✅ (U2M)
이 비교가 명확히 보여주듯, OAuth는 모든 보안 지표에서 PAT보다 우수합니다. PAT의 유일한 장점은 “단순함”이지만, Databricks CLI/SDK의 OAuth 지원이 성숙해진 현재, 이 장점도 크게 희석되었습니다.

​
PAT 사용 예시 (참고용)

# curl로 API 호출
curl -X GET "https://<workspace-host>/api/2.0/clusters/list" \
  -H "Authorization: Bearer dapi1234567890abcdef..."

# .databrickscfg에 PAT 설정
# [DEV-PAT]
# host  = https://<workspace-host>
# token = dapi1234567890abcdef...

from databricks.sdk import WorkspaceClient

# PAT로 인증
w = WorkspaceClient(
    host="https://<workspace-host>",
    token="dapi1234567890abcdef..."
)

clusters = w.clusters.list()

​
Part 2: OAuth Token Federation

​
개념

OAuth Token Federation은 외부 IdP(Identity Provider)가 발급한 OIDC 토큰으로 Databricks에 인증 하는 방식입니다. 핵심 아이디어는 단순합니다:
“이미 신뢰할 수 있는 외부 시스템이 발급한 신원 증명을 Databricks가 그대로 수용한다.”
이를 통해 Databricks Secret(client_secret)을 전혀 관리하지 않고도 인증할 수 있습니다.

​
왜 혁신적인가

OAuth M2M의 가장 큰 운영 부담은 Secret 관리 입니다.
OAuth M2M의 Secret 관리 과제Token Federation의 해결
Secret 생성/저장/로테이션Secret 자체가 없음
Secret 유출 위험 (CI/CD 변수, 설정 파일)유출 가능한 Secret이 존재하지 않음
Secret 만료 시 서비스 중단외부 IdP가 매번 새 토큰 발급
멀티 환경(dev/staging/prod) Secret 관리환경별 외부 토큰 자동 발급
참고 비유: 호텔에서 체크인할 때 여권(외부 IdP 토큰)을 보여주면, 호텔(Databricks)이 객실 키(access_token)를 발급하는 것과 같습니다. 여권은 이미 신뢰할 수 있는 기관(정부 = IdP)이 발급했으므로, 호텔이 별도의 회원 카드(client_secret)를 요구하지 않습니다.

​
동작 원리

외부 워크로드          외부 IdP              Databricks
(GitHub Actions)    (GitHub OIDC)         인증서버
       │                │                    │
       │ 1. OIDC 토큰    │                    │
       │    요청          │                    │
       │───────────────▶│                    │
       │                │                    │
       │ 2. OIDC 토큰    │                    │
       │    발급          │                    │
       │◀───────────────│                    │
       │                │                    │
       │ 3. Databricks 토큰 교환 요청          │
       │    (외부 OIDC 토큰 +                  │
       │     grant_type=                      │
       │     urn:ietf:params:oauth:           │
       │     grant-type:token-exchange)       │
       │──────────────────────────────────────▶
       │                                      │
       │                    4. 외부 토큰 검증    │
       │                    - 발급자(issuer)    │
       │                      확인             │
       │                    - 서명 검증         │
       │                    - audience 확인    │
       │                    - 매핑된 SP 찾기    │
       │                                      │
       │ 5. Databricks access_token 발급       │
       │    (1시간, SP의 권한)                  │
       │◀──────────────────────────────────────│
       │                                      │
       │ 6. API 호출 (Bearer token)            │
       │──────────────────────────────────────▶│

​
핵심 구성 요소

구성 요소설명
Federation Policy어떤 외부 IdP를 신뢰할지 정의 (issuer URL, audience)
Service Principal Mapping외부 토큰의 subject를 어떤 SP에 매핑할지 정의
OIDC Token외부 IdP가 발급하는 JWT (JSON Web Token)
Token Exchange외부 OIDC 토큰을 Databricks access_token으로 교환하는 과정

​
지원 시나리오

Token Federation은 OIDC를 지원하는 모든 외부 IdP 와 연동할 수 있습니다. 아래 테이블은 주요 사용 사례와 외부 IdP를 보여줍니다.
시나리오외부 IdPOIDC Issuer 예시
GitHub ActionsGitHub OIDC Providerhttps://token.actions.githubusercontent.com
Azure DevOpsAzure AD (Entra ID)https://login.microsoftonline.com/{tenant}/v2.0
AWS 워크로드AWS STS (OIDC)https://sts.amazonaws.com
GCP 워크로드Google OIDChttps://accounts.google.com
KubernetesK8s Service Account클러스터별 OIDC issuer URL
GitLab CIGitLab OIDChttps://gitlab.com

​
GitHub Actions 연동 예시

GitHub Actions는 Token Federation의 가장 대표적인 사용 사례입니다.

​
1단계: Service Principal 생성

Account Console에서 CI/CD용 SP를 생성하고, 필요한 권한을 부여합니다.

​
2단계: Federation Policy 생성

Databricks Account Console 또는 API에서 Federation Policy를 구성합니다. 
{
  "name": "github-actions-federation",
  "issuer": "https://token.actions.githubusercontent.com",
  "audiences": ["https://accounts.cloud.databricks.com"],
  "subject_claim": "sub",
  "subject": "repo:MyOrg/MyRepo:ref:refs/heads/main"
}
필드설명
issuerGitHub OIDC Provider의 URL
audiences토큰이 사용될 대상 (Databricks)
subject_claimJWT에서 subject를 추출할 claim 이름
subject허용할 subject 값 (특정 repo/branch로 제한)
이 설정이 의미하는 바는 명확합니다: MyOrg/MyRepo 리포지토리의 main 브랜치에서 실행되는 GitHub Actions 워크플로우만 이 SP로 인증할 수 있습니다. 다른 리포지토리나 브랜치는 거부됩니다.

​
3단계: GitHub Actions 워크플로우

name: Deploy to Databricks

on:
  push:
    branches: [main]

permissions:
  id-token: write   # OIDC 토큰 발급 권한
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # GitHub OIDC 토큰 자동 발급
      - name: Get OIDC Token
        id: oidc
        uses: actions/github-script@v7
        with:
          script: |
            const token = await core.getIDToken('https://accounts.cloud.databricks.com');
            core.setOutput('token', token);

      # Databricks CLI 설치 및 인증
      - name: Setup Databricks CLI
        uses: databricks/setup-cli@main

      - name: Deploy
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_TOKEN_FEDERATION: ${{ steps.oidc.outputs.token }}
        run: |
          databricks bundle deploy --target production
참고 Secret이 전혀 없습니다: 위 워크플로우에서 DATABRICKS_HOST는 URL(공개 정보)일 뿐이고, OIDC 토큰은 GitHub가 매 실행마다 자동 발급합니다. client_secret이나 PAT를 GitHub Secrets에 저장할 필요가 없습니다.

​
Token Federation vs OAuth M2M 비교

두 방식 모두 Service Principal로 인증하지만, Secret 관리 방식에서 근본적인 차이가 있습니다.
항목OAuth M2MToken Federation
인증 자격client_id + client_secret외부 OIDC 토큰
Secret 관리필요 (생성, 저장, 로테이션)불필요
유출 위험client_secret 유출 가능유출 가능한 자격 증명 없음
설정 복잡도낮음중간 (Federation Policy 설정)
외부 IdP 의존없음있음 (IdP 장애 시 인증 불가)
적용 범위모든 자동화 환경OIDC 지원 환경만
이 비교에서 보듯, Token Federation은 보안 면에서 확실히 우수하지만, 외부 IdP에 대한 의존성 이 추가됩니다. 외부 IdP가 OIDC를 지원하는 환경(GitHub Actions, Azure DevOps, AWS 등)이라면 Token Federation을, 그렇지 않은 환경이라면 OAuth M2M을 선택하세요.

​
Token Federation의 한계

  • 초기 설정 복잡도: Federation Policy, SP Mapping 등 초기 구성이 OAuth M2M보다 복잡합니다. 하지만 한 번 설정하면 운영 부담이 거의 없습니다.
  • 외부 IdP 의존: GitHub, Azure AD 등 외부 서비스 장애 시 인증이 불가능합니다.
  • OIDC 필수: 외부 시스템이 OIDC 토큰을 발급할 수 있어야 합니다. 모든 시스템이 이를 지원하지는 않습니다.
  • 디버깅 어려움: 인증 실패 시 외부 IdP 토큰의 claim 값, Federation Policy 매핑 등 확인할 요소가 많습니다.

​
인증 방법 최종 정리

아래 테이블은 네 가지 인증 방법의 선택 기준을 최종 정리합니다.
질문답변 → 인증 방법
개발자가 로컬에서 작업하는가?OAuth U2M
자동화이고, 외부 IdP(GitHub 등)가 OIDC를 지원하는가?Token Federation
자동화이고, 외부 IdP가 없거나 OIDC 미지원인가?OAuth M2M
5분 안에 빠르게 API 테스트해야 하는가?PAT (임시용)
주의 프로덕션 환경에서 PAT는 사용하지 마세요. PAT는 개발/테스트 단계의 임시 수단입니다. 프로덕션으로 전환할 때는 반드시 OAuth 기반 인증으로 교체하세요. 조직의 보안 감사(Audit)에서 PAT 사용은 거의 항상 지적 사항입니다.