Databricks CLI の認証

注:

この情報は、パブリックプレビュー段階にあるDatabricks CLIバージョン0.205 以降に適用されます。ご使用のDatabricks CLIのバージョンは、databricks -vを実行することで確認できます。

この記事では、Databricks CLIとDatabricksアカウントおよびワークスペース間の認証を設定する方法について説明します。詳しくは、Databricks CLIとはを参照してください。

この記事では、Databricks CLIをインストール済みであることを前提としています。Databricks CLIのインストールまたはアップデートを参照してください。

Databricks CLIコマンドを実行する前に、実行するCLIコマンドの種類に応じて、Databricks CLIとDatabricksアカウント、ワークスペース、またはこれらの組み合わせ間で認証を設定する必要があります。

Databricksアカウントまたはワークスペース内でDatabricks自動化コマンドを実行するには、実行時に関連リソースに対してDatabricks CLIを認証する必要があります。Databricksワークスペースレベルのコマンド、Databricksアカウントレベルのコマンド、またはその両方を呼び出すかによって、Databricksワークスペース、アカウント、またはその両方の認証を行う必要があります。DatabricksのワークスペースレベルとアカウントレベルのCLIコマンドグループのリストについては、databricks -hコマンドを実行してください。Databricks CLIコマンドがカバーするDatabricksワークスペースレベルおよびアカウントレベルのREST API操作のリストについては、Databricks REST APIを参照してください。

以下のセクションでは、Databricks CLIとDatabricksの間で認証を設定する方法について説明します。

Databricks個人用アクセストークン認証

Databricks個人用アクセストークン認証では、Databricks個人用アクセストークンを使用して、DatabricksユーザーアカウントやDatabricksサービスプリンシパルなどのターゲットDatabricksエンティティを認証します。「Databricks個人用アクセストークン認証」も参照してください。

注:

Databricksのアカウントレベルのコマンドは認証にDatabricks個人用アクセストークンを使用しないため、Databricks個人用アクセストークン認証をDatabricksアカウントの認証に使用することはできません。Databricksアカウントを使用して認証するには、代わりに次のいずれかの認証タイプを使用することを検討してください。

注:

Databricksのユーザー名とパスワードを使用した基本認証のサポートは2024年7月10日に終了しました。詳しくは、「Databricksで管理するパスワードのサポート終了」を参照してください。

個人アクセストークンを作成するには、次の手順を実行します。

  1. Databricksワークスペースで、上部のバーに表示されているDatabricksユーザー名をクリックし、ドロップダウンから [設定] を選択します。

  2. [開発者] をクリックします。

  3. [アクセストークン] の横にある [管理] をクリックします。

  4. [新規トークンを生成] をクリックします。

  5. (任意)今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには(非推奨)、[有効期間(日)] ボックスを空白のままにしてください。

  6. [生成] をクリックします。

  7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

注:

コピーしたトークンは必ず安全な場所に保存してください。コピーしたトークンを他のユーザーと共有しないでください。コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。代わりに、この手順を繰り返して新しいトークンを作成する必要があります。コピーしたトークンを紛失した場合、またはトークンが漏洩したと思われる場合は、[アクセストークン] ページでトークンの横にあるゴミ箱([取り消し])アイコンをクリックして、直ちにそのトークンをワークスペースから削除することを強くお勧めします。

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしているか、トークンを作成または使用する権限を付与していない可能性があります。 ワークスペース管理者または次のトピックを参照してください。

Databricks個人用アクセストークン認証を構成して使用するには、次の手順を実行します。

注:

次の手順では、DEFAULTという名前のDatabricks構成プロファイルを作成します。使用するDEFAULT構成プロファイルがすでにある場合は、この手順をスキップしてください。それ以外の場合、この手順により既存のDEFAULT構成プロファイルが上書きされます。既存の構成プロファイルの名前とホストを表示するには、コマンドdatabricks auth profilesを実行します。

DEFAULT以外の名前の構成プロファイルを作成するには、次のdatabricks configureコマンドの末尾に--profile <configuration-profile-name>または-p <configuration-profile-name>を追加し、 <configuration-profile-name>を新しい構成プロファイルの名前に置き換えます。

  1. Databricks CLIを使用して、次のコマンドを実行します。

    databricks configure
    
  2. プロンプトDatabricks Hostに、Databricksワークスペース インスタンスのURLを入力します (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com)。

  3. プロンプトのPersonal Access Tokenに、ワークスペースのDatabricks個人用アクセストークンを入力します。

    Databricks個人用アクセストークンを入力すると、対応する構成プロファイルが.databrickscfgファイルに追加されます。Databricks CLIがデフォルトの場所でこのファイルを見つけられない場合、まずこのファイルを作成し、次にこの構成プロファイルを新しいファイルに追加します。このファイルのデフォルトの場所は、Unix、Linux、macOSの場合は~(ユーザーホーム)フォルダ、Windowsの場合は%USERPROFILE%(ユーザーホーム)フォルダです。

  4. Databricks CLIコマンド呼び出しの一部として、Databricks CLIの--profileまたは-pオプションに続けて構成プロファイルの名前を使用できるようになりました(例: databricks clusters list -p <configuration-profile-name>)。

OAuthマシン間(M2M)認証

DatabricksDatabricks個人用アクセストークン認証 を使用して で認証する代わりに、OAuth 認証を使用できます。OAuth は、 Databricks personal アクセストークンよりも短い有効期限をトークンに提供し、サーバー側のセッションの無効化とスコープを改善します。 OAuth アクセス トークンは 1 時間以内に期限切れになるため、誤ってトークンをソース コントロールにチェックインするリスクが軽減されます。「 Databricksを使用してサービスプリンシパルで へのアクセスを認証するOAuth (OAuth M2M)」 も参照してください。

OAuth M2M認証を構成して使用するには、次の手順を実行します。

  1. OAuth M2M 認証の設定手順を完了します。 「 を使用してサービスプリンシパルで へのアクセスを認証する (DatabricksOAuthOAuth M2M)」を参照してください。

  2. .databrickscfgファイルで次のフィールドを使用してDatabricks構成プロファイルを作成または識別します。プロファイルを作成する場合は、プレースホルダーを適切な値に置き換えます。

    アカウントレベルのコマンドでは、.databrickscfgファイルに以下の値を設定します。

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

    ワークスペースレベルのコマンドでは、.databrickscfgファイルに以下の値を設定します。

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

    注:

    .databrickscfgファイルのデフォルトの場所は、ユーザーのホームディレクトリです。これは、LinuxおよびmacOSの場合は~、Windowsの場合は%USERPROFILE%です。

  3. Databricks CLIの--profileまたは-pオプションを使用し、その後にDatabricks CLIコマンド呼び出しの一部として構成プロファイルの名前を指定します(例:databricks account groups list -p <configuration-profile-name>またはdatabricks clusters list -p <configuration-profile-name>)。

    ヒント

    構成プロファイル名を手動で入力する代わりに、--profile または -p の後に Tab を押すと、選択可能な既存の構成プロファイルのリストが表示されます。

OAuthユーザー対マシン(U2M)認証

トークン認証を使用して Databricks で認証する代わりに、OAuth 認証を使用できます。OAuth は、 Databricks personal アクセストークンよりも短い有効期限をトークンに提供し、サーバー側のセッションの無効化とスコープを改善します。 OAuth アクセス トークンは 1 時間以内に期限切れになるため、誤ってトークンをソース コントロールにチェックインするリスクが軽減されます。「OAuth を使用してユーザーアカウントで Databricks へのアクセスを認証する (OAuth U2M)」も参照してください。

OAuth U2M認証を構成して使用するには、次の手順を実行します。

  1. Databricksのアカウントレベルのコマンドを呼び出す前に、以下のコマンドを実行してOAuthトークンの管理をローカルで開始する必要があります。このコマンドは、コマンドを実行するアカウントごとに個別に実行する必要があります。アカウントレベルの操作を呼び出したくない場合は、ステップ5に進んでください。

    以下のコマンドで、これらのプレースホルダーを置き換えます。

    databricks auth login --host <account-console-url> --account-id <account-id>
    
  2. Databricks CLIは、アカウントコンソールのURLとアカウントIDをDatabricks構成プロファイルとしてローカルに保存するよう促します。Enterを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイルの名前を入力してください。同じ名前のプロファイルがすでにある場合、このアカウントコンソールのURLとアカウントIDで上書きされます。

    既存のプロファイルのリストを取得するには、別のターミナルまたはコマンドプロンプトで、databricks auth profilesコマンドを実行します。特定のプロファイルの既存の設定を表示するには、コマンドdatabricks auth env --profile <profile-name>を実行します。

  3. Webブラウザで、画面上の指示に従ってDatabricksアカウントにログインします。

  4. 現在のOAuthトークンの値と今後の有効期限のタイムスタンプを表示するには、コマンドdatabricks auth token --host <account-console-url> --account-id <account-id>を実行します。

  5. Databricksのワークスペースレベルのコマンドを呼び出す前に、次のコマンドを実行してOAuthトークンの管理をローカルで開始する必要があります。このコマンドは、コマンドを実行するワークスペースごとに個別に実行する必要があります。

    以下のコマンドで、<workspace-url>をDatabricksワークスペースインスタンスURL(例:https://dbc-a1b2345c-d6e7.cloud.databricks.com)に置き換えてください。

    databricks auth login --host <workspace-url>
    
  6. Databricks CLIは、ワークスペースURLをDatabricks構成プロファイルとしてローカルに保存するよう促します。Enterを押して提案されたプロファイル名を受け入れるか、新規または既存のプロファイルの名前を入力してください。同じ名前のプロファイルがすでにある場合は、このワークスペースURLで上書きされます。

    既存のプロファイルのリストを取得するには、別のターミナルまたはコマンドプロンプトで、databricks auth profilesコマンドを実行します。特定のプロファイルの既存の設定を表示するには、コマンドdatabricks auth env --profile <profile-name>を実行します。

  7. Webブラウザで、画面の指示に従ってDatabricksワークスペースにログインします。

  8. 現在のOAuthトークンの値と今後の有効期限のタイムスタンプを表示するには、コマンドdatabricks auth token --host <workspace-url>を実行します。

  9. Databricks CLIコマンド呼び出しの一部として、Databricks CLIの--profileまたは-pオプションの後に構成プロファイルの名前を入力します(例:databricks account groups list -p <configuration-profile-name>またはdatabricks clusters list -p <configuration-profile-name>)。

    ヒント

    構成プロファイル名を手動で入力する代わりに、--profileまたは-pの後にTabを押すと、選択可能な既存の構成プロファイルのリストが表示されます。

認証評価順序

Databricksワークスペースまたはアカウントを使用して認証を試行するために必要な設定を収集する必要がある場合、Databricks CLIは以下の場所でこれらの設定を常に次の順序で検索します。

  1. バンドルの作業ディレクトリ(バンドルルートとネストされたパス)から実行されるコマンドの場合、プロジェクトのバンドル設定ファイル内のフィールドの値(バンドル設定ファイルにはアクセス資格情報の値を直接含めることはできません)。

  2. 環境変数の値(この記事および「クライアント統合認証の環境変数とフィールド」に記載されています)。

  3. .databrickscfgファイル内の構成プロファイルフィールドの値(この記事で前述)。

Databricks CLIは必要な設定を見つけると、他の場所での検索を停止します。例:

  • Databricks CLIがDatabricks個人用アクセストークンの値を必要としていて、DATABRICKS_TOKEN環境変数が設定されており、.databrickscfgファイルにも複数のパーソナルアクセストークンが含まれているとします。この例では、Databricks CLIはDATABRICKS_TOKEN環境変数の値を使用し、.databrickscfgファイルは検索しません。

  • databricks bundle deploy -t devコマンドでDatabricks個人用アクセストークンの値が必要で、DATABRICKS_TOKEN環境変数が設定されておらず、.databrickscfgファイルには複数の個人用アクセストークンが含まれており、プロジェクトのバンドル設定ファイルにはprofileフィールドを通じてDEVという名前の構成プロファイルを参照するdev環境宣言が含まれているとします。この例では、Databricks CLIは.databrickscfgファイルでDEVという名前のプロファイルを検索し、そのプロファイルのtokenフィールドの値を使用します。

  • databricks bundle run -t dev hello-jobコマンドでDatabricks個人用アクセストークンの値が必要で、DATABRICKS_TOKEN環境変数が設定されておらず、.databrickscfgファイルには複数の個人用アクセストークンが含まれており、プロジェクトのバンドル設定ファイルにはhostフィールドを通じて特定のDatabricksワークスペースURLを参照するdev環境宣言が含まれているとします。この例では、Databricks CLIは.databrickscfgファイル内の構成プロファイルを検索し、一致するワークスペースURLを持つhostフィールドを含むプロファイルを探します。Databricks CLIは、一致するhostフィールドを見つけると、そのプロファイルのtokenフィールド値を使用します。