Google IDトークンによる認証

Databricks REST APIsに対して認証するには、次の 2 つのオプションがあります。

• Databricks 個人用アクセス トークン。 これらはワークスペースレベルのREST APIsにのみ使用できます。
• OpenID Connect (OIDC) トークン。 これらはすべての Databricks REST APIsに使用できます。

OpenID Connect (OIDC) トークン は、認証をサポートするためのオープンスタンダードです。 OIDC 1.0 は、OAuth 2.0 プロトコルの上にある単純な ID レイヤーです。 これにより、アプリケーションは、OAuth 承認サーバーによって実行される認証に基づいてユーザーの ID を検証できます。 アプリケーションは、OIDC トークンからユーザーの基本プロファイル情報を取得することもできます。 OIDC トークン by デフォルト は 1 時間後に期限切れになります。

important

Databricks REST APIs は、一般に Google ID トークンと呼ばれる Google 発行の OIDC トークンのみをサポートします。 混乱を避けるため、この記事の残りの部分では、 OIDC トークン ではなく Google ID トークン という用語を使用します。

この記事では、 Databricks REST APIs を使用するための認証手順と、必要な Google Cloud サービス アカウントを作成してこれらのアカウントのトークンを生成する方法について説明します。

1 つの Google ID トークンをアカウント単位のAPIsまたはワークスペース単位のAPIsに使用できますが、両方の目的に使用することはできません。ワークスペースレベルとアカウントレベルの APIs のトークンを設定する手順はほぼ同じです。 重要な違いは、説明書で説明されています。

本番運用環境の場合、 Databricks は 2 つのサービス アカウントを使用して Databricks REST APIsを操作することをお勧めします。

• ワークロードを実行するための 1 つのサービス アカウント (SA-1) を作成します。
• Databricks と Google Cloud のリソースに対する権限を保持するために、別のサービス アカウント (SA-2) を作成します。
• SA-2 になり すま して SA-2 を呼び出す権限を SA-1 に付与 Databricks REST APIs。

この偽装モデルでは、1 つのチームがワークロードのセキュリティを管理し、別のチームがリソースのセキュリティを管理できます。 偽装のアクセス許可は必要な場合にのみ付与するため、このアプローチは組織にセキュリティと柔軟性を提供します。

この記事では、本番運用の利用について、これらの手順を実行する方法について詳しく説明します。 これらの手順は、次のいずれかの戦略を使用して、本番運用以外の使用およびテストに適合させることができます。

• Google ユーザー アカウント を使用して SA-2 になりすます。ユーザーアカウントには、 roles/iam.serviceAccountTokenCreatorの役割が必要です。
• SA-1 と SA-2 の両方に 1 つの Google Cloud サービス アカウント を使用します。

アカウントレベルの APIs とワークスペースレベルの APIs

Databricks REST APIsを使用するための認証を理解するには、REST APIsのタイプと Databricks リソース階層との関係を理解する必要があります。

1 つ以上の Databricks アカウント を持っている場合があります。 Databricks アカウントには、0 個、1 個、またはそれ以上の Databricks ワークスペースが含まれています。 アカウントコンソールを使用して、ワークスペースを作成し、ワークスペースの設定に必要なクラウドリソース (認証情報、ストレージ、ネットワークなど) を管理できます。

Databricks ワークスペース には、ジョブやノートブックなど、さまざまなリソースがあります。 ワークスペース管理者 (単に管理者と呼ばれることもあります) は、 管理者設定ページの設定など、ワークスペース レベルで定義されている設定を変更できます。

この違いにより、 APIsには2つのタイプがあります。

• DatabricksアカウントレベルのAPIsは、アカウントの所有者とアカウント管理者のみが呼び出すことができます。これらの APIs は、アカウントコンソールのURLhttps://accounts.gcp.databricks.com でホストされています。
• DatabricksワークスペースレベルのAPIsは、ワークスペース管理者とワークスペースユーザーのみが呼び出すことができます。これらの APIs は、https://1234567890123456.7.gcp.databricks.com などのワークスペース URL でホストされます。

Databricks REST APIに対して認証するには、 APIのベース URL と一致するオーディエンス(aud)を含む Google ID トークンを渡す必要があります。これは、これら 2 つのタイプのAPIsで異なります。異なるベース URL で Databricks REST APIs を呼び出すには、異なる Google ID トークンを使用する必要があります。

資格情報のパススルー

いくつかの Databricks REST API メソッドでは 、資格情報のパススルー が必要です。 これらのメソッドを呼び出すには、Google ID に加えて、HTTP ヘッダーで cloud-platform スコープを含む Google OAuth アクセス トークン も渡す必要があります。Databricks サーバーは、Google OAuth アクセス トークンを使用して、呼び出し元の代わりに Google Cloud APIsを呼び出します。

Databricks では、アクセス トークンは検証または保持されません。

important

操作に認証情報のパススルーが必要かどうかを判断するには、各 API 操作の API ドキュメントを参照してください。 これらの APIs には、要求にX-Databricks-GCP-SA-Access-Token HTTP ヘッダーが必要です。

ステップ 1: 2 つのサービス アカウントを作成する

1. 新しい Google Cloud サービス アカウントを 2 つ作成します。 Google の記事 「サービス アカウントの作成」の指示に従います。 Google Cloud Console を使用するには、 サービス アカウント ページに移動し、作成する Google Cloud プロジェクトを選択します。 これらのサービス アカウントを作成するGoogle Cloud プロジェクトは、 Databricks ワークスペースに使用するプロジェクトと一致する必要はなく、新しいサービス アカウントも互いに同じ Google Cloud プロジェクトを使用する必要はありません。

   • トークン-creating サービス アカウント (SA-1): このサービス アカウントは、メイン サービス アカウントのトークンの作成を自動化します。 これらのトークンは、 Databricks REST APIsを呼び出すために使用されます。 Googleのドキュメントではこれを SA-1 と呼んでいます。
   • Main サービス アカウント for Databricks REST APIs (SA-2): このサービス アカウントは、 Databricks REST APIs および自動化されたワークフローのプリンシパル (自動化ユーザー) として機能します。 Googleのドキュメントではこれを SA-2 と呼んでいます。

   両方のサービス アカウントのEメール アドレスを保存して、後の手順で使用します。

2. トークン作成サービス アカウント (SA-1) の サービス アカウント キー を作成し、 SA-1-key.jsonというローカル ファイルに保存します。

   1. Google Cloud Console のサービス アカウント ページで、SA-1 の Eメール アドレスをクリックします。
   2. 「キー 」タブをクリックします。
   3. [キーの追加 ] をクリックします。
   4. JSON (デフォルト)が選択されていることを確認します。
   5. [ 作成 ]をクリックします。
   6. Web ページは、キー ファイルをブラウザにダウンロードします。 そのファイルをローカルの作業ディレクトリに移動し、名前を . SA-1-key.jsonに変更します。

   その他の手順については、Google の記事「 サービス アカウント キーの作成」を参照してください。

3. トークンを作成するサービス アカウント (SA-1) に、メインのサービス アカウント (SA-2) のサービス アカウント トークン Creator ロールを付与します。 Google の記事「 直接リクエストの権限」の指示に従います。

   1. Google Cloud Console のサービス アカウント ページで、SA-2 の Eメール アドレスをクリックします。

important

Google Cloud Console では、トークンを作成する SA(SA-1)ではなく、メインの SA(SA-2)を編集してください。

1. [ アクセス許可 ]をクリックします。
2. [ アクセス権を付与 ] をクリックします。
3. [新しいプリンシパル ] フィールドに、トークンを作成する SA (SA-1) の Eメール アドレスを貼り付けます。
4. [ Role ] フィールドで、[ サービス アカウント トークン Creator Role ] を選択します。
5. [ 保存 ]をクリックします。

ステップ 2: Google ID トークンを作成する

Databricks では、Google Cloud CLI (gcloud) を使用して ID トークンを生成し、 Databricks REST APIsを呼び出すことをお勧めします。

important

生成された ID トークンは 1 時間で期限切れになります。 その時間内に残りのすべてのステップを完了する必要があります。 Databricks APIsの呼び出しなど、後の手順を完了する前にトークンの有効期限が切れた場合は、この手順を繰り返して新しい Google ID トークンを生成する必要があります。

1. Google Cloud CLI をマシンにインストールします。 gcloud ツールのインストールに関する Google の記事をご覧ください。

2. 次のコマンドを実行して、メイン サービス アカウントの ID トークンを生成します。

   • <SA-1-key-json> を JSON 形式の SA-1 キー ファイルへのパスに置き換えます。
   • <SA-2-email>をSA-2のEメールアドレスに置き換えてください。
   • ユースケースに基づいて、次のように <audience> を置き換えます。
     • ワークスペース レベルの APIsの場合は 、https://999999999992360.0.gcp.databricks.com などの形式が https://<numbers>.<digit>.gcp.databricks.com のワークスペース URL に置き換えます。すべてのワークスペースには、異なる一意のワークスペース URL があります。 複数のワークスペースで APIs を呼び出すには、それぞれ異なる audience 値を持つ複数の Google ID トークンを作成する必要があります。
     • アカウントレベルの API の場合は 、 https://accounts.gcp.databricks.comに置き換えます。 異なるアカウントはすべて同じ audience 値を共有します。

   本番運用システムで使用する以下のコマンドを実行します。

   Bash

   gcloud auth login --cred-file=<SA-1-key-json>
   
   gcloud auth print-identity-token --impersonate-service-account="<SA-2-email-address>" --include-email --audiences="<audience>"

   本番運用以外で、ユーザーアカウントを使用してSA-2になりすます場合は、次のコマンドを使用します。

   Bash

   gcloud auth login
   
   gcloud auth print-identity-token --impersonate-service-account=<SA-2-email-address> --audiences="<audience>" --include-email

   本番運用以外で使用する場合、SA-1 と SA-2 の両方に 1 つのサービス アカウントを使用する場合は、サービス アカウントのキー JSON ファイルと共に次のコマンドを使用します。

   Bash

   gcloud auth login --cred-file=<SA-key-json>
   
   gcloud auth print-identity-token --audiences="<audience>"

3. 出力の末尾にある長い行を google-id-token-sa-2.txtというファイルに保存します。

   次のようなテキストが出力されます。

   WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email-address>].
   
   eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

ステップ 3: Google OAuth アクセス トークンを作成する(認証情報のパススルーが必要な APIs のみ)

注記

この手順は、資格情報のパススルーが必要な APIs を呼び出す場合にのみ必要です。 操作に認証情報のパススルーが必要かどうかを判断するには、各 API 操作の API ドキュメントを参照してください。

アクセス トークンを生成する要求には、アクセス トークンの有効期間を定義する lifetime フィールドが含まれます。 トークンを 5 分間だけアクティブにする必要がある場合は、 300s (300 秒) に設定します。 次の例では、1 時間を表す 3600sを使用しています。

important

• 残りのすべてのステップをその制限時間内に完了する必要があります。 Databricks APIsの呼び出しなど、後の手順を完了する前に時間が経過した場合は、この手順を繰り返して新しい Google OAuth アクセス トークンを生成する必要があります。
• デフォルトでは、時間 (3600s) が lifetime フィールドに設定できる最大期間です。 この制限を延長するには、Google 顧客サポートに連絡して例外をリクエストしてください。

1. 次のコマンドを実行します。 <SA-2-email-address> を SA-2 のサービス アカウント Eメール アドレスに置き換えます。本番運用以外の使用またはテストで、単一のサービスアカウントを使用している場合、またはユーザーアカウントを使用してサービスアカウントを偽装している場合は、 <SA-2-email-address> をサービスアカウントのEメールアドレスに置き換えてください。

   Bash

   gcloud auth print-access-token --impersonate-service-account=<SA-2-email-address>

2. 出力の末尾にある長い行を access-token-sa-2.txtというファイルに保存します。

   次のようなテキストが出力されます。

   WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email-address>].
   
   eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

ステップ 4: サービス アカウントをワークスペースまたはアカウント ユーザーとして追加する

Google ID トークンを使用してDatabricksアカウントレベルのAPIsまたはワークスペースレベルの APIsを呼び出すことができます。手順はユースケースによって異なります。 Google ID トークンの作成時に フィールドが異なるため、1 つの GoogleAPIs audienceID トークンを使用して両方のタイプの にアクセスすることはできません。

ワークスペース APIs

Google ID トークンを使用してワークスペース APIs を認証するには、ワークスペース管理設定ページを使用して、メインのサービス アカウント (SA-2) をユーザーのメール アドレスであるかのように追加します。

1. ワークスペースの管理者として、管理者設定ページに移動します。
2. 「ワークスペースでユーザーを管理する」の指示に従い、管理者設定ページで入力を求められたら、メインのサービス アカウントの Eメール アドレスを使用します。
3. 必要に応じて、新しいサービス アカウントに必要なグループ メンバーシップを、呼び出す予定の Databricks REST APIs と使用するデータ オブジェクトに基づいて追加します。 「グループの管理」を参照してください。
4. 必要に応じて、そのユーザーの Databricks アクセス制御設定を追加します。 アクセス制御リストを参照してください。

アカウントレベルの APIs

Google ID トークンを使用してアカウントレベルの APIs (アカウント APIなど)を認証するには、アカウントコンソールを使用して、メインのサービス アカウント(SA-2)をアカウント管理者として追加します。 ユーザーを追加する場合と同様に、Eメール アドレスを使用してサービス アカウントを追加します。

1. アカウント管理者として、 アカウントコンソールの[ユーザー]タブに移動します。

2. [ ユーザーを追加 ]をクリックします。

注記

[サービスプリンシパルの追加] をクリックしないでください。サービス アカウントを使用して Databricks サービスプリンシパルを作成することはできません。

3. Eメール アドレス フィールドに、メインのサービス アカウント (SA-2) Eメール アドレスを入力します。

4. 姓と名の必須フィールドを、サービス アカウントの目的を反映する方法で設定します。

5. [ ユーザーを追加 ]をクリックします。

手順 5: Databricks API を呼び出す

REST API認証時に提供する必要があるトークンは、予定されている使用方法 (アカウント API またはワークスペース レベルのAPIs) によって異なります。Google ID トークンの作成時に フィールドが異なるため、1 つの GoogleAPIs audiencesID トークンを使用して両方のタイプの にアクセスすることはできません。

次の HTTP ヘッダーは、Google ID を使用した Databricks 認証に使用されます。

HTTP ヘッダー名	説明	どのような種類の APIs が必要ですか?
Authorization	ベアラートークンとしてのSA-2のGoogle IDトークン。 構文は Authentication: Bearer <token>です。	すべてのAPI
X-Databricks-GCP-SA-Access-Token	SA-2 の Google OAuth アクセス トークン。	アカウントレベルの APIs のみ

ワークスペース レベルの API 要求の例

ワークスペースの Databricks REST API を呼び出すには、次の構文で Authorization HTTP ヘッダーに Google ID トークンを渡します。

Authorization: Bearer <google-id-token>

提供するトークンには、次の属性が必要です。

• アクセスするワークスペースは、トークンの作成時に指定したワークスペース URL と一致する必要があります。 「ステップ 2: Google ID トークンを作成する」を参照してください。
• 偽装されるサービス アカウント (SA-2) は、ワークスペースのユーザーである必要があります。 ワークスペース APIsを参照してください。

次の例では、ワークスペース レベルのAPIを呼び出して、クラスターを一覧表示します。

• <google-id-token> を google-id-token-sa-2.txtファイルに保存した Google ID トークンに置き換えます。
• <workspace-URL>を、 https://1234567890123456.7.gcp.databricks.comのような形式のベースとなるワークスペースURLに置き換えます。

Bash

curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  <workspace-URL>/api/2.0/clusters/list

認証情報のパススルーを使用しない API のアカウントレベルの API リクエストの例

次の例では、アカウント API を呼び出してワークスペースの一覧を取得します。

• <google-id-token> を google-id-token-sa-2.txtファイルに保存した Google ID トークンに置き換えます。
• <account-id>をアカウントIDに置き換えてください。アカウントIDを見つけるには:
  1. アカウント管理者として、 Databricks アカウント コンソールに移動します。
  2. 右上のユーザー名の横にある下向きの矢印をクリックします。
  3. ドロップダウンメニューでは、 アカウントID をコピーできます。

Bash

curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  https://accounts.gcp.databricks.com/api/2.0/example/<account-id>/operation-name

認証情報のパススルーを使用したアカウントレベルの API リクエストの例

次の例では、アカウント API を呼び出してワークスペースの一覧を取得します。

• <google-id-token> を google-id-token-sa-2.txtファイルに保存した Google ID トークンに置き換えます。

• <access-token-sa-2> を、ファイル access-token-sa-2.txtに保存した SA-2 アクセス トークンに置き換えます。

• <account-id>をアカウントIDに置き換えてください。アカウントIDを見つけるには:

  1. アカウント管理者として、 Databricks アカウント コンソールに移動します。
  2. 左側のメニューの下部にある(スクロールが必要な場合があります)、[ユーザー]ボタン(人のアイコン)をクリックします。
  3. 表示されるポップアップで、ID の右側にあるアイコンをクリックしてアカウント ID をコピーします。

  

Bash

curl \
  -X DELETE \
  --header 'Authorization: Bearer <google-id-token>' \
  --header 'X-Databricks-GCP-SA-Access-Token: <access-token-sa-2>' \
  https://accounts.gcp.databricks.com/api/2.0/accounts/<account-id>/workspaces/<workspace-id>