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 personal アクセストークン

注：

個人用アクセストークンは、テストシナリオ用に提供されます。 Databricks では、本番運用シナリオに対して、より安全な認証の種類を推奨しています。

Databricks個人用アクセストークンを作成するには、「ワークスペースユーザー向けの個人用アクセストークンDatabricks」の手順に従います。

PATを使用して、一般的な構成プロパティと機密性の高い資格情報プロパティが埋め込まれた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 ブラウザーベースの 認証とも呼ばれます。

注：

JDBC 2.6.40.1071 は、プライベートリンクワークスペースに M2M を使用して接続することがサポートされていない古いバージョンの問題を解決します。

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 2.6.40.1071 は、プライベートリンクワークスペースに M2M を使用して接続することがサポートされていない古いバージョンの問題を解決します。

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

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

サービスプリンシパルとそのOAuth シークレットを作成するには、「 Databricksを使用してサービスプリンシパルでへのアクセスを認証するOAuth (OAuth M2M)」を参照してください。サービスプリンシパルの UUID または Application ID の値と、サービスプリンシパルのシークレットの SecretOAuth 値をメモします。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可します。「コンピュート権限」または「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」セクションを参照してください。