認証について

Important

Lakebase 自動スケールは、自動スケール コンピューティング、ゼロへのスケール、分岐、インスタント リストアを備えた最新バージョンの Lakebase です。 サポートされているリージョンについては、「 リージョンの可用性」を参照してください。 Lakebase プロビジョニング済みユーザーの場合は、「 Lakebase Provisioned」を参照してください。

Lakebase Postgres へのデータベース接続を認証する方法について説明します。 詳細な接続手順については、「 クイック スタート」を参照してください。

概要

Lakebase では、それぞれ異なるユース ケース向けに設計された 2 つの認証方法がサポートされています。

OAuth トークン認証: 時間制限付き OAuth トークンを持つAzure Databricks ID を使用します。 次の場合に最適です。

• トークンを更新できる対話型セッション
• ワークスペース統合ワークフロー
• トークンローテーションを実装できるアプリケーション
• Azure Databricksで認証を管理する場合

ネイティブ Postgres パスワード認証: 従来の Postgres ロールとパスワードを使用します。 次の場合に最適です。

• 資格情報を 1 時間ごとに更新できないアプリケーション
• 実行時間の長い処理
• トークンのローテーションをサポートしていないツール

注

プラットフォーム管理とデータベース アクセス: このページでは、データベース認証 (データベースに接続するための OAuth トークンと Postgres パスワード) に重点を置いています。 プラットフォーム管理認証 (プロジェクト、ブランチ、コンピューティングの作成) については、「Project アクセス許可を参照してください。

接続のタイムアウト

すべてのデータベース接続には、認証方法に関係なく、次の制限が適用されます。

• 24 時間アイドル タイムアウト: 24 時間アクティビティのない接続は自動的に閉じられます。
• 3日間の最大接続寿命: 3 日以上有効な接続は、アクティビティに関係なく閉じられる場合があります。

適切なタイムアウト設定で接続再試行ロジックを実装することで、接続タイムアウトを適切に処理するようにアプリケーションを設計します。

OAuth トークン認証

OAuth トークン認証を使用すると、Azure Databricks ID を使用して接続できます。 時間制限付きの OAuth トークンを生成し、Postgres に接続するときにパスワードとして使用します。

プロジェクト所有者の OAuth ロールが自動的に作成されます。 他のAzure Databricks ID に対して OAuth 認証を有効にするには、databricks_auth 拡張機能と SQL を使用して Postgres ロールを作成する必要があります。 SQL を使用した DB ID の OAuth ロールの作成を参照してください。

OAuth トークンのしくみ

• トークンの有効期間: OAuth トークンは 1 時間後に期限切れになります。
• 有効期限の適用: トークンの有効期限はログイン時にのみ適用されます。 トークンの有効期限が切れた後も、開いている接続はアクティブなままです。
• トークンの更新: 対話型セッションの場合は、必要に応じ新しいトークンを生成します。 実行時間の長い接続を使用するアプリケーションの場合は、 トークンローテーション を実装して資格情報を自動的に更新します。

要件と制限

• 対応する Postgres ロールが必要です: Azure Databricks ID には、対応する Postgres ロールが必要です。 プロジェクト所有者のロールが自動的に作成されます。 他のAzure Databricks ID の場合は、databricks_auth 拡張機能を使用してロールを作成します。
• ワークスペース スコープ: OAuth トークンはワークスペース スコープであり、プロジェクトを所有するのと同じワークスペースに属している必要があります。 ワークスペース間トークン認証はサポートされていません。
• SSL が必要: トークンベースの認証には SSL 接続が必要です。 すべてのクライアントは、SSL (通常は sslmode=require) を使用するように構成する必要があります。

ユーザーからマシンへのフローで OAuth トークンを取得する

データベース所有者、管理者、またはAzure Databricks ID にデータベースに対応する Postgres ロールがある場合は、UI、Databricks API、CLI、または Databricks SDK のいずれかから OAuth トークンを取得できます。

その他のAzure Databricks ID ユーザーについては、OAuth トークンを取得するためのワークスペース レベルの承認手順については、「Authorize user access to Azure Databricks with OAuth」を参照してください。

UI

psql や DBeaver などの SQL クライアントを使用する場合は、Lakebase UI を使用してトークンを生成します。

1. Lakebase アプリでプロジェクトに移動します。
2. 接続先のブランチとコンピューティングを選択します。
3. [ 接続 ] をクリックし、指示に従って OAuth トークンを生成します。

詳細な手順については、 OAuth ロールを使用した接続 に関する記事を参照してください。

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

応答：

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

データベースに接続するときに、 token 値をパスワードとして使用します。

Python SDK

Databricks SDK for Python を使用して OAuth トークンを生成できます。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

# Use the token to connect to Postgres
import psycopg2

conn = psycopg2.connect(
    host="ep-example.database.region.databricks.com",
    port=5432,
    database="databricks_postgres",
    user="your.email@company.com",
    password=credential.token,
    sslmode="require"
)

Java SDK

Databricks SDK for Java を使用して OAuth トークンを生成できます。

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

マシン間フローで OAuth トークンを取得する

データベースへの安全で自動化された (マシン間) アクセスを有効にするには、Azure Databricks サービス プリンシパルを使用して OAuth トークンを取得する必要があります。 このプロセスには、サービス プリンシパルの構成、資格情報の生成、認証用の OAuth トークンの作成が含まれます。

1. 無期限に有効な資格情報を使用してサービス プリンシパルを構成します。 手順については、「OAuth を使用したAzure Databricksへのサービス プリンシパル アクセスの認証を参照してください。
2. サービス プリンシパルとして新しい OAuth トークンを作成します。

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

応答：

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

データベースに接続するときに、 token 値をパスワードとして使用します。

Python SDK

Databricks SDK for Python を使用して OAuth トークンを生成できます。

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://<YOUR WORKSPACE URL>/",
    client_id="<YOUR SERVICE PRINCIPAL ID>",
    client_secret="REDACTED"
)

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

Java SDK

Databricks SDK for Java を使用して OAuth トークンを生成できます。

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.service.postgres.*;

// Initialize with service principal credentials
DatabricksConfig config = new DatabricksConfig()
    .setHost("https://<YOUR WORKSPACE URL>/")
    .setClientId("<YOUR SERVICE PRINCIPAL ID>")
    .setClientSecret("REDACTED");

WorkspaceClient w = new WorkspaceClient(config);

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

注

時間単位の有効期限が切れる前に OAuth トークンをローテーションする:

• 使用のたびに OAuth トークンの有効期限を確認し、必要に応じて更新します。
• または、現在の OAuth トークンを定期的に更新するようにバックグラウンド スレッドを設定します。

トークンローテーションの例

OAuth トークンは 1 時間後に期限切れになるため、実行時間の長いデータベース接続を維持するアプリケーションでは、資格情報を定期的に更新するためにトークンローテーションを実装する必要があります。 次の例では、アプリケーション コードでトークンを自動的にローテーションする方法を示します。

注

これらの例の要件:

• プロジェクトを所有するワークスペースに対して認証する必要があります。 WorkspaceClient()は、ワークスペースの OAuth 資格情報を使用してデータベース トークンを生成します。
• Azure Databricks ID は、プロジェクトが作成されたワークスペースのメンバーである必要があります。
• Lakebase アプリの [接続 ] ダイアログから接続パラメーター (ホスト、データベース、エンドポイント) を取得します。 詳細については、 クイック スタート を参照してください。
• endpoint パラメーターは、次の形式を使用します。projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

ワークスペース認証のセットアップについては、「OAuth または OAuth を使用したAzure Databricksへのサービス プリンシパル アクセスの認証を使用してAzure Databricksへのユーザー アクセスを認証する方法に関する説明を参照してください。

Python: psycopg3

この例では、psycopg3 の接続プールと、新しい接続が作成されるたびに新しい OAuth トークンを生成するカスタム接続クラスを使用します。 この方法により、プールからの各接続に有効な現在のトークンが常に含まれるようにします。

%pip install "psycopg[binary,pool]"

from databricks.sdk import WorkspaceClient

import psycopg
from psycopg_pool import ConnectionPool

w = WorkspaceClient()

class CustomConnection(psycopg.Connection):
    @classmethod
    def connect(cls, conninfo='', **kwargs):
        # Generate a fresh OAuth token for each new connection
        endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        kwargs['password'] = credential.token
        return super().connect(conninfo, **kwargs)

# Configure connection parameters (get these from the Connect dialog in the Lakebase App)
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create connection pool with custom connection class
pool = ConnectionPool(
    conninfo=f"dbname={database} user={username} host={host} sslmode=require",
    connection_class=CustomConnection,
    min_size=1,
    max_size=10,
    open=True
)

# Use the connection pool
with pool.connection() as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT version()")
        for record in cursor:
            print(record)

Python: SQLAlchemy

この例では、有効期限が切れる前に OAuth トークンを自動的に更新するイベント リスナーで SQLAlchemy の接続プールを使用します。 イベント リスナーは、プールから新しい物理接続が作成される前に起動し、有効期限が 2 分以内であればトークンを更新し、アプリケーションが手動介入なしで常に有効なトークンを持つようになります。

%pip install sqlalchemy psycopg2-binary databricks-sdk

from databricks.sdk import WorkspaceClient
import time

from sqlalchemy import create_engine, text, event

w = WorkspaceClient()

# Configure connection parameters (get these from the Connect dialog in the Lakebase App)
endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create SQLAlchemy engine
connection_pool = create_engine(f"postgresql+psycopg2://{username}:@{host}:{port}/{database}?sslmode=require")

# Global variables for token management
postgres_password = None
token_expiry = 0.0  # Unix timestamp when the current token expires

@event.listens_for(connection_pool, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    global postgres_password, token_expiry

    # Refresh token if None or expiring within 2 minutes
    if postgres_password is None or time.time() >= token_expiry - 120:
        print("Refreshing PostgreSQL OAuth token")
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        postgres_password = credential.token
        token_expiry = credential.expire_time.seconds

    cparams["password"] = postgres_password

# Use the connection pool
with connection_pool.connect() as conn:
    result = conn.execute(text("SELECT version()"))
    for row in result:
        print(f"Connected to PostgreSQL database. Version: {row}")

Postgres パスワード認証

ネイティブ Postgres パスワード認証では、従来の Postgres ロールとパスワードが使用されます。 OAuth トークンとは異なり、これらのパスワードは 1 時間後に有効期限が切れるので、頻繁な資格情報のローテーションを処理できないアプリケーションに適しています。

Postgres パスワードを使用するタイミング

Postgres パスワード認証は、次の場合に使用します。

• アプリケーションまたはツールで資格情報を 1 時間ごとに更新することはできません
• 安定した資格情報を必要とする実行時間の長いプロセスがある
• クライアント ライブラリで OAuth トークンのローテーションがサポートされていない
• 互換性のために従来のデータベース認証が必要です

Postgres パスワードのしくみ

• パスワードの有効期間: パスワードは自動的に期限切れになりません
• ワークスペースとの統合なし: 認証は Azure Databricks ワークスペース認証ではなく、Postgres によって処理されます
• 手動管理: パスワードを手動でローテーションし、ユーザーに配布する必要があります
• 接続タイムアウトは引き続き適用されます。パスワードの有効期限が切れない場合でも、接続には 24 時間のアイドル タイムアウトと 3 日間の最大接続時間が適用されます

セキュリティに関する考慮事項

• パスワード ストレージ: 環境変数またはシークレット管理システムを使用してパスワードを安全に格納する
• SSL が必要: すべての接続で SSL (sslmode=require) を使用する必要があります

次のステップ

• クイック スタート: データベースに接続する
• Postgres ロールの管理
• アクセス許可の管理
• データのクエリを実行する