サービスプリンシパルを使用して Databricks (OAuth M2M) で認証する

この記事では、Databricksサービスプリンシパルを作成し、それを使用してターゲットエンティティを認証する方法について説明します。

注：

サービスプリンシパルのOAuth認証情報を管理するには、アカウント管理者である必要があります。

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

サービスプリンシパルは、アカウント内で直接作成したり、ワークスペースから作成したりすることができます。ワークスペースで作成されたサービスプリンシパルは、自動的にアカウントに追加されます。ワークスペースでIDフェデレーションを有効にしている場合、Databricksでは、アカウント内でサービスプリンシパルを作成してワークスペースに割り当てることをおすすめします。IDフェデレーションを有効にしておらず、ワークスペースレベルでサービスプリンシパルを使用する場合は、ワークスペースからサービスプリンシパルを作成する必要があります。

アカウントコンソールを使用してサービスプリンシパルをアカウントに追加するには、次の手順を実行します。

アカウント管理者として、アカウントコンソールにログインします。
[ユーザー管理]をクリックします。
[サービスプリンシパル] タブで、[サービスプリンシパルの追加] をクリックします。
サービスプリンシパルの名前を入力します。
[追加] をクリックします。
オプションとして、[ロール] タブで、[アカウント管理者] をオンにして、DatabricksのアカウントレベルのAPIを呼び出します。

サービスプリンシパルをIDフェデレーションワークスペースに割り当てることができるようになりました。

アカウントコンソールサイドバーで、[ワークスペース] をクリックします。
ワークスペース名をクリックします。
[権限] タブで、[権限を追加] をクリックします。
サービスプリンシパルを検索して選択し、権限レベル（ワークスペースユーザーまたは管理者）を割り当て、[保存] をクリックします。

ワークスペース管理者として、Databrickワークスペースにログインします。
Databricksワークスペースの上部のバーにあるユーザー名をクリックし、[設定]を選択します。
[IDとアクセス] タブをクリックします。
サービスプリンシパルの横にある [管理] をクリックします。
[サービスプリンシパルの追加] をクリックします。
検索ボックスのドロップダウン矢印をクリックし、[新規追加] をクリックします。
サービスプリンシパルの名前を入力します。
[追加] をクリックします。

サービスプリンシパルはワークスペースとDatabricksアカウントの両方に追加されます。

ステップ2: ワークスペースレベルのアクセス許可をDatabricksサービスプリンシパルに割り当てる

ワークスペースの管理コンソールがまだ開いていない場合は、上部のバーにあるユーザー名をクリックし、[設定] をクリックします。
[IDとアクセス] タブをクリックします。
サービスプリンシパルの横にある [管理] をクリックします。
Databricks サービスプリンシパルの名前をクリックして、その設定ページを開きます。
[構成] タブで、Databricksサービスプリンシパルがこのワークスペースに対して持つ必要のある各権限の横にあるチェックボックスをオンにし、[更新] をクリックします。
[権限] タブで、このDatabricksサービスプリンシパルを管理および使用するすべてのDatabricksユーザー、サービスプリンシパル、およびグループにアクセス権を付与します。「サービスプリンシパルのロールの管理」を参照してください。

ステップ3: サービスプリンシパルのOAuthシークレットを作成する

OAuthを使用してDatabricksを認証する前に、まずOAuthアクセストークンの生成に使用するOAuthシークレットを作成する必要があります。サービスプリンシパルには、最大5つのOAuthシークレットを設定できます。アカウント管理者とワークスペース管理者は、サービスプリンシパルのOAuthシークレットを作成できます。

アカウント管理者として、アカウントコンソールにログインします。
[ユーザー管理]をクリックします。
[サービスプリンシパル] タブで、サービスプリンシパルを選択します。
[OAuthシークレット] で、[シークレットを生成] をクリックします。
表示されたシークレットとクライアントIDをコピーし、[完了] をクリックします。

シークレットは作成中に一度だけ明らかにされます。クライアントID は、サービスプリンシパルのアプリケーションIDと同じです。

ワークスペースの管理コンソールがまだ開いていない場合は、上部のバーにあるユーザー名をクリックし、[設定] をクリックします。
[IDとアクセス] タブをクリックします。
サービスプリンシパルの横にある [管理] をクリックします。
Databricks サービスプリンシパルの名前をクリックして、その設定ページを開きます。
[シークレット] タブをクリックします。
[OAuthシークレット] で、[シークレットを生成] をクリックします。
表示されたシークレットとクライアントIDをコピーし、[完了] をクリックします。

シークレットは作成中に一度だけ明らかにされます。クライアントID は、サービスプリンシパルのアプリケーションIDと同じです。

注：

サービスプリンシパルでクラスターやSQLウェアハウスを使用できるようにするには、サービスプリンシパルにこれらへのアクセス権を付与する必要があります。詳しくは、「コンピュート権限」または「SQLウェアハウスを管理する」を参照してください。

OAuth M2M認証の設定を完了する

OAuth M2M認証の構成を完了するには、以下に挙げられた関連する環境変数、.databrickscfgフィールド、Terraformフィールド、またはConfigフィールドを設定する必要があります。

Databricksホスト。アカウント操作の場合はhttps://accounts.gcp.databricks.comを、ワークスペース操作の場合はターゲットワークスペースのURL（例：https://1234567890123456.7.gcp.databricks.com）を指定します。
Databricksアカウント操作用のDatabricksアカウントID。
サービスプリンシパルのクライアントID。
サービスプリンシパルのシークレット。

OAuth M2M認証を実行するには、参加しているツールまたはSDKに基づいて、コード内に以下を統合します。

ツールまたはで特定の認証タイプに環境変数を使用するには、DatabricksSDK DatabricksAPIsツールとの認証またはツールまたはSDK のドキュメントを参照してください。クライアント統合認証の環境変数とフィールドおよびクライアント統合認証のデフォルトの認証方法も参照してください。

アカウントレベルの操作では、以下の環境変数を設定します。

DATABRICKS_HOST：DatabricksアカウントのコンソールURL（https://accounts.gcp.databricks.com）に設定されます。
DATABRICKS_ACCOUNT_ID
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

ワークスペースレベルの操作では、以下の環境変数を設定します。

DATABRICKS_HOSTをDatabricksワークスペースのURLに設定します（例：https://1234567890123456.7.gcp.databricks.com）。
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

Databricks 構成プロファイルを作成または識別し、 .databrickscfg ファイルに次のフィールドを含めます。プロファイルを作成する場合は、プレースホルダを適切な値に置き換えます。ツールまたはSDKでプロファイルを使用するには、DatabricksツールとAPIsの認証、またはツールまたはSDKのドキュメントを参照してください。クライアント統合認証の環境変数とフィールドおよびクライアント統合認証のデフォルトの認証方法も参照してください。

アカウントレベルの操作では、.databrickscfgファイルに以下の値を設定します。この場合、DatabricksアカウントのコンソールURLは https://accounts.gcp.databricks.com です。

[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

ワークスペースレベルの操作では、.databrickscfgファイルに以下の値を設定します。この場合、ホストはDatabricksのワークスペースのURLです。例: https://1234567890123456.7.gcp.databricks.com

[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

Databricks CLIの場合は、次のいずれかを実行します。

この記事の「環境」セクションで指定されているように環境変数を設定します。
この記事の「プロフィール」セクションで指定されているように、.databrickscfgファイルの値を設定します。

環境変数は常に.databrickscfgファイルの値よりも優先されます。

OAuthマシン間 (M2M) 認証も参照してください。

注：

OAuth M2M認証は、Databricks Runtime 13.3 LTS以上のDatabricks Connect for PythonおよびScalaでサポートされています。

Databricks Connectでは、次のいずれかを実行できます。

この記事の「プロファイル」セクションで指定されているように、Databricksワークスペースレベルの操作のために.databrickscfgファイルの値を設定します。また、プロファイルのcluster_id環境変数をワークスペースインスタンスURL (例:https://1234567890123456.7.gcp.databricks.com) に設定します。
この記事の「環境」セクションで指定されているように、Databricksワークスペースレベルの操作のために環境変数を設定します。また、DATABRICKS_CLUSTER_ID環境変数をワークスペースインスタンスURL (例: https://1234567890123456.7.gcp.databricks.com ) に設定します。

.databrickscfgファイルの値は、常に環境変数よりも優先されます。

.databrickscfgファイル内のこれらの環境変数もしくは値を使用してDatabricks Connectクライアントを初期化するには、次のいずれかを参照してください。

Pythonの場合は、「Pythonの接続プロパティを構成する」を参照してください。
Scalaの場合は、「Scalaの接続プロパティを構成する」を参照してください。

DatabricksのVisual Studio Code拡張機能の場合は、次のようにします。

この記事の「プロファイル」セクションで指定されているように、Databricksワークスペースレベルの操作のために.databrickscfgファイルの値を設定します。
DatabricksのVisual Studio Code拡張機能の [構成] ウィンドウで、[Databricksを構成する] をクリックします。
[コマンド] パレットのDatabricks Hostに、ワークスペースURLを https://1234567890123456.7.gcp.databricks.com などと入力し、Enterを押します。
[コマンド] パレットで、URLのリストからターゲットプロファイルの名前を選択します。

詳細については、「Visual Studio CodeのDatabricks拡張機能の認証設定」を参照してください。

アカウントレベルのオペレーションの場合、デフォルトの認証の場合:

provider "databricks" {
  alias = "accounts"
}

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（HashiCorp Vaultなど）から値を取得します。「Vaultのプロバイダー」も参照してください。この場合、DatabricksアカウントのコンソールURLはhttps://accounts.gcp.databricks.comとなります。

provider "databricks" {
  alias         = "accounts"
  host          = <retrieve-account-console-url>
  account_id    = <retrieve-account-id>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

ワークスペースレベルの操作の場合、デフォルト認証の場合:

provider "databricks" {
  alias = "workspace"
}

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（HashiCorp Vaultなど）から値を取得します。「Vaultのプロバイダー」も参照してください。この場合、ホストはDatabricksワークスペースのURLとなります（例：https://1234567890123456.7.gcp.databricks.com）。

provider "databricks" {
  alias         = "workspace"
  host          = <retrieve-workspace-url>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Databricks Terraformプロバイダーによる認証の詳細については、「認証」を参照してください。

アカウントレベルのオペレーションでは、デフォルトの認証に以下を使用します。

from databricks.sdk import AccountClient

a = AccountClient()
# ...

直接構成の場合、以下を使用して、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、DatabricksアカウントのコンソールURLはhttps://accounts.gcp.databricks.comとなります。

from databricks.sdk import AccountClient

a = AccountClient(
  host          = retrieve_account_console_url(),
  account_id    = retrieve_account_id(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

ワークスペースレベルの操作、特にデフォルトの認証の場合:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、ホストはDatabricksワークスペースのURLとなります（例：https://1234567890123456.7.gcp.databricks.com）。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

を使用し、Databricks PythonDatabricksクライアント統合認証を実装するツールと SDK を使用した認証の詳細については以下を参照してください。

アカウントレベルのオペレーションの場合、デフォルトの認証の場合:

import com.databricks.sdk.AccountClient;
// ...
AccountClient a = new AccountClient();
// ...

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、DatabricksアカウントのコンソールURLはhttps://accounts.gcp.databricks.comとなります。

import com.databricks.sdk.AccountClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveAccountConsoleUrl())
  .setAccountId(retrieveAccountId())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
AccountClient a = new AccountClient(cfg);
// ...

ワークスペースレベルの操作の場合、デフォルト認証の場合:

import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、ホストはDatabricksワークスペースのURLとなります（例：https://1234567890123456.7.gcp.databricks.com）。

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveWorkspaceUrl())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

Javaを使用し、Databricksクライアントの統合認証を実装しているDatabricksツールおよびSDKでの認証の詳細については、以下を参照してください。

Scala用Databricks Connectクライアントのセットアップ（Scala用Databricks Connectクライアントは付属のDatabricks SDK for Javaを使用して認証）
Databricks アカウントまたはワークスペースを使用して Java 用 Databricks SDK を認証する

アカウントレベルのオペレーションの場合、デフォルトの認証の場合:

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient())
// ...

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、DatabricksアカウントのコンソールURLはhttps://accounts.gcp.databricks.comとなります。

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
  Host:         retrieveAccountConsoleUrl(),
  AccountId:    retrieveAccountId(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

ワークスペースレベルの操作の場合、デフォルト認証の場合:

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient())
// ...

直接構成の場合、retrieveプレースホルダーを独自の実装に置き換え、コンソールやその他の構成ストア（Google Cloud Secret Managerなど）から値を取得します。この場合、ホストはDatabricksワークスペースのURLとなります（例：https://1234567890123456.7.gcp.databricks.com）。

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient(&databricks.Config{
  Host:         retrieveWorkspaceUrl(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

Go を使用し、クライアント統合認証を実装するDatabricks ツールと SDKDatabricks を使用した認証の詳細については、「アカウントまたはワークスペースで Go のを認証DatabricksSDKDatabricks する」を参照してください。

OAuth M2M認証用のアクセストークンを手動で生成して使用する

クライアント統合認証Databricks 標準を実装するDatabricks ツールとSDKは、DatabricksOAuthOAuth M2M認証に必要なユーザーに代わってアクセストークンを自動的に生成、更新、および使用します。

OAuth M2M認証用にDatabricks OAuthアクセストークンを手動で生成、更新、または使用する必要がある場合は、このセクションの手順に従ってください。

ステップ1: DatabricksサービスプリンシパルとOAuthシークレットを作成する

まだDatabricksのサービスプリンシパルとそれに対応するOAuthシークレットがない場合は、この記事の冒頭のステップ1〜3に従って作成してください。

ステップ2: アクセストークンを手動で生成する

DatabricksサービスプリンシパルのクライアントIDとOAuthシークレットを使用して、アカウントレベルのREST APIとワークスペースレベルのREST APIの両方に対して認証を行うためのOAuthアクセストークンをリクエストします。このアクセストークンの有効期間は1時間です。その後は、新しいOAuthアクセストークンをリクエストする必要があります。OAuthアクセストークンの範囲は、トークンを作成するレベルによって異なります。トークンは、以下のように、アカウントレベルまたはワークスペースレベルのいずれかで作成できます。

サービスプリンシパルがアクセスできるアカウントおよびワークスペース内で、アカウントレベルやワークスペースレベルのREST APIを呼び出すには、アカウントレベルでアクセストークンを手動で生成します。
サービスプリンシパルがアクセスできるワークスペースのうちの1つだけからREST APIを呼び出すには、そのワークスペースだけのアクセストークンをワークスペースレベルで手動生成します。

アカウントレベルのアクセストークンを手動で生成する

アカウントレベルで作成されたOAuthアクセストークンは、アカウント内のDatabricks REST APIと、サービスプリンシパルがアクセスできるすべてのワークスペースに対して使用できます。

アカウント管理者として、アカウントコンソールにログインします。
右上のユーザー名の横にある下向きの矢印をクリックします。
アカウントIDをコピーしてください。
次のURLの<my-account-id>をコピーしたアカウントIDに置き換えて、トークンエンドポイントのURLを作成します。
```
https://accounts.gcp.databricks.com/oidc/accounts/<my-account-id>/v1/token
```
curlなどのクライアントを使用して、トークンエンドポイントURL、サービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）、および作成したサービスプリンシパルのOAuthシークレットを含むOAuthアクセストークンをリクエストします。all-apisスコープは、サービスプリンシパルにアクセス権が付与されているすべてのDatabricks REST APIにアクセスするために使用できるOAuthアクセストークンをリクエストします。
- <token-endpoint-URL>を前述のトークンエンドポイントのURLに置き換えます。
- <client-id>をサービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）に置き換えます。
- <client-secret>を、作成したサービスプリンシパルのOAuthシークレットに置き換えます。
```
export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'
```
これにより、次のようなレスポンスが生成されます。
```
{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
レスポンスからaccess_tokenをコピーします。
ステップ3: Databricks REST APIを呼び出すに進みます。

ワークスペースレベルのアクセストークンを手動で生成する

ワークスペースレベルで作成されたOAuthアクセストークンは、サービスプリンシパルがアカウント管理者であっても、他のワークスペースのメンバーであっても、そのワークスペース内のREST APIにのみアクセスできます。

https://<databricks-instance>をDatabricksデプロイメントのワークスペースURLに置き換えて、トークンエンドポイントURLを構築します。
```
https://<databricks-instance>/oidc/v1/token
```
curlなどのクライアントを使用して、トークンエンドポイントURL、サービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）、および作成したサービスプリンシパルのOAuthシークレットを含むOAuthアクセストークンをリクエストします。all-apisスコープは、トークンをリクエストしているワークスペース内で、サービスプリンシパルにアクセス権が付与されているすべてのDatabricks REST APIにアクセスするために使用できるOAuthアクセストークンをリクエストします。
- <token-endpoint-URL>を前述のトークンエンドポイントのURLに置き換えます。
- <client-id>をサービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）に置き換えます。
- <client-secret>を、作成したサービスプリンシパルのOAuthシークレットに置き換えます。
```
export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'
```
これにより、次のようなレスポンスが生成されます。
```
{
  "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
レスポンスからaccess_tokenをコピーします。

ステップ3: Databricks REST APIを呼び出す

OAuthアクセストークンを使用して、DatabricksアカウントレベルのREST APIおよびワークスペースレベルのREST APIを認証できるようになりました。アカウントレベルのREST APIを呼び出すには、サービスプリンシパルがアカウント管理者である必要があります。

Bearer認証を使用して、ヘッダーにトークンを含めることができます。このアプローチは、 curlまたは構築する任意のクライアントで使用できます。

アカウントレベルの REST APIリクエストの例

この例では、Bearer認証を使用して、アカウントに関連付けられているすべてのワークスペースのリストを取得します。

<oauth-access-token> を、前のステップでコピーしたサービスプリンシパルのOAuthアクセストークンに置き換えます。
<account-id>をアカウントIDに置き換えます。

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.gcp.databricks.com/api/2.0/accounts/<account-id>/workspaces'

ワークスペースレベルのREST APIリクエストの例

この例では、Bearer 認証を使用して、指定されたワークスペースで利用可能なすべてのクラスターを一覧表示します。

<oauth-access-token> を、前のステップでコピーしたサービスプリンシパルのOAuthアクセストークンに置き換えます。
<workspace-URL>を、 dbc-a1b2345c-d6e7.cloud.databricks.comのような形式のベースとなるワークスペースURLに置き換えます。

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

サービスプリンシパルを使用して Databricks (OAuth M2M) で認証する

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

ステップ2: ワークスペースレベルのアクセス許可をDatabricksサービスプリンシパルに割り当てる

ステップ3: サービスプリンシパルのOAuthシークレットを作成する

OAuth M2M認証の設定を完了する

OAuth M2M認証用のアクセストークンを手動で生成して使用する

ステップ1: DatabricksサービスプリンシパルとOAuthシークレットを作成する

ステップ2: アクセストークンを手動で生成する

アカウントレベルのアクセストークンを手動で生成する

ワークスペースレベルのアクセストークンを手動で生成する

ステップ3: Databricks REST APIを呼び出す

アカウントレベルの REST APIリクエストの例

ワークスペースレベルのREST APIリクエストの例

関連リソース