Сведения о проверке подлинности

Узнайте, как пройти проверку подлинности подключений к базе данных Lakebase Postgres. Пошаговые инструкции по подключению см. в кратком руководстве.

Обзор

Lakebase поддерживает два метода проверки подлинности, каждый из которых предназначен для различных вариантов использования:

Аутентификация токенов OAuth: Использует удостоверения Azure Databricks с временными токенами OAuth. Лучше всего:

Интерактивные сеансы, в которых можно обновить маркеры
Рабочие процессы, интегрированные с рабочей областью
Приложения, которые могут реализовать ротацию токенов
Когда требуется управление проверкой подлинности с помощью Azure Databricks

Собственная проверка подлинности паролей Postgres: Использует традиционные роли Postgres с паролями. Лучше всего:

Приложения, которые не могут обновлять учетные данные почасово
Длительные процессы
Средства, которые не поддерживают ротацию токенов

Замечание

Управление платформой и доступ к базе данных. Эта страница посвящена проверке подлинности базы данных (маркеры OAuth и пароли Postgres для подключения к базе данных). Аутентификация для управления платформой (создание проектов, ветвей, вычислений) см. раздел Разрешения проекта.

Время ожидания подключения

Все подключения к базе данных применяются к следующим ограничениям независимо от метода проверки подлинности:

24-часовое время ожидания простоя: Подключения без действия в течение 24 часов автоматически закрываются.
3-дневное максимальное время подключения: Подключения, которые поддерживаются более 3 дней, могут быть закрыты, независимо от активности.

Спроектируйте приложения для обработки времени ожидания подключения, реализовав логику повторных попыток подключения с соответствующими параметрами времени ожидания.

Аутентификация токена OAuth

Аутентификация токена OAuth позволяет установить соединение, используя удостоверение Azure Databricks. Вы создаете маркер OAuth с ограниченным временем и используете его в качестве пароля при подключении к Postgres.

Роль OAuth владельца проекта создается автоматически. Чтобы включить проверку подлинности OAuth для других удостоверений Azure Databricks, необходимо создать их роли Postgres с помощью расширения databricks_auth и SQL. См. Создание роли OAuth для идентификации БД с помощью SQL.

Как работают токены OAuth

Время существования токена: Срок действия маркеров OAuth истекает через один час.
Принудительное применение истечения срока действия: Истечение срока действия токена применяется только при входе. Открытые подключения остаются активными даже после истечения срока действия маркера.
Обновление маркера: Для интерактивных сеансов при необходимости создайте новый маркер. Для приложений с длительными подключениями реализуйте ротацию токенов для автоматического обновления учетных данных.

Требования и ограничения

требуется роль Corresponding Postgres: удостоверение Azure Databricks должно иметь соответствующую роль Postgres. Роль владельца проекта создается автоматически. Для других удостоверений Azure Databricks создайте свои роли с помощью расширения databricks_auth.
Ограничение по рабочей области: Маркеры OAuth имеют область действия, ограниченную рабочей областью, и должны принадлежать той же рабочей области, которая владеет проектом. Аутентификация токена между рабочими пространствами не поддерживается.
Требуется SSL: аутентификация на основе токенов требует SSL-подключений. Все клиенты должны быть настроены для использования SSL (обычно sslmode=require).
Пул подключений не поддерживается: встроенный пул подключений PgBouncer не поддерживает проверку подлинности OAuth. Используйте собственные роли паролей Postgres для подключений в пуле. См. раздел "Использование пула подключений".

Получение маркера OAuth в потоке "пользователь — компьютер"

Если вы являетесь владельцем базы данных, администратором или ваше удостоверение Azure Databricks имеет соответствующую роль Postgres для базы данных, вы можете получить OAuth токен из пользовательского интерфейса, API Databricks, CLI или одного из SDK Databricks.

Для других пользователей удостоверений Azure Databricks см. Авторизация доступа пользователей к Azure Databricks с помощью OAuth для получения инструкций по авторизации на уровне рабочей области и получения токенов OAuth.

Пользовательский интерфейс

При использовании клиентов SQL, таких как psql или DBeaver, используйте пользовательский интерфейс Lakebase для создания маркеров:

Перейдите к проекту в приложении Lakebase.
Выберите ветвь и вычислительные ресурсы, к которым вы хотите подключиться.
Нажмите кнопку Connect и следуйте инструкциям по созданию маркера 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 Используйте значение в качестве пароля при подключении к базе данных.

пакет SDK Python

Маркер OAuth можно создать с помощью пакета SDK Databricks для Python.

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 psycopg

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

пакет SDK Java

Вы можете создать маркер OAuth с помощью Databricks SDK для Java.

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 в процессе авторизации между машинами

Чтобы обеспечить безопасный автоматизированный (машина-машина) доступ к базе данных, необходимо получить маркер OAuth с помощью сервисного принципала Azure Databricks. Этот процесс включает настройку главного объекта службы, создание учетных данных и выпуск токенов OAuth для аутентификации.

Настройте учетную запись службы с бессрочными учетными данными. Для получения инструкций см. раздел Авторизация доступа субъекта-службы к Azure Databricks с помощью 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 Используйте значение в качестве пароля при подключении к базе данных.

пакет SDK Python

Маркер OAuth можно создать с помощью пакета SDK Databricks для Python.

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}")

пакет SDK Java

Вы можете создать маркер OAuth с помощью Databricks SDK для Java.

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 истекает через один час, приложения, поддерживающие длительные подключения к базе данных, должны периодически реализовывать смену маркеров для периодического обновления учетных данных. В следующих примерах показано, как автоматически повернуть маркеры в коде приложения.

Замечание

Требования к этим примерам:

Необходимо пройти аутентификацию в рабочей области, владеющей проектом. Эта WorkspaceClient() использует учетные данные OAuth вашей рабочей области для генерации токенов базы данных.
Ваш идентификатор Azure Databricks должен быть включен в рабочую область, в которой был создан проект.
Получите параметры подключения (узел, база данных, конечная точка) из диалогового окна "Подключение " в приложении Lakebase. Подробности см. в Руководстве по быстрому старту.
Параметр endpoint использует формат: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

Сведения о настройке проверки подлинности рабочей области см. в разделах Авторизация доступа пользователей к Azure Databricks с помощью OAuth или Авторизация доступа субъектов-служб к Azure Databricks с помощью OAuth.

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

В этом примере используется пул соединений SQLAlchemy с прослушивателем событий, который автоматически обновляет маркер OAuth до истечения срока действия. Прослушиватель событий запускается перед созданием каждого нового физического подключения из пула и обновляет маркер, если до истечения его срока действия остается менее 2 минут, гарантируя, что приложение всегда имеет действительный маркер без ручного вмешательства.

%pip install sqlalchemy==2.0.36 "psycopg[binary]==3.2.3" databricks-sdk==0.79.0

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+psycopg://{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

Замечание

Подключения к паролям отключены по умолчанию для новых проектов автомасштабирования Lakebase. Чтобы включить их, см. статью "Управление подключениями к паролям".

Встроенная проверка подлинности паролей Postgres использует традиционные роли Postgres с паролями. В отличие от токенов OAuth эти пароли не истекают через час, что делает их подходящими для приложений, которые не могут обрабатывать частые смены учетных данных.

Когда следует использовать пароли Postgres

Используйте проверку подлинности паролей Postgres, если:

Приложение или средство не может обновлять учетные данные каждый час
У вас есть долговременные процессы, требующие устойчивых учетных данных
Клиентская библиотека не поддерживает смену маркера OAuth
Для обеспечения совместимости требуется традиционная проверка подлинности базы данных

Как работают пароли Postgres

Время существования пароля: срок действия паролей не истекает автоматически
No workspace integration: проверка подлинности обрабатывается Postgres, а не аутентификацией рабочей области Azure Databricks
Управление вручную: пароли должны вращаться вручную и распределяться между пользователями
Время ожидания подключения по-прежнему применяется: даже если срок действия паролей не истекает, подключения по-прежнему подвергаются времени простоя — 24 часа и максимальной продолжительности подключения в 3 дня.

Вопросы безопасности

Хранилище паролей. Безопасное хранение паролей с помощью переменных среды или систем управления секретами
Протокол SSL: все подключения должны использовать SSL (sslmode=require)

Пулинг соединений

Собственные роли паролей Postgres поддерживают встроенный пул подключений PgBouncer. Пулизатор уменьшает затраты на подключение для приложений с высокой пропускной способностью. См. раздел "Использование пула подключений".

Дополнительные ресурсы

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-24