Google ID トークンによる認証

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

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

重要

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

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

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

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

  • ワークロードを実行するためのサービス アカウント (SA-1) を 1 つ作成します。

  • 別のサービス アカウント (SA-2) を作成して、Databricks と Google クラウド リソースへのアクセス許可を保持します。

  • SA-1 に SA-2 を 偽装 して Databricks REST APIsを呼び出すアクセス許可を付与します。

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

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

  • Google ユーザー アカウントを使用して SA-2 になりすます。ユーザ アカウントには、ロール roles/iam.serviceAccountTokenCreatorが必要です。

  • SA-1 と SA-2 の両方に 1 つの Google クラウド サービス アカウント を使用します。

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

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

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

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

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

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 クラウド APIs を呼び出します。

Databricks では、アクセストークンの検証や保持は行われません。

重要

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

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

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

    • トークン作成サービス アカウント (SA-1): このサービス アカウントは、メイン サービス アカウントのトークンの作成を自動化します。 これらのトークンは、Databricks REST APIsを呼び出すために使用されます。 Google のドキュメントでは、これを SA-1 と呼んでいます。

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

    後の手順で使用するために、両方のサービスアカウントの電子メールアドレスを保存します。

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

    1. Google クラウドコンソールの [Service Accounts ] ページで、SA-1 のメールアドレスをクリックします。

    2. 「キー」タブをクリックします。

    3. [ADD KEY] をクリックします。

    4. [JSON] (デフォルト) が選択されていることを確認します。

    5. [作成]をクリックします。

    6. Web ページがキー ファイルをブラウザにダウンロードします。 そのファイルをローカルの作業ディレクトリに移動し、名前を SA-1-key.jsonに変更します。

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

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

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

    重要

    Google クラウドコンソールで、トークン作成 SA(SA-1)ではなく、メイン SA(SA-2)を編集してください。

    1. [権限] をクリックします。

    2. [アクセス権を付与] をクリックします。

    3. [ New Principals ] フィールドに、トークン作成 SA (SA-1) の E メール アドレスを貼り付けます。

    4. [Role] フィールドで、[サービス アカウント トークン Creator Role] を選択します。

    5. [保存]をクリックします。

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

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

重要

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

  1. マシンに Google クラウド 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 値を共有します。

    本番運用システムで使用するには、次のコマンドを実行します。

    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 を偽装する場合は、次のコマンドを使用します。

    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 ファイルで次のコマンドを使用します。

    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 のみ)

..note:: このステップは、クレデンシャルパススルーを必要とする APIs を呼び出す場合にのみ必要です。 操作に資格情報のパススルーが必要かどうかを判断するには、各 API 操作の API ドキュメントを参照してください。

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

重要

  • 残りのすべてのステップを制限時間内に完了する必要があります。 Databricks APIsの呼び出しなど、後の手順を完了する前に時間が経過した場合は、この手順を繰り返して新しい Google OAuth アクセス トークンを生成する必要があります。

  • デフォルトでは、時間(3600s)が lifetime フィールドに設定できる最大期間です。 この制限を延長するには、Google カスタマー サポートに連絡して例外をリクエストしてください。

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

    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 トークンの作成APIs audience時に [ ] 欄が異なるため、1 つの Google ID トークンを使用して両方のタイプの にアクセスすることはできません。

ワークスペースAPIs

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

  1. ワークスペース管理者として、 管理者設定ページに移動します。

  2. ワークスペースのユーザー管理の手順に従い、管理設定ページで入力を求められた場合は、メインのサービス アカウントの電子メール アドレスを使用します。

  3. 必要に応じて、呼び出す予定のDatabricks REST APIsと使用するデータ オブジェクトに基づいて、新しい サービス アカウント に必要な可能性があるグループ メンバーシップを追加します。 「グループの管理」を参照してください。

  4. 必要に応じて、そのユーザーの Databricks アクセス制御設定を追加します。 アクセス制御リストを参照してください。

アカウントレベルのAPIs

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

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

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

    注：

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

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

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

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

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

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

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

HTTP ヘッダー名

説明

どのようなタイプの APIs が必要ですか?

Authorization

ベアラー トークンとしての SA-2 の Google ID トークン。 構文は Authentication: Bearer <token>です。

すべての APIs

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) は、ワークスペースのユーザーである必要があります。 Workspace APIsを参照してください。

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

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

  • <workspace-URL> を、https://1234567890123456.7.gcp.databricks.comのような形式のベース ワークスペース URL に置き換えます。

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

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

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

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

  • <account-id> をアカウント ID に置き換えます。アカウント ID を確認するには:

    1. アカウント管理者として、 Databricks アカウント コンソールに移動します。

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

    3. ドロップダウンメニューで、 アカウントIDをコピーできます。

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 トークンgoogle-id-token-sa-2.txt置き換えます。

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

  • <account-id> をアカウント ID に置き換えます。アカウント ID を確認するには:

    1. アカウント管理者として、 Databricks アカウント コンソールに移動します。

    2. 左側のメニューの下部(スクロールが必要な場合があります)で、[ユーザー]ボタン(人物アイコン)をクリックします。

    3. 表示されるポップアップで、ID の右側にあるアイコンをクリックして、アカウント ID をコピーします。

    アカウント ID を確認します。 
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>