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

[アーティクル]
10/11/2024

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

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

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

Databricks JDBC ドライバーは、次の Azure Databricks 認証の種類をサポートしています。

Azure Databricks 個人用アクセストークン
Microsoft Entra ID トークン
OAuth 2.0 トークン
OAuth ユーザー対マシン (U2M) 認証
OAuth マシン間 (M2M) 認証

Azure Databricks 個人用アクセストークン

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

Azure Databricks ワークスペースの上部バーで、目的の Azure Databricks ユーザー名をクリックし、次にドロップダウンから [設定] を選択します。
[開発者] をクリックします。
[アクセストークン] の横にある [管理] をクリックします。
[新しいトークンの生成] をクリックします。
(省略可能) 将来このトークンを識別するのに役立つコメントを入力し、トークンの既定の有効期間 90 日を変更します。有効期間のないトークンを作成するには (推奨されません)、[有効期間 (日)] ボックスを空のままにします。
[Generate](生成) をクリックします。
表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

Note

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

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

Azure 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 ドライバーのコンピューティング設定」を参照してください。

Microsoft Entra ID トークン

ODBC および JDBC ドライバー 2.6.15 以降では、Azure Databricks ユーザーまたは Microsoft Entra ID サービスプリンシパルの Microsoft Entra ID トークンがサポートされています。

Microsoft Entra ID アクセストークンを作成するには、次の操作を行います。

Azure Databricks ユーザーの場合は、Azure CLI を使用できます。「Azure CLI を使用してユーザーの Microsoft Entra ID トークンを取得する」を参照してください。
Microsoft Entra ID サービスプリンシパルについては、「Azure CLI を使用して Microsoft Entra ID アクセストークンを取得する」を参照してください。 Microsoft Entra ID マネージドサービスプリンシパルを作成するには、「サービスプリンシパルを管理する」をご参照ください。

Microsoft Entra ID アクセストークンの既定の有効期間は約 1 時間です。アクセストークンは、「Microsoft Entra ID アクセストークンを更新する」のコードを実行することで、接続を中断することなく、既存のセッションに対してプログラムで更新できます。トークンを更新する方法については、Databricks JDBC ドライバーガイドのセクション Configuring Authentication > Using OAuth 2.0 を参照してください。

Microsoft Entra ID トークンを使って認証するには、次の構成を設定します。

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

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<microsoft-entra-id-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", "<microsoft-entra-id-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

上記のコードスニペットをニーズに合わせて調整できる完全な Java コード例については、この記事の冒頭にあるコード例を参照してください。
上記の URL または Java コードで、<microsoft-entra-id-token> を Microsoft Entra ID トークンに置き換えます。
<server-hostname> と <http-path> の値を取得する方法については、「Databricks JDBC ドライバーのコンピューティング設定」を参照してください。

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

OAuth 2.0 トークン

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

Microsoft Entra ID サービスプリンシパルのトークンパススルー認証用に OAuth 2.0 トークンを作成するには、「OAuth M2M 認証用のアクセストークンを手動で生成して使用する」を参照してください。サービスプリンシパルの OAuth の access_token 値をメモします。
Microsoft Entra ID マネージドサービスプリンシパルを作成するには、「サービスプリンシパルを管理する」をご参照ください。

重要

JDBC ドライバー 2.6.36 以降では、Azure Databricks OAuth シークレットを使用した OAuth 2.0 トークンの作成がサポートされています。 Microsoft Entra ID シークレットはサポートされません。

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> を Azure Databricks OAuth トークンに置き換えます。 (Microsoft Entra ID トークンは、OAuth 2.0 トークンパススルー認証ではサポートされていません。)
<server-hostname> と <http-path> の値を取得する方法については、「Databricks JDBC ドライバーのコンピューティング設定」を参照してください。

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

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

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

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

Note

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

OAuth ユーザー対マシン認証 (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 以降では、Microsoft Entra ID サービスプリンシパルの OAuth マシン間 (M2M) 認証がサポートされています。これは、OAuth 2.0 ''クライアント資格情報'' 認証とも呼ばれます。

Note

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

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

Microsoft Entra ID マネージドサービスプリンシパルを作成し、それを Azure Databricks アカウントとワークスペースに割り当てます。これを行うには、「サービスプリンシパルを管理する」をご参照ください。

重要

JDBC ドライバー 2.6.36 以降では、OAuth M2M または OAuth 2.0 クライアント資格情報認証用に Azure Databricks OAuth シークレットがサポートされています。 Microsoft Entra ID シークレットはサポートされません。
サービスプリンシパルの Azure Databricks OAuth シークレットを作成します。これを行うには、「OAuth M2M 認証用のアクセストークンを手動で生成して使用する」を参照してください。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセス権を付与します。「コンピューティングのアクセス許可」または「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> をサービスプリンシパルのアプリケーション (クライアント) ID 値に置き換えます。
- <service-principal-oauth-secret> をサービスプリンシパルの Azure Databricks OAuth シークレットに置き換えます。 (Microsoft Entra ID シークレットは、OAuth M2M または OAuth 2.0 クライアント資格情報認証ではサポートされていません。)
- <server-hostname> と <http-path> の値を取得する方法については、「Databricks JDBC ドライバーのコンピューティング設定」を参照してください。

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

次の方法で共有

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

Azure Databricks 個人用アクセストークン

Microsoft Entra ID トークン

OAuth 2.0 トークン

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

OAuth マシン間 (M2M) 認証

フィードバック

その他のリソース

次の方法で共有

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

Azure Databricks 個人用アクセス トークン

Microsoft Entra ID トークン

OAuth 2.0 トークン

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

OAuth マシン間 (M2M) 認証

フィードバック

その他のリソース

Azure Databricks 個人用アクセストークン