メインコンテンツまでスキップ

サービスプリンシパルへのアクセスを承認する Databricks with OAuth

この記事では、自動化された CLI コマンドやスクリプトやアプリケーションから行われた REST API 呼び出しなど、無人プロセスから Databricks リソースへのアクセスを承認する方法について説明します。

Databricks は、UI の外部でのサービスプリンシパルの認証と認証の優先プロトコルとして OAuth 2.0 を使用します。統合クライアント認証により、トークンの生成と更新が自動化されます。サービスプリンシパルがサインインして同意を得ると、 OAuth は、 CLI、 SDK、またはその他のツールが代わりに使用するアクセストークンを発行します。 各アクセストークンは1時間有効で、その後、新しいトークンが自動的に要求されます。

この記事では、 認証 とは、 OAuth を使用してサービスプリンシパル Databricks リソースへのアクセス権を付与することを指し、 認証 とは、アクセストークンを通じて資格情報を検証することを指します。

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

サービスプリンシパルを承認する方法​

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

  • 自動 (推奨): サポートされているツールや SDK (Databricks Terraform SDK など) で 統合認証 を使用します。このアプローチは、トークンの生成と更新を自動的に処理し、自動化やその他の無人ワークロードに最適です。

  • 手動： コード検証ツールとチャレンジを生成し、それらを OAuth トークンと交換します。ツールまたは API が統合認証をサポートしていない場合は、この方法を使用します。アプリケーション用に独自のトークン更新メカニズムを構築する必要がある場合があります。詳細については、「 OAuth M2M アクセストークンを手動で生成する」を参照してください。

前提 条件​

OAuth を設定する前に、次の手順を実行します。

  1. Databricksサービスプリンシパルを作成します。Add サービスプリンシパルをアカウントに追加するを参照してください。
  2. サービスプリンシパルの [構成 ] タブに移動し、このワークスペースに必要なエンタイトルメントを選択します。
  3. [ 権限] タブに移動し、このサービスプリンシパルを管理および使用する Databricks ユーザー、サービスプリンシパル、およびグループにアクセス権を付与します。 「 サービスプリンシパルを管理および使用できるユーザー」を参照してください。

ステップ 1: OAuth シークレットを作成する​

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

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

  1. サービスプリンシパルの詳細ページで、[ シークレット] タブを開きます。
  2. [ OAuthシークレット ] で、[ シークレットを生成 ] をクリックします。
  3. シークレットの有効期間を日数 (最大 730 日) で設定します。
  4. 表示されたシークレットとクライアント ID をコピーし、[ 完了] をクリックします。シークレットは一度だけ表示されます。クライアント ID は、サービスプリンシパルのアプリケーション ID と同じです。

アカウント管理者は、アカウントコンソールから OAuth シークレットを作成することもできます。 [ ユーザー管理 ] タブからサービスプリンシパルを選択し、[ 資格情報とシークレット] タブに移動します。

注記

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

ステップ 2: 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に基づいて、コード内に以下を統合します。

ツールまたは SDK で特定の Databricks 認証の種類に環境変数を使用するには、「 Databricks リソースへのアクセスを承認する」 またはツールまたは SDK のドキュメントを参照してください。統合認証の環境変数とフィールド、および認証方法の優先度も参照してください。

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

  • DATABRICKS_HOST：DatabricksアカウントのコンソールURL https://accounts.cloud.databricks.com の値に設定します。
  • DATABRICKS_ACCOUNT_ID
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

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

  • DATABRICKS_HOSTを Databricks ワークスペース URL の値 (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com) に設定します。
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

OAuth M2M アクセストークンを手動で生成する​

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

OAuth M2M アクセストークンを生成するには、サービスプリンシパルのクライアント ID とシークレットOAuth使用します。各アクセストークンは 1 時間有効です。有効期限が切れたら、新しいトークンを要求します。トークンは、アカウントレベルまたはワークスペースレベルのいずれかで生成できます。

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

アカウントレベルのトークンを使用して、アカウントとサービスプリンシパルがアクセスできる任意のワークスペースの REST APIs を呼び出します。

  1. アカウントIDを見つけます。

  2. 次の URL の <account-id> をアカウント ID に置き換えて、トークンエンドポイント URL を構築します。

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

  3. curl を使用して 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
    }

    all-apis スコープは、サービスプリンシパルがアクセス許可を持つ任意のDatabricks REST APIを呼び出すことを許可するOAuthアクセストークンを要求します。

  4. 応答から access_token 値をコピーします。

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

ワークスペースレベルのトークンは、そのワークスペースの REST APIs でのみ使用します。

  1. トークン エンドポイント URL を構築するには、<databricks-instance>を Databricks ワークスペース インスタンス名の <databricks-instance> に置き換えます (例: dbc-a1b2345c-d6e7.cloud.databricks.com:

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

  2. curl を使用して 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
    }

  3. 応答から access_token 値をコピーします。

注記

配信エンドポイントのトークンを生成するには、リクエストにエンドポイント ID とアクションを含めます。「OAuthトークンを手動で取得する」を参照してください。

Databricks REST API を呼び出す​

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

認証 Bearer 認証で認証ヘッダーにトークンを含めます。

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

この例では、アカウントのすべてのワークスペースを一覧表示します。取り替える：

  • <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 要求の例​

この例では、ワークスペースで使用可能なすべてのクラスタリングを一覧表示します。 取り替える：

  • <oauth-access-token> サービスプリンシパルの OAuth アクセストークン。
  • <databricks-instance> を Databricks ワークスペース インスタンス名 (例: dbc-a1b2345c-d6e7.cloud.databricks.com) に置き換えます。
Bash
export OAUTH_TOKEN=<oauth-access-token>

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

OAuth M2M 認証のトラブルシューティング​

サービスプリンシパルの Databricks OAuth M2M 認証に関する最も一般的な問題を解決するには、次の手順を使用します。

クイックチェック​

まず、OAuth M2M 認証の失敗を引き起こす次の一般的な構成の問題を確認します。

  • 資格情報: DATABRICKS_CLIENT_ID はサービスプリンシパルのアプリケーション ID (クライアント ID) に設定され、 DATABRICKS_CLIENT_SECRET は OAuth シークレット値に設定され、どちらも余分なスペースはありません。
  • ホスト: DATABRICKS_HOST は、アカウント操作の場合は https://accounts.cloud.databricks.com、またはワークスペース操作の場合は https://dbc-a1b2345c-d6e7.cloud.databricks.com など、ターゲットワークスペース URL を指します。/apiは含めないでください。
  • 割り当て： サービスプリンシパルは、ターゲットワークスペースに割り当てられます。
  • 権限： サービスプリンシパルには、ターゲットリソースに対する必要な権限があります。
  • 競合： DATABRICKS_TOKEN、 DATABRICKS_USERNAMEなどの競合する変数は設定されていません。競合 env | grep DATABRICKS 実行と設定解除の競合。
  • ツール： 統合認証と現在の CLI または SDK バージョンを使用します。

401 未承認​

考えられる原因と修正:

  • 不正なクライアント ID またはシークレット: DATABRICKS_CLIENT_IDとDATABRICKS_CLIENT_SECRETを再コピーします。不明な場合はシークレットを再生成します。
  • 期限切れのシークレット: 現在のシークレットの有効期限が切れている場合は、新しいシークレットを作成します。
  • 間違ったトークン発行者: M2M の場合は、IdP またはクラウド トークン エンドポイントではなく、Databricks OAuth トークン エンドポイントを使用します。
  • ホストの不一致: ワークスペース APIsの認証を行う場合は、呼び出すワークスペース URL DATABRICKS_HOST 必要があります。

403 禁断​

考えられる原因と修正:

  • リソースの 権限がありません: サービスプリンシパルにクラスターまたはSQLウェアハウスのCAN USEまたはCAN MANAGE、およびノートブック、ジョブ、またはデータオブジェクトに必要なオブジェクトレベルのアクセス権を付与します。
  • ワークスペース の割り当てなし: アカウントコンソールで、サービスプリンシパルをワークスペースに割り当てます。
  • 管理者 API アクセス: 管理者専用 APIsの場合は、 サービスプリンシパル をワークスペース admin グループに割り当てるか、アカウント admin 権限を付与します。

構成の問題​

症状には、タイムアウト、「ホストが見つかりません」、「アカウントが見つかりません」、「ワークスペースが見つかりません」などがあります。

修正：

  • ホストルール: アカウントコンソールのURLを使用してアカウント APIs。 ワークスペース APIsのワークスペース URL を使用します。 /apiサフィックスは含めないでください。
  • アカウント ID: アカウントレベルの操作にのみ DATABRICKS_ACCOUNT_ID を指定します。 アカウントコンソールからUUIDを使用します。
  • プロファイルの選択: 複数のプロファイルを使用する場合は、 --profile <name> 渡すか、 DATABRICKS_CONFIG_PROFILEを設定します。

接続​

ネットワークの問題が原因で OAuth M2M 認証が失敗した場合は、次のテストを使用して、環境が Databricks エンドポイントに到達できることを確認します。

  • DNS: nslookup <your-host> (ホスト名の IP アドレスを返す必要があります)
  • TLS と到達可能性: curl -I https://<your-host> (HTTP ステータス 200、401、または 403 を返す必要があります)
  • 企業ネットワーク: プロキシまたはファイアウォール規則で Databricks エンドポイントへの HTTPS が許可されていることを確認します

追加のリソース​

に最終更新