\
--json '{"permissions": ["USER"]}'
```
`ADMIN` ではなく `USER` を利用してください。Devin にワークスペースの管理者権限は不要です。
## ステップ2: Devinをサービスプリンシパルに接続する
以下の2つの選択肢のうち、**いずれか一方**を実施してください。それぞれ単独で完結しており、**Settings > Environment > Blueprints** 配下の[ブループリント](/ja/onboard-devin/environment/blueprints)を利用してDatabricks CLIをインストールし、ステップ1のサービスプリンシパルとして認証するようCLIを設定します。
* [**オプションA: OAuthクライアントシークレット**](#option-a-oauth-client-secret)。標準的な[OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m)方式です。サービスプリンシパルにクライアントシークレットを発行し、それをDevin Secretsに保存します。最も手早く始められる方法です。
* [**オプションB: OIDCトークンフェデレーション**](#option-b-oidc-token-federation)。Devinのセッションごとに、Devinが署名した短命のOpenID Connectトークンを発行できます。Databricksの[トークンフェデレーション](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation)により、サービスプリンシパルがその発行者を信頼できるようになるため、Devinは自身のIDトークンをDatabricksのOAuthトークンと交換します。Databricksのシークレットを作成・保存する必要が一切ないため、Databricksは自動化されたワークロードにこの方式を強く推奨しています。
人間のユーザーに紐づくパーソナルアクセストークン (PAT) は、どちらのオプションでも推奨されません。サービスプリンシパルを迂回してしまい、失効のタイミングが予測できず、Devinの操作が個人に帰属することになるためです。
### オプションA: OAuthクライアントシークレット
Databricksのシークレットを管理したくない場合は、[オプションB: OIDCトークンフェデレーション](#option-b-oidc-token-federation)へ進んでください。まずはこちらの方法で始めて、後から切り替えることもできます。その場合は、オプションBのブループリントに差し替え、フェデレーションポリシーを作成したうえで、OAuthシークレットと `DATABRICKS_CLIENT_SECRET` のDevin Secretを削除してください。
#### 1. OAuth シークレットを生成する
アカウントコンソールで Step 1 のサービスプリンシパルを開き、**OAuth シークレット**を生成します。ローテーションプロセスで対応可能な範囲で最短の有効期間 (最大 730 日) を設定し、シークレットの適用範囲は `sql`、`jobs`、`unity-catalog` など Devin に必要な API スコープのみに限定してください。すべてのスコープを選択することは避けてください。
#### 2. Devin シークレットを追加する
Devin で、次に編集するブループリント (組織またはリポジトリ) の **Secrets** タブに、以下を [Devin シークレット](/ja/product-guides/secrets)として追加します。
| シークレット | 値 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABRICKS_HOST` | Devin に作業させたい **workspace** の URL。例: `https://dbc-xxxx.cloud.databricks.com` または `https://adb-xxxx.azuredatabricks.net` (`/api` サフィックスは付けません) 。`accounts.*` ホストではありません。 |
| `DATABRICKS_CLIENT_ID` | ステップ 1 で取得した service principal の `applicationId` (UUID) 。数値の `id` ではありません |
| `DATABRICKS_CLIENT_SECRET` | 生成した OAuth シークレット |
client ID と client secret が設定されていれば、CLI は自動的に OAuth M2M を選択するため、`DATABRICKS_AUTH_TYPE` の設定は不要です。他のすべての方式を明示的に除外したい場合のみ `oauth-m2m` を設定してください。
シークレットは新しいセッションの開始時に環境変数として注入されるため、CLI 用のプロファイルファイルは不要です。ローテーションしたシークレットは、再ビルドなしで次回の新しいセッションから適用されます。
#### 3. ブループリントを追加する
CLI のインストールのみを行います。認証はすべて、上記の 3 つのシークレットによって行われます。
```yaml theme={null}
initialize:
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
databricks --version
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI authenticates as a service principal using the DATABRICKS_HOST,
DATABRICKS_CLIENT_ID, and DATABRICKS_CLIENT_SECRET environment variables, which are
provided as Devin Secrets. Do not run `databricks auth login`, do not set DATABRICKS_TOKEN,
and do not ask for a personal access token. Check auth with `databricks current-user me`.
Write only to the devin_dev catalog; production catalogs are read-only. Ship notebook and
job changes through a pull request.
```
`initialize` 中にシークレットをファイルへ書き込まないでください。そこに書き込まれた内容はすべてスナップショットに取り込まれます。
あわせて `DATABRICKS_TOKEN` を設定したり、`~/.databrickscfg` の profile をスナップショットに残したりしないでください。認証情報の競合は、M2M 認証が失敗する最も一般的な原因です。
#### 4. スナップショットをビルドする
ブループリントを保存し、ビルドが **成功** と表示されるまで待ってから、新しいセッションを開始します。既存のセッションでは古いスナップショットがそのまま使用されます。[ステップ 3](#step-3-grant-permissions) に進んでください。
### オプション B: OIDC トークンフェデレーション
Devin セッションは有効期限の短い ID トークン(`iss`、`sub`、`aud`)を発行し、service principal に設定したフェデレーションポリシーによって、Databricks がそのトークンを信頼するようになります。ブループリントは `devin-oidc` CLI をインストールし、すべての呼び出しで新しいトークンが渡されるように `databricks` をラップしたうえで、service principal を指す profile を書き込みます。あとは、セッションからトークンの claims を読み取り、それに一致するポリシーを作成するだけです。
まずは最短の手順を試しませんか?[オプション A](#option-a-oauth-client-secret) から始め、保存された secret をやめる準備ができたらここに戻ってきてください。
#### 1. ブループリントを追加する
profile内の2つのプレースホルダーを、ご自身の値に置き換えてください。
| プレースホルダー | 置き換える内容 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | Devinに作業させる**workspace**のURL。例: `https://dbc-xxxx.cloud.databricks.com` または `https://adb-xxxx.azuredatabricks.net` (`/api` サフィックスは付けません) 。`accounts.*` ホストではない点に注意してください。Option Aの `DATABRICKS_HOST` と同じ値です。 |
| `` | Step 1で実行した `databricks account service-principals create` の出力に含まれる、service principalの `applicationId` (UUID) 。数値の `id` ではありません。`id` はfederation policyをアタッチするときにのみ利用します。 |
```yaml theme={null}
initialize:
- uses: github.com/CognitionAI/actions/setup-devin-oidc@main
- name: Install Databricks CLI
run: |
sudo rm -f /usr/local/bin/databricks
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | sudo sh
sudo mv /usr/local/bin/databricks /usr/local/bin/databricks-bin
- name: Wrap the CLI so each call carries a fresh Devin OIDC token
run: |
sudo tee /usr/local/bin/databricks > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DATABRICKS_OIDC_TOKEN="$(devin-oidc token --audience "${DATABRICKS_DEVIN_AUDIENCE:-databricks}")"
export DATABRICKS_OIDC_TOKEN
exec /usr/local/bin/databricks-bin "$@"
EOF
sudo chmod +x /usr/local/bin/databricks
- name: Write Databricks CLI profile
run: |
cat > ~/.databrickscfg <<'EOF'
[DEFAULT]
host =
auth_type = env-oidc
client_id =
audience = databricks
EOF
chmod 600 ~/.databrickscfg
knowledge:
- name: databricks-auth
contents: |
The `databricks` CLI is preconfigured to authenticate as a service principal through
Devin OIDC token federation. Do not run `databricks auth login`, do not set
DATABRICKS_TOKEN, and do not ask for a personal access token. Check auth with
`databricks current-user me`. Write only to the devin_dev catalog; production catalogs
are read-only. Ship notebook and job changes through a pull request.
```
| 構成要素 | 目的 |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `setup-devin-oidc` | Devin の identity token を発行する `devin-oidc` CLI をインストールします ([詳細](/ja/product-guides/oidc)) 。 |
| ラッパー | Devin の identity token は 60 秒で失効するため、CLI 呼び出しごとにトークンを新たに発行します。 |
| `auth_type = env-oidc` | CLI を token federation に固定し、PAT や対話型ログインにフォールバックしないようにします。 |
| `host` / `client_id` | 上の表にあるワークスペース URL と service principal の `applicationId`。 |
| `audience` | ラッパーが要求するオーディエンス。後述の federation policy にも同じ値を設定します。 |
| `knowledge` | CLI が既に認証済みであることを Devin に伝え、`databricks auth login` を実行しないようにします。 |
このプロファイルには secret が含まれないため、`initialize` 中に書き込んでも安全です。Option A から切り替える場合は、下記の policy を設定したうえで `DATABRICKS_CLIENT_SECRET` の Devin Secret を削除し、CLI が 2 つの認証情報を認識しないようにしてください。
#### 2. スナップショットをビルドする
ブループリントを保存し、ビルドのステータスが **成功** になるまで待ちます。ブループリントには次に作成するフェデレーションポリシーに依存する要素はないため、後からリビルドする必要はありません。
#### 3. フェデレーションポリシーを作成する
ブループリントをビルドすると、Devin セッションは ID トークンを発行できるようになります。そのトークンを利用して Databricks が信頼すべきクレームの正確な値を確認し、それに一致するフェデレーションポリシーを service principal に作成します。
新しい Devin セッションを開始し、以下を実行するよう指示してください。出力されるのはトークンの ID クレームのみで、トークン自体が出力されることはありません。
```bash theme={null}
devin-oidc token --audience databricks | python3 -c '
import sys, json, base64
p = sys.stdin.read().strip().split(".")[1]
c = json.loads(base64.urlsafe_b64decode(p + "=="))
print(json.dumps({k: c[k] for k in ("iss", "sub", "aud")}, indent=2))'
```
想定される出力形式:
```json theme={null}
{
"iss": "https://app.devin.ai",
"sub": "org_id:",
"aud": "databricks"
}
```
Enterprise デプロイメントでは、`iss` はカスタムの Devin URL (例: `https://yourcompany.devinenterprise.com`) になります。`iss` と `sub` は出力されたとおりに正確にコピーしてください。生のトークンをチケットやドキュメントに貼り付けないでください。これは以降 60 秒間有効なベアラー認証情報です。
前の手順で得た値に置き換えたうえで、以下を `devin-federation-policy.json` として保存します:
```json theme={null}
{
"description": "Allow Devin sessions to authenticate as the devin-sessions service principal",
"oidc_policy": {
"issuer": "https://",
"audiences": ["databricks"],
"subject": "org_id:"
}
}
```
3 つのフィールドはいずれも完全一致が必要です:
* `issuer` は、スキームを含み末尾にスラッシュを付けない形で、トークンの `iss` と完全に一致している必要があります。
* `audiences` には Devin が要求するオーディエンス (本ガイドでは `databricks`) を含める必要があります。
* `subject` はトークンの `sub` と一致している必要があります。デフォルトの subject は組織 ID であるため、組織内のすべてのセッションがこの principal として認証できます。フェデレーションポリシーは subject をリテラル文字列として照合するため、Databricks ではこの時間粒度が適切です。`devin_id` のようなセッション単位のクレームはセッションごとに値が変わるため、静的なポリシーでは照合できません。
`subject_claim`、`jwks_uri`、`jwks_json` は未設定のままにしてください。Databricks はデフォルトで `sub` クレームを利用し、issuer の `/.well-known/openid-configuration` から JWKS を検出します。
```bash theme={null}
databricks account service-principal-federation-policy create \
--policy-id devin-sessions \
--json @devin-federation-policy.json
```
作成されたことを確認します:
```bash theme={null}
databricks account service-principal-federation-policy list
```
ブループリントが書き込んだ profile はすでにこの service principal を指しているため、リビルドは不要です。続けて [Step 3](#step-3-grant-permissions) に進んでください。
### 再ビルドとバージョンの固定
Databricks のインストールスクリプトと `setup-devin-oidc@main` はいずれもアップストリームの `main` ブランチを追跡するため、フルビルドでは新しいリリースが取り込まれます。一方、[差分ビルド](/ja/onboard-devin/environment/differential-builds)は `initialize` をスキップし、ブループリントが変更されるまではスナップショットにあるバージョンをそのまま維持します。再現性のあるビルドが必要な場合は、`main` ではなくリリースタグからインストーラーを取得し (例: `.../databricks/setup-cli/v1.17.0/install.sh`) 、その CLI バージョンのみをインストールするようにしたうえで、action をコミット SHA に固定してください (`setup-devin-oidc@`) 。
## ステップ3: 権限を付与する
認証で証明できるのは、Devinが誰であるかということだけです。Devinが何を参照・変更できるかは、ワークスペースの権限とUnity Catalogの権限付与 (grant) によって決まり、ブループリントに手を加えることなくいつでも調整できます。作業内容に見合う最小限のプロファイルから始め、必要に応じて慎重に範囲を広げてください。
### 権限プロファイル
| プロファイル | 典型的な作業 | Unity Catalog の権限付与 | ワークスペース権限 |
| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Explore** (ここから開始) | データに関する質問への回答、スキーマのドキュメント化、失敗したジョブの調査、PR でのクエリ修正の提案 | 本番カタログに対する `USE CATALOG`、`USE SCHEMA`、`SELECT`、`BROWSE`。Devin がファイルを参照する必要がある場所には `READ VOLUME` | SQL ウェアハウス 1 つに対する `CAN USE`。Devin に調査させるジョブおよびパイプラインに対する `CAN VIEW` |
| **Build** | サンドボックスでのテーブル、関数、ノートブックの試作、実際の読み取り専用データに対するテストの実行 | 本番環境の Explore の権限に加えて、専用の `devin_dev` カタログまたはスキーマの所有権 (もしくはそれらに対する `ALL PRIVILEGES`) | Explore の権限に加えて、サンドボックスのジョブに対する `CAN MANAGE RUN`。Devin がコンピュートを起動する可能性がある場合は制限的なクラスターポリシー |
| **Operate** | Explore と Build の運用実績が確認できた後の、特定の本番ジョブの再実行または修復 | Explore の権限に加えて、ジョブが書き込む特定のテーブルに対する `MODIFY` | 特定のジョブに対する `CAN MANAGE RUN` (ワークスペース全体ではなくジョブ単位で付与) |
権限付与のステートメントでは、サービスプリンシパルをアプリケーション ID で指定します。
```sql theme={null}
-- Explore: 本番の analytics カタログへの読み取り専用アクセス
GRANT USE CATALOG, BROWSE ON CATALOG analytics TO ``;
GRANT USE SCHEMA, SELECT ON SCHEMA analytics.gold TO ``;
GRANT READ VOLUME ON VOLUME analytics.gold.landing TO ``;
-- Build: Devin が所有し、本番から隔離されたサンドボックス用カタログ
CREATE CATALOG IF NOT EXISTS devin_dev;
ALTER CATALOG devin_dev OWNER TO ``;
```
グループ単位での管理を希望する場合は、service principal を `devin-agents` などの group に追加し、その group に対して権限を付与してください。
コードの変更は、引き続きプルリクエストを経由させてください。Devin は本番データを読み取って問題を把握し、サンドボックス内で対処法を検証できますが、notebook、job 定義、Asset Bundle の変更は、本番環境を直接編集するのではなく、通常のレビュープロセスを通じて反映されます。
## Step 4: Databricks スキルプラグインをインストールする(任意)
Databricks は、コーディングエージェントに Databricks のワークフロー(Asset Bundles、job、SQL、Unity Catalog、Spark)を習得させる [Agent Skills](https://github.com/databricks/databricks-agent-skills) を公開しています。これらを Devin の[プラグイン](/ja/product-guides/plugins)としてインストールすれば、CLI に加えてこうしたノウハウも Devin に持たせられます。
1. **Customize → Plugins** を開き、**Add plugin → From repository** を選択します。
2. リポジトリに `databricks/databricks-agent-skills`、サブディレクトリに `plugins/databricks/claude` を入力します。プラグインのマニフェストはこのサブフォルダ内にあるため、repository root からインストールすると **No plugin manifest found** と表示されます。
3. Step 2 で Organization blueprint を利用した場合は、**Organization** スコープでインストールします。リポジトリブループリントを利用した場合は、代わりにそのリポジトリの `.devin/config.json` にプラグインを宣言してください([inheritance and levels](/ja/cli/extensibility/plugins/overview#inheritance-and-levels) を参照)。こうすれば、CLI を備えたセッションにのみスキルが適用されます。
4. 動作を確認できたら[プラグインを commit にピン留め](/ja/product-guides/plugins#pinning-a-plugin)し、上流の変更がレビューされないままセッションに入り込まないようにします。
このプラグインのコアスキルは、profile を設定するために `databricks auth login` を実行することを推奨しています。ただし、この対話的なブラウザフローは無人の Devin セッションでは完了できず、ここでは不要です。CLI がすでに認証済みであることは、Step 2 の `knowledge` 項目が Devin に伝えます。
## Step 5: 検証
ブループリントのビルドが成功したら、新しいセッションを開始し、Devin に次のコマンドを実行するよう依頼します。
```bash theme={null}
databricks --version
databricks current-user me
```
`current-user me` は、`userName` がそのアプリケーション ID と一致する service principal を返すはずです。CLI がどの認証方式を選択したかを確認するには、次のようにします。
```bash theme={null}
databricks auth describe
```
オプションAの場合は `oauth-m2m`、オプションBの場合は `env-oidc` と報告されます。
認証に成功しても、Devin がデータにアクセスできるとは限りません。ステップ3で付与した権限が適用されていることを確認してください。
```bash theme={null}
databricks catalogs list
databricks warehouses list
databricks grants get catalog
```
`` は、Step 3 で付与したカタログに置き換えてください (使用例では `analytics` を使用しています) 。次に、Devin が `CAN USE` を持つウェアハウスに対して小さな読み取り専用クエリを実行するよう依頼し、Build プロファイルを設定している場合は `devin_dev` でテーブルの作成と削除も依頼してください。Devin が `SELECT` 権限を持たない本番テーブルへのクエリは失敗するはずです。この失敗こそが、権限境界が正しく機能している証拠です。
## トラブルシューティング
| 症状 | 対象 | 原因と対処法 |
| ---------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 認証情報の競合、または認証方式が複数あることを示すエラー | 方式 A | `DATABRICKS_TOKEN`、`DATABRICKS_USERNAME`、および `~/.databrickscfg` のプロファイルを削除してください。複数の認証方式が設定されている場合、CLI はどれを使うか推測しません。 |
| `DATABRICKS_OIDC_TOKEN` が未設定または空 | 方式 B | ラッパーが迂回されたか、インストールされていません。`which databricks` がラッパーを指していること、および `devin-oidc token --audience databricks` が単体で成功することを確認してください。 |
| `invalid_grant`、またはサブジェクトに関するエラー | 方式 B | ポリシーの `subject` がトークンの `sub` と完全には一致していません。Step 2 のクレーム取得スクリプトを再実行し、1 文字ずつ突き合わせてください。 |
| オーディエンスに関するエラー | 方式 B | ポリシーの `audiences` に、ラッパーが要求するオーディエンスが含まれていません。どちらも既定値は `databricks` です。同一に保ってください。 |
| issuer、JWKS、署名に関するエラー | 方式 B | `issuer` に誤記がある (末尾のスラッシュ、`http`、ホスト名の誤り) か、Databricks から `https:///.well-known/jwks.json` に到達できません。ネットワーク外からこの URL を読み込み、公開されていることを確認してください。 |
| トークンの有効期限切れ | 方式 B | Devin のアイデンティティトークンの有効期間は 60 秒です。手動でトークンを発行せず、ラッパーを利用してください。 |
| CLI が `env-oidc` を認識しない | 方式 B | スナップショットに古い CLI (またはレガシーの Python 製 `databricks-cli` パッケージ) が入っています。ブループリントから古いパッケージを削除し、再ビルドしてください。 |
| 認証は成功するが `catalogs list` が空、またはクエリが拒否される | 両方 | プリンシパルは認証済みですが、認可されていません。ワークスペースへの割り当て (Step 1) と Unity Catalog の権限付与 (Step 3) を `databricks grants get catalog ` で確認してください。 |
| 接続のタイムアウトまたは DNS の名前解決失敗 | 両方 | ワークスペースのホストに Devin から到達できません。該当ホスト (必要であればアカウントのホストも) を Devin の[ネットワークポリシー](/ja/product-guides/security-profiles)に追加してください。 |
## サポート
Databricks 側のセットアップ (service principal、OAuth シークレット、フェデレーション ポリシー、Unity Catalog) については、[Databricks の認証ドキュメント](https://docs.databricks.com/aws/en/dev-tools/auth/)を参照してください (必要に応じて Azure 版または GCP 版に切り替えてください) 。Devin 側のセットアップ (ブループリント、OIDC、プラグイン、ネットワークポリシー) については、[support@cognition.ai](mailto:support@cognition.ai) または担当の account team までお問い合わせください。