Databricksを使用して リソースへの無人アクセスをサービスプリンシパルで承認するOAuth

このトピックでは、Databricks DatabricksCLIコマンドを自動化するとき、または無人プロセスから実行されるコードから を呼び出すときにリソースへのアクセスを承認する手順と詳細について説明します。DatabricksRESTAPIs

Databricks は、UI の外部で Databricks リソースと対話する際のユーザー認証と認証の優先プロトコルとして OAuth を使用します。 Databricks は、OAuth の認証方法の一部として生成されるアクセス トークンの更新を自動化するための統合クライアント認証ツールも提供しています。 これは、サービスプリンシパル とユーザー アカウントにも当てはまりますが、操作の一部としてアクセスする必要がある Databricks リソースに対して、適切なアクセス許可と特権を使用してサービスプリンシパルを構成する必要があります。

詳細については、「 Databricks リソースへのアクセスの承認」を参照してください。

Databricks サービスプリンシパルを使用する場合の承認と認証にはどのようなオプションがありますか?

このトピックでは、 承認 とは、委任を通じて特定の Databricks リソースへのアクセスをネゴシエートするために使用されるプロトコル (OAuth) を指します。 認証 とは、資格情報が表現、送信、および検証されるメカニズムを指し、この場合は アクセストークン です。

Databricks はOAuth 2.0 ベースの承認を使用してDatabricksコマンド ラインまたはコードからアカウントとワークスペース リソースへのアクセスを有効にします。これらのリソースにアクセスするアクセス許可を持つサービスプリンシパルの代わりに。Databricksサービスプリンシパルが構成され、CLI コマンドを実行したり、 を呼び出したりするときにその資格情報が検証されると、参加しているツールまたはRESTAPI OAuthにSDK トークンが付与され、その時点からサービスプリンシパルに代わってトークンベースの認証が実行されます。OAuthアクセストークンの有効期間は1時間で、その後、関係するツールまたはSDKは、1時間有効な新しいトークンを取得するための自動バックグラウンド試行を行います。

Databricks では、 OAuthを使用してサービスプリンシパルのアクセスを承認する 2 つの方法がサポートされています。

• Databricks 統合クライアント認証サポートを使用して、ほとんどの場合自動的に行われます。 特定の Databricks SDK (Databricks Terraform SDK など) とツールを使用している場合は、この簡略化されたアプローチを使用します。 サポートされているツールと SDK については、「 Databricks 統合クライアント認証」を参照してください。 このアプローチは、自動化やその他の無人プロセス シナリオに適しています。
• 手動で、OAuth コード検証ツール/チャレンジのペアと認証コードを直接生成し、それらを使用して、構成で提供する初期 OAuth トークンを作成します。 Databricks 統合クライアント認証でサポートされている API を使用していない場合は、この方法を使用します。 この場合、使用しているサードパーティのツールやAPIに固有のアクセストークンの更新を処理するための独自のメカニズムを開発する必要があるかもしれません。 詳しくは、OAuth サービスプリンシパル認証用のアクセス・トークンを手動で生成して使用するを参照してください。

開始する前に、 Databricks サービスプリンシパルを構成し、オートメーション コードまたはコマンドが要求したときに使用する必要があるリソースにアクセスするための適切なアクセス許可を割り当てる必要があります。

前提条件: サービスプリンシパルを作成する

アカウント admins とワークスペース admins は、サービスプリンシパルを作成できます。 この手順では、 Databricks ワークスペースでサービスプリンシパルを作成する方法について説明します。 Databricksアカウントコンソールの詳細については、「アカウントでサービスプリンシパルを管理する」を参照してください。

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

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

ステップ 1: サービスプリンシパルに権限を割り当てる

1. サービスプリンシパルの名前をクリックして、その詳細ページを開きます。
2. 「構成 」タブで、このワークスペースに対してサービスプリンシパルに付与する各権限の横にあるボックスを選択し、「 更新 」をクリックします。
3. [ アクセス許可 ] タブで、このサービスプリンシパルを管理および使用する任意の Databricks ユーザー、サービスプリンシパル、およびグループにアクセス権を付与します。 「サービスプリンシパルでの役割の管理」を参照してください。

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

OAuth を使用して Databricks リソースへのアクセスを承認する前に、まず OAuth シークレットを作成し、これを使用して認証用の OAuth アクセス トークンを生成する必要があります。 サービスプリンシパルは、最大 5 つの OAuth シークレットを持つことができます。

アカウント管理者とワークスペース管理者は、サービスプリンシパルのOAuthシークレットを作成できます。

1. サービスプリンシパルの詳細ページで、[ シークレット ] タブをクリックします。

2. [ OAuthシークレット ] で、[ シークレットを生成 ] をクリックします。

   

3. 表示された シークレット と クライアントID をコピーし、[ 完了 ] をクリックします。

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

アカウント 管理者は、アカウント コンソールのサービスプリンシパル 詳細ページから OAuth シークレットを生成することもできます。

1. アカウント管理者として、アカウントコンソールにログインします。

2. [ ユーザー管理] をクリックします。

3. [ サービスプリンシパル ] タブで、サービスプリンシパルを選択します。

4. [ OAuthシークレット ] で、[ シークレットを生成 ] をクリックします。

   

5. 表示された シークレット と クライアントID をコピーし、[ 完了 ] をクリックします。

注記

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

ステップ 3: OAuth 認証を使用する

統合クライアント認証ツールで OAuth 認証を使用するには、次の関連する環境変数 ( .databrickscfg フィールド、Terraform フィールド、または Config フィールド) を設定する必要があります。

• アカウント操作の https://accounts.cloud.databricks.com またはターゲット ワークスペース URL (ワークスペース操作の https://dbc-a1b2345c-d6e7.cloud.databricks.com など) として指定される Databricks ホスト。
• Databricksアカウント操作用のDatabricksアカウントID。
• サービスプリンシパルのクライアントID。
• サービスプリンシパルのシークレット。

OAuth サービスプリンシパル認証を実行するには、参加するツールまたはSDKに基づいて、コード内に以下を統合します。

Environment

To use environment variables for a specific Databricks authentication type with a tool or SDK, see Authorizing access to Databricks resources or the tool’s or SDK’s documentation. See also Environment variables and fields for client unified authentication and the Default methods for client unified authentication.

For account-level operations, set the following environment variables:

• DATABRICKS_HOST, set to the Databricks account console URL, https://accounts.cloud.databricks.com.
• DATABRICKS_ACCOUNT_ID
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

For workspace-level operations, set the following environment variables:

• DATABRICKS_HOST, set to the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

Profile

Create or identify a Databricks configuration profile with the following fields in your .databrickscfg file. If you create the profile, replace the placeholders with the appropriate values. To use the profile with a tool or SDK, see Authorizing access to Databricks resources or the tool’s or SDK’s documentation. See also Environment variables and fields for client unified authentication and the Default methods for client unified authentication.

For account-level operations, set the following values in your .databrickscfg file. In this case, the Databricks account console URL is https://accounts.cloud.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>

For workspace-level operations, set the following values in your .databrickscfg file. In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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

CLI

For the Databricks CLI, do one of the following:

• Set the environment variables as specified in this article’s “Environment” section.
• Set the values in your .databrickscfg file as specified in this article’s “Profile” section.

Environment variables always take precedence over values in your .databrickscfg file.

See also OAuth machine-to-machine (M2M) authentication.

Connect

注記

OAuth service principal authentication is supported on the following Databricks Connect versions:

• For Python, Databricks Connect for Databricks Runtime 13.1 and above.

• For Scala, Databricks Connect for Databricks Runtime 13.3 LTS and above.

For Databricks Connect, you can do one of the following:

• Set the values in your .databrickscfg file for Databricks workspace-level operations as specified in this article’s “Profile” section. Also set the cluster_id environment variable in your profile to your workspace instance URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.
• Set the environment variables for Databricks workspace-level operations as specified in this article’s “Environment” section. Also set the DATABRICKS_CLUSTER_ID environment variable to your workspace instance URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.

Values in your .databrickscfg file always take precedence over environment variables.

To initialize the Databricks Connect client with these environment variables or values in your .databrickscfg file, see Compute configuration for Databricks Connect.

VS Code

For the Databricks extension for Visual Studio Code, do the following:

1. Set the values in your .databrickscfg file for Databricks workspace-level operations as specified in this article’s “Profile” section.
2. In the Configuration pane of the Databricks extension for Visual Studio Code, click Configure Databricks.
3. In the Command Palette, for Databricks Host, enter your workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com, and then press Enter.
4. In the Command Palette, select your target profile’s name in the list for your URL.

For more details, see Set up authorization for the Databricks extension for Visual Studio Code.

Terraform

For account-level operations, for default authentication:

provider "databricks" {
  alias = "accounts"
}

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console or some other configuration store, such as HashiCorp Vault. See also Vault Provider). In this case, the Databricks account console URL is https://accounts.cloud.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>
}

For workspace-level operations, for default authentication:

provider "databricks" {
  alias = "workspace"
}

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console or some other configuration store, such as HashiCorp Vault. See also Vault Provider). In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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

For more information about authenticating with the Databricks Terraform provider, see Authentication.

Python

For account-level operations, use the following for default authentication:

Python

from databricks.sdk import AccountClient

a = AccountClient()
# ...

For direct configuration, use the following, replacing the retrieve placeholders with your own implementation, to retrieve the values from the console or other configuration store, such as AWS Systems Manager Parameter Store. In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Python

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()
)
# ...

For workspace-level operations, specifically default authentication:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

For direct configuration, replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store. In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Python

from databricks.sdk import WorkspaceClient

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

For more information about authenticating with Databricks tools and SDKs that use Python and that implement Databricks client unified authentication, see:

• Set up the Databricks Connect client for Python
• Set up authorization for the Databricks extension for Visual Studio Code
• Authenticate the Databricks SDK for Python with your Databricks account or workspace

Java

For account-level operations, for default authentication:

Java

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Java

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);
// ...

For workspace-level operations using default authentication:

Java

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Java

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);
// ...

For more information about authenticating with Databricks tools and SDKs that use Java and implement Databricks client unified authentication, see:

• Set up the Databricks Connect client for Scala (the Databricks Connect client for Scala uses the included Databricks SDK for Java for authentication)
• Authenticate the Databricks SDK for Java with your Databricks account or workspace

Go

For account-level operations using default authentication:

Go

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Go

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

For workspace-level operations using default authentication:

Go

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Go

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

For more information about authenticating with Databricks tools and SDKs that use Go and that implement Databricks client unified authentication, see Authenticate the Databricks SDK for Go with your Databricks account or workspace.

OAuth サービスプリンシパル authentication 用のアクセス トークンを手動で生成して使用する

Databricksクライアント統合認証Databricks 標準を実装する ツールと SDKDatabricksOAuth は、OAuth サービスプリンシパル 認証に必要な アクセストークンを自動的に生成、更新、および使用します。

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

サービスプリンシパルのクライアントIDとOAuth OAuthシークレットを使用して、アカウントレベルのRESTAPIs とワークスペースレベルの の両方に対する認証のための アクセストークンを要求します。RESTAPIsアクセストークンの有効期限は1時間です。 有効期限が切れたら、新しい OAuth アクセス トークンを要求する必要があります。 OAuth アクセストークンのスコープは、トークンを作成するレベルによって異なります。 トークンは、次のように、アカウントレベルまたはワークスペースレベルで作成できます。

• サービスプリンシパルがアクセスできるアカウントとワークスペース内のアカウントレベルとワークスペースレベルの REST APIs を呼び出すには、 アカウントレベルでアクセストークンを手動で生成します。
• サービスプリンシパルがアクセスできるワークスペースの 1 つだけ内で REST APIs を呼び出すには、そのワークスペースのみの ワークスペースレベルでアクセストークンを手動で生成 します。

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

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

1. アカウント管理者として、アカウントコンソールにログインします。

2. 右上のユーザー名の横にある下向きの矢印をクリックします。

3. アカウントIDを コピーしてください。

4. 次のURLの<my-account-id>をコピーしたアカウントIDに置き換えて、トークンエンドポイントのURLを作成します。

   https://accounts.cloud.databricks.com/oidc/accounts/<my-account-id>/v1/token

5. curlなどのクライアントを使用して、トークンエンドポイントURL、サービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）、および作成したサービスプリンシパルのOAuthシークレットを含むOAuthアクセストークンをリクエストします。all-apisスコープは、サービスプリンシパルにアクセス権が付与されているすべてのDatabricks REST APIにアクセスするために使用できるOAuthアクセストークンをリクエストします。

   • <token-endpoint-URL>を前述のトークンエンドポイントのURLに置き換えます。
   • <client-id>をサービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）に置き換えます。
   • <client-secret>を、作成したサービスプリンシパルのOAuthシークレットに置き換えます。
   Bash

   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'

   これにより、次のようなレスポンスが生成されます。

   JSON

   {
     "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   レスポンスからaccess_tokenをコピーします。

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

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

1. トークン エンドポイント URL を作成するには、 https://<databricks-instance> を Databricks デプロイの ワークスペース URL に置き換えます。

   https://<databricks-instance>/oidc/v1/token

2. curlなどのクライアントを使用して、トークンエンドポイントURL、サービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）、および作成したサービスプリンシパルのOAuthシークレットを含むOAuthアクセストークンをリクエストします。all-apisスコープは、トークンをリクエストしているワークスペース内で、サービスプリンシパルにアクセス権が付与されているすべてのDatabricks REST APIにアクセスするために使用できるOAuthアクセストークンをリクエストします。

   • <token-endpoint-URL>を前述のトークンエンドポイントのURLに置き換えます。
   • <client-id>をサービスプリンシパルのクライアントID（アプリケーションIDとも呼ばれます）に置き換えます。
   • <client-secret>を、作成したサービスプリンシパルのOAuthシークレットに置き換えます。
   Bash

   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'

   これにより、次のようなレスポンスが生成されます。

   JSON

   {
     "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   レスポンスからaccess_tokenをコピーします。

Databricks REST API を呼び出す

アクセス OAuthトークンを使用して、 アカウントDatabricksRESTAPIsレベルの および ワークスペース レベルのRESTAPIs に対して認証できます。サービスプリンシパルは、アカウントレベルの REST APIsを呼び出すためにアカウント管理者権限を持っている必要があります。

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

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

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

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

Bash

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.cloud.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に置き換えます。

Bash

export OAUTH_TOKEN=<oauth-access-token>

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

追加のリソース

• サービスプリンシパル
• Databricks ID モデルの概要
• 認証とアクセス制御に関する追加情報