Databricks JDBC ドライバーの認証設定

この記事では、 Databricks JDBC ドライバーの Databricks 認証設定を構成する方法について説明します。

Databricks JDBC ドライバーの Databricks 接続を構成するには、コンピュートリソース設定、ドライバー機能設定、および次の認証設定を、JDBC 接続 URL または JDBC 接続プロパティのプログラムによるコレクションに結合する必要があります。

JDBC 接続 URL は、次の形式を使用します。

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>[;<setting1>=<value1>;<setting2>=<value2>;<settingN>=<valueN>]

<server-hostname> と <http-path>の値を取得するには、「Databricks JDBC ドライバーのコンピュート設定」を参照してください。
次のセクションにリストされているように、各接続プロパティの必要に応じて <setting>=<value> を置き換えます。
また、特別なドライバー機能や高度なドライバー機能の設定を追加することもできます。

JDBC接続プロパティのプログラムによるコレクションは、次の例のようなJavaコードで使用できます。

package org.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class Main {
  public static void main(String[] args) throws Exception {
    Class.forName("com.databricks.client.jdbc.Driver");
    String url = "jdbc:databricks://" + System.getenv("DATABRICKS_SERVER_HOSTNAME") + ":443";
    Properties p = new java.util.Properties();
    p.put("httpPath", System.getenv("DATABRICKS_HTTP_PATH"));
    p.put("<setting1>", "<value1");
    p.put("<setting2>", "<value2");
    p.put("<settingN>", "<valueN");
    try (Connection conn = DriverManager.getConnection(url, p)) {
      Statement stmt = conn.createStatement();
      try (ResultSet rs = stmt.executeQuery("<query>")) {
        ResultSetMetaData md = rs.getMetaData();
        String[] columns = new String[md.getColumnCount()];
        for (int i = 0; i < columns.length; i++) {
          columns[i] = md.getColumnName(i + 1);
        }
        while (rs.next()) {
          System.out.print("Row " + rs.getRow() + "=[");
          for (int i = 0; i < columns.length; i++) {
            if (i != 0) {
              System.out.print(", ");
            }
            System.out.print(columns[i] + "='" + rs.getObject(i + 1) + "'");
          }
          System.out.println(")]");
        }
      }
    }
    System.exit(0);
  }
}

DATABRICKS_SERVER_HOSTNAME 環境と DATABRICKS_HTTP_PATH 環境の値を、それぞれターゲットの Databricks コンピュートリソースの [サーバーホスト名] と [HTTP パス] の値に設定します。これらの値を取得するには、「 Databricks JDBC ドライバーのコンピュート設定」を参照してください。環境変数を設定するには、オペレーティングシステムのマニュアルを参照してください。
次のセクションにリストされているように、必要に応じて各接続プロパティの <setting> と <value> を置き換えます。
また、通常、追加の<setting>と<value>のペアとして、特別なドライバー機能設定または高度なドライバー機能設定を追加することもできます。
この例では、 <query> を SQL SELECT クエリ文字列に置き換えます。

接続 URL と接続プロパティのコレクションのどちらを使用するかは、ターゲットアプリ、ツール、クライアント、SDK、または API の要件によって異なります。この記事では、サポートされている Databricks 認証の種類ごとに、JDBC 接続 URL の例と JDBC 接続プロパティのプログラムによるコレクションについて説明します。

Databricks JDBC ドライバーでは、次の Databricks 認証の種類がサポートされています。

Databricks personal アクセストークン
OAuth 2.0 トークン
OAuth user-to-machine (U2M) 認証
OAuthマシン間(M2M)認証

注：

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

Databricks personal アクセストークン

Databricks 個人用アクセストークンを作成するには、次の操作を行います。

Databricks ワークスペースで、上部のバーにある Databricks ユーザー名をクリックし、ドロップダウンから[設定]を選択します。
[ 開発者] をクリックします。
[アクセストークン] の横にある [管理] をクリックします。
[ 新しいトークンの生成] をクリックします。
（任意）今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには（非推奨）、[有効期間 (日) ] ボックスを空白のままにしてください。
[生成] をクリックします。
表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

注：

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

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。

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

一般構成プロパティと機密性の高い資格情報プロパティが埋め込まれた JDBC 接続 URL の場合:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>

JDBC接続URLの外部で設定された一般的な構成プロパティと機密性の高いクレデンシャル・プロパティを持つJavaコードの場合:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

上記のコード・スニペットを独自のニーズに適合させることができる完全なJavaコード例については、この記事の冒頭にあるコード例を参照してください。
上記の URL または Java コードで、 <personal-access-token> をワークスペースユーザーの Databricks 個人用アクセストークンに置き換えます。
<server-hostname> と <http-path>の値を取得するには、「Databricks JDBC ドライバーのコンピュート設定」を参照してください。

OAuth 2.0 トークン

JDBC ドライバー 2.6.36 以降では、Databricks ユーザーまたはサービスプリンシパルの OAuth 2.0 トークンがサポートされています。これは、OAuth 2.0 トークンパススルー 認証とも呼ばれます。

トークン・パススルー認証用の OAuth 2.0 トークンを作成するには、以下の操作を行います。

ユーザーの場合、 Databricks CLI を使用して OAuth U2M プロセスを開始して OAuth 2.0 トークンを生成し、 databricks auth token コマンドを実行して生成された OAuth 2.0 トークンを取得できます。 OAuthユーザーからマシン(U2M)への認証を参照してください。OAuth 2.0 トークンのデフォルトの有効期間は 1 時間です。新しい OAuth 2.0 トークンを生成するには、このプロセスを繰り返します。
詳細については、「 OAuth M2M 認証用にアクセストークンを手動で生成して使用する」を参照してください。サービスプリンシパルのOAuth access_token 値をメモします。 OAuth 2.0 トークンのデフォルトの有効期間は 1 時間です。新しい OAuth 2.0 トークンを生成するには、このプロセスを繰り返します。

OAuth 2.0 トークンパススルー認証を使用して認証するには、次の構成を設定します。

一般構成プロパティと機密性の高い資格情報プロパティが埋め込まれた JDBC 接続 URL の場合:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>

JDBC接続URLの外部で設定された一般的な構成プロパティと機密性の高いクレデンシャル・プロパティを持つJavaコードの場合:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

上記のコード・スニペットを独自のニーズに適合させることができる完全なJavaコード例については、この記事の冒頭にあるコード例を参照してください。
上記の URL または Java コードで、 <oauth-token> を OAuth 2.0 トークンに置き換えます。
<server-hostname> と <http-path>の値を取得するには、「Databricks JDBC ドライバーのコンピュート設定」を参照してください。

詳細については、「Databricks JDBC ドライバーガイド」の「Token Pass-through」セクションを参照してください。

OAuthユーザー対マシン（U2M）認証

JDBC ドライバー 2.6.36 以降では、Databricks ユーザーの OAuth ユーザー間 (U2M) 認証がサポートされています。これは、OAuth 2.0 ブラウザーベースの 認証とも呼ばれます。

OAuth U2M または OAuth 2.0 ブラウザーベースの認証には前提条件はありません。 OAuth 2.0 トークンのデフォルトの有効期間は 1 時間です。 OAuth U2M または OAuth 2.0 ブラウザーベースの認証では、期限切れの OAuth 2.0 トークンが自動的に更新されます。

注：

OAuth U2M または OAuth 2.0 ブラウザーベースの認証は、ローカルで実行されるアプリケーションでのみ機能します。サーバーベースまたはクラウドベースのアプリケーションでは動作しません。

OAuth user-to-machine (U2M) または OAuth 2.0 ブラウザーベースの認証を使用して認証するには、次の構成を設定します。

一般構成プロパティと機密性の高い資格情報プロパティが埋め込まれた JDBC 接続 URL の場合:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0

JDBC接続URLの外部で設定された一般的な構成プロパティと機密性の高いクレデンシャル・プロパティを持つJavaコードの場合:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2");
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

上記のコード・スニペットを独自のニーズに適合させることができる完全なJavaコード例については、この記事の冒頭にあるコード例を参照してください。
上記の URL または Java コードで、 <passphrase> を任意のパスフレーズに置き換えます。ドライバーは、更新トークンの暗号化にこのキーを使用します。
<server-hostname> と <http-path>の値を取得するには、「Databricks JDBC ドライバーのコンピュート設定」を参照してください。

詳細については、「Databricks JDBC ドライバーガイド」の「Using Browser Based Authentication」セクションを参照してください。

OAuthマシン間（M2M）認証

JDBC ドライバー 2.6.36 以降では、Databricks サービスプリンシパルの OAuth マシン間 (M2M) 認証がサポートされています。これは、OAuth 2.0 クライアント資格情報 認証とも呼ばれます。

注：

JDBC は現在、プライベートリンクワークスペースに M2M を使用して接続しません。

OAuth M2M または OAuth 2.0 クライアント資格情報認証を構成するには、次の手順を実行します。

Databricks ワークスペースに Databricks サービスプリンシパルを作成し、そのサービスプリンシパルの OAuth シークレットを作成します。

サービスプリンシパルとそのOAuthシークレットを作成するには、「サービスプリンシパルを使用してDatabricksで認証する」を参照してください。サービスプリンシパルの UUID または アプリケーション ID の値と、サービスプリンシパルのシークレットのシークレットOAuth 値をメモします。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可します。「コンピュート権限」または「SQL ウェアハウスの管理」を参照してください。

OAuth マシン間 (M2M) または OAuth 2.0 クライアント資格情報認証を使用して認証するには、次の構成を設定します。

一般構成プロパティと機密性の高い資格情報プロパティが埋め込まれた JDBC 接続 URL の場合:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>

JDBC接続URLの外部で設定された一般的な構成プロパティと機密性の高いクレデンシャル・プロパティを持つJavaコードの場合:

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

上記のコード・スニペットを独自のニーズに適合させることができる完全なJavaコード例については、この記事の冒頭にあるコード例を参照してください。
上記の URL または Java コードで、次のプレースホルダーを置き換えます。
- <service-principal-application-id> をサービスプリンシパルの UUID/アプリケーション ID 値に置き換えます。
- <service-principal-oauth-secret> をサービスプリンシパルの OAuth シークレット値に置き換えます。
- <server-hostname> と <http-path>の値を取得するには、「Databricks JDBC ドライバーのコンピュート設定」を参照してください。

詳細については、「Databricks JDBC ドライバーガイド」の「Using M2M Based Authentication」セクションを参照してください。