DatabricksにおけるOAuth Machine-to-Machine実装

Databricksへの自動化アクセス（CI/CDパイプライン、Airflowジョブ、外部アプリケーション）では、 人間のユーザーではなくプログラムが認証する必要があります。従来はPersonal Access Token（PAT）が広く使われていましたが、 2024年以降DatabricksはOAuth Machine-to-Machine（M2M）認証を推奨方式に位置づけています。

この記事では、OAuth M2Mの仕組み（Client Credentials Flow）、サービスプリンシパルの作成から OAuthアプリ登録・トークン取得までの具体的な手順、PATとの比較、そして試験で問われるポイントを解説します。

なぜOAuth M2Mが必要か

PATには以下の運用上の課題があります。

• PATは個人ユーザーに紐づくため、退職・異動でトークンが孤立するリスクがある
• 有効期限の管理が手動で、期限切れによるパイプライン障害が起きやすい
• PATが漏洩した場合、そのユーザーの全権限でアクセスされる
• PATの使用状況の監査が困難（どのPATがどのパイプラインで使われているか不明確）

OAuth M2Mは、サービスプリンシパル（人間でないIDエンティティ）とOAuth 2.0 Client Credentials Flowを組み合わせることで、 これらの課題を構造的に解決します。

OAuth 2.0 Client Credentials Flow

OAuth M2MはOAuth 2.0のClient Credentials Grantを使用します。 ユーザーの操作を一切介さず、クライアント（プログラム）がClient IDとClient Secretを使って直接トークンを取得するフローです。

1. クライアントがトークンリクエストを送信: Client IDとClient Secretを含むPOSTリクエストをDatabricksのトークンエンドポイントに送信
2. Databricksがクライアントを認証: Client IDとSecretを検証し、サービスプリンシパルの権限を確認
3. アクセストークンを発行: 短寿命のBearer Token（デフォルト1時間）を返却
4. トークンでAPIにアクセス: 取得したトークンをAuthorizationヘッダに付与してDatabricks APIを呼び出す

Authorization Code Flowと異なり、ブラウザリダイレクトやユーザーの同意画面はありません。 完全に機械同士のやり取りで完結するため「Machine-to-Machine」と呼ばれます。

セットアップ手順

OAuth M2M認証を構成するステップは以下の3つです。

ステップ1: サービスプリンシパルの作成

Account Consoleまたはdatabricks service-principals create CLIコマンドで サービスプリンシパルを作成します。

# Databricks CLIでサービスプリンシパルを作成
databricks service-principals create \
  --application-id "<application-id>" \
  --display-name "ci-cd-pipeline-sp"

# または Account SCIM API経由
curl -X POST \
  "https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/scim/v2/ServicePrincipals" \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "ci-cd-pipeline-sp",
    "entitlements": [
      { "value": "workspace-access" }
    ]
  }'

ステップ2: OAuthアプリケーション（Client Secret）の登録

サービスプリンシパルに対してOAuth Secretを生成します。

# サービスプリンシパルのOAuth Secretを生成
curl -X POST \
  "https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/servicePrincipals/<sp-id>/credentials/secrets" \
  -H "Authorization: Bearer <admin-token>"

# レスポンス例
{
  "id": "secret-id-xxxx",
  "secret": "dose...xxxx",   ← この値を安全に保管
  "status": "ACTIVE",
  "create_time": "2026-03-26T10:00:00.000Z"
}

注意: Client Secretは作成時のレスポンスでのみ返却されます。 後から取得することはできないため、必ずシークレットマネージャー（AWS Secrets Manager, Azure Key Vault等）に保管してください。

ステップ3: トークンの取得

Client IDとClient Secretを使ってアクセストークンを取得します。

# アクセストークンの取得
curl -X POST \
  "https://<workspace-url>/oidc/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<service-principal-client-id>" \
  -d "client_secret=<client-secret>" \
  -d "scope=all-apis"

# レスポンス例
{
  "access_token": "eyJhbGciOiJSUzI1NiI...",
  "token_type": "Bearer",
  "expires_in": 3600
}

取得したアクセストークンをAuthorizationヘッダに付与してDatabricks APIを呼び出します。

# トークンを使ってジョブ一覧を取得
curl -X GET \
  "https://<workspace-url>/api/2.1/jobs/list" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiI..."

PAT vs OAuth M2M 比較表

CI/CDパイプラインでの活用パターン

OAuth M2MをCI/CDパイプラインに組み込む際の典型的なパターンを示します。

# GitHub Actions の例
name: Deploy Databricks Jobs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Databricks CLI
        run: pip install databricks-cli

      - name: Get OAuth Token
        id: token
        run: |
          TOKEN=$(curl -s -X POST \
            "${{ secrets.DATABRICKS_HOST }}/oidc/v1/token" \
            -d "grant_type=client_credentials" \
            -d "client_id=${{ secrets.DATABRICKS_CLIENT_ID }}" \
            -d "client_secret=${{ secrets.DATABRICKS_CLIENT_SECRET }}" \
            -d "scope=all-apis" | jq -r '.access_token')
          echo "::add-mask::$TOKEN"
          echo "token=$TOKEN" >> $GITHUB_OUTPUT

      - name: Deploy with Databricks CLI
        run: databricks bundle deploy --target production
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_TOKEN: ${{ steps.token.outputs.token }}

Client IDとClient SecretはGitHub Secretsに格納し、コードにハードコードしない点が重要です。

セキュリティ上の注意点

• Client Secretのローテーション: 定期的に新しいSecretを生成し、古いSecretを無効化する。 Secretの有効期間ポリシーを組織で定めておく
• 最小権限の原則: サービスプリンシパルにはパイプラインに必要な最小限の権限のみ付与する。 CAN_MANAGE_RUNではなくCAN_VIEW等、可能な限り読み取り専用にする
• Secretの保管: AWS Secrets Manager、Azure Key Vault、HashiCorp Vault等のシークレットマネージャーを使い、 環境変数やコード内にSecretを直接埋め込まない
• 監査ログの確認: サービスプリンシパルの操作はDatabricksの監査ログに記録される。 不審なアクセスパターンを検知するアラートを設定する

試験で問われるポイント

• 「CI/CDパイプラインで推奨される認証方式は」→ OAuth M2M（サービスプリンシパル + Client Credentials）
• 「PATのセキュリティ上の問題点は」→ 長寿命・ユーザー依存・権限スコープの広さ
• 「OAuth M2Mのトークン取得に使うOAuth 2.0フローは」→ Client Credentials Grant
• 「サービスプリンシパルとは何か」→ 人間でないIDエンティティ（アプリケーションやパイプライン用）

問題で確認

よくある質問