对数据库实例进行身份验证

重要

此功能在以下区域中为公共预览版：westus、westus2、eastus、eastus2、centralus、southcentralus、northeurope、westeurope、australiaeast、brazilsouth、canadacentral、centralindia、southeastasia、uksouth。

本页介绍如何向 Lakebase 数据库实例进行身份验证。可通过两种方法进行身份验证：

获取 OAuth 令牌并使用 Azure Databricks 标识进行身份验证。
使用设置了密码的本机 Postgres 角色。

使用 Azure Databricks 标识进行身份验证

以 Azure Databricks 标识身份进行身份验证时，需要生成 OAuth 令牌，并在连接到 Postgres 时将其用作密码。

开始前的注意事项

OAuth 令牌在一小时后过期，但仅在登录时强制执行过期。即使令牌过期，打开的连接仍然处于活动状态。但是，如果令牌已过期，需要身份验证的任何 PostgreSQL 命令将失败。
用于 Postgres 身份验证的 OAuth 令牌是工作区范围的，应属于拥有数据库实例的同一工作区。不支持跨工作区令牌身份验证。若要了解有关身份验证的详细信息，请参阅 Databricks CLI 的身份验证。
基于令牌的身份验证需要纯文本密码，因此只允许 SSL 连接。确保用于通过基于令牌的身份验证访问 Postgres 的客户端库配置为建立 SSL 连接。

在用户到计算机流中获取 OAuth 令牌

如果你是数据库所有者、管理员或 Azure Databricks 标识具有相应的数据库实例 Postgres 角色，则可以从 UI、Databricks CLI 或 Databricks SDK 之一获取 OAuth 令牌。可以使用 Databricks CLI 适当限制令牌的范围。

对于其他 Azure Databricks 标识用户，请参阅授权用户使用 OAuth 访问 Azure Databricks 以获取 OAuth 令牌的工作区级授权说明。

UI

当数据库实例状态可用时，请使用 Azure Databricks UI 获取 OAuth 令牌：

在工作区边栏中单击 “计算 ”，然后单击 “Lakebase Postgres ”选项卡。
查找并单击要为其获取 OAuth 令牌的数据库实例的名称。
单击“连接详细信息”选项卡。
单击“ 获取 OAuth 令牌”。标志指示令牌的创建时间。
单击 “复制 OAuthToken ”将令牌复制到剪贴板。

CLI

当数据库实例状态可用时，请使用 Databricks CLI v0.256.0 及更高版本来获取 OAuth 令牌：

使用以下命令提取令牌。

 databricks database generate-database-credential \
   --request-id $(uuidgen) \
   --json '{
     "instance_names": ["db-instance-name"]
   }'

这会生成采用以下格式的响应。从响应复制 token。

{
  "expiration_time": "2025-08-24T14:15:22Z",
  "token": "<string>"
}

有关使用 Databricks CLI 获取 OAuth 令牌的详细信息，请参阅 OAuth 用户到计算机（U2M）身份验证。

Python SDK

可以使用用于 Python 的 Databricks SDK 生成 OAuth 令牌。用于 Python 的 Databricks SDK 版本 v0.56.0 中提供了 Azure Databricks SDK 绑定。

如果使用旧版 SDK 运行，请先运行这些命令。

%pip install --upgrade databricks-sdk
%restart_python

用于 Python 的 Databricks SDK 为数据库实例生成安全的 OAuth 令牌 cred。根据需要输入凭据。

from databricks.sdk import WorkspaceClient
import uuid

w = WorkspaceClient()

instance_name = "<YOUR INSTANCE>"

cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])

Java SDK

可以使用用于 Java 的 Databricks SDK 生成 OAuth 令牌。在 Databricks 的 Java SDK 版本 v0.53.0 或更高版本中提供了数据库 SDK 绑定。如果使用旧版 SDK 运行，则可能需要刷新导入的 SDK。有关详细信息，请参阅此文。

%scala

import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
import com.databricks.sdk.service.database.DatabaseInstance
import com.databricks.sdk.service.database.DatabaseCredential
import java.util.Collections
import java.util.UUID

val w = new WorkspaceClient()

val instanceName = "<YOUR INSTANCE>"

// Generate database credential
val cred = w.database().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setRequestId(UUID.randomUUID().toString())
        .setInstanceNames(Collections.singletonList(instanceName))
)

// Print out credential details
System.out.println("Credential: " + cred.getToken())

在计算机对计算机流中获取 OAuth 令牌

若要启用对数据库实例的安全、自动化（计算机到计算机）访问，必须使用 Azure Databricks 服务主体获取 OAuth 令牌。此过程涉及配置服务主体、生成凭据，并发行用于身份验证的 OAuth 令牌。

为服务主体配置无限期有效的凭据。有关说明，请参阅使用 OAuth 授权服务主体访问 Azure Databricks。

以服务主体的身份生成新的 OAuth 令牌。

CLI

当数据库实例状态可用时，请使用 Databricks CLI v0.256.0 及更高版本来获取 OAuth 令牌：

使用以下命令提取令牌。

  databricks database generate-database-credential \
    --request-id $(uuidgen) \
    --json '{
      "instance_names": ["db-instance-name"]
    }'

这会生成采用以下格式的响应。从响应复制 token。

{
  "expiration_time": "2025-08-24T14:15:22Z",
  "token": "<string>"
}

Python SDK

可以使用用于 Python 的 Databricks SDK 生成 OAuth 令牌。用于 Python 的 Databricks SDK 版本 v0.56.0 中提供了 Azure Databricks SDK 绑定。

如果使用旧版 SDK 运行，请先运行这些命令。

%pip install --upgrade databricks-sdk
%restart_python

用于 Python 的 Databricks SDK 为数据库实例生成安全的 OAuth 令牌 cred。根据需要输入数据库实例名称。

from databricks.sdk import WorkspaceClient
import uuid

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

instance_name = "<YOUR INSTANCE>"

cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])

Java SDK

可以使用用于 Java 的 Databricks SDK 生成 OAuth 令牌。在 Databricks 的 Java SDK 版本 v0.53.0 或更高版本中提供了数据库 SDK 绑定。如果使用旧版 SDK 运行，则可能需要更新到较新的 SDK。有关详细信息，请参阅此文。

%scala

import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.core.DatabricksConfig
import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
import com.databricks.sdk.service.database.DatabaseInstance
import com.databricks.sdk.service.database.DatabaseCredential
import java.util.Collections
import java.util.UUID

val config = new DatabricksConfig() // See https://github.com/databricks/databricks-sdk-java#authentication
val w = new WorkspaceClient(config)

val instanceName = "<YOUR INSTANCE>"

// Generate database credential
val cred = w.database().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setRequestId(UUID.randomUUID().toString())
        .setInstanceNames(Collections.singletonList(instanceName))
)

// Print out credential details
System.out.println("Credential: " + cred.getToken())

注释

在每小时过期之前轮换 OAuth 令牌：

根据需要检查每次使用和刷新 OAuth 令牌的过期时间。
或者，设置后台线程以定期刷新当前 OAuth 令牌。

排查令牌标识问题

如果令牌的标识与安全标签不匹配，可能会收到如下所示的错误消息。

A valid oauth token was supplied but the token's identity "<USER>" did not match the security label configured for role "<SERVICE PRINCIPAL>". Please ensure that the token is generated for the correct databricks identity.

运行以下命令来检查返回的 Azure Databricks 标识：

CLI

databricks current-user me

Python SDK

w.current_user.me().user_name

Java SDK

w.currentUser.me().getUserName()

如果未返回预期的标识，请验证初始化工作区客户端时是否使用了正确的凭据。

使用 Microsoft Entra ID 进行身份验证

对于 Azure Databricks，Microsoft Entra ID 标识和令牌也可用于向 Azure Databricks API 进行身份验证。使用这些 API 获取令牌以向 Postgres 进行身份验证。

有关如何在 Azure Databricks 中管理 Microsoft Entra ID 托管标识，请参阅管理用户、服务主体和组。可以在 Azure Databricks 中创建来自 Microsoft Entra ID 的用户、组和服务主体。将这些标识添加到 Azure Databricks 后，可以将它们添加到数据库实例，如 “管理 Postgres”角色中所述。

若要检索Microsoft Entra ID 令牌，请参阅以下内容：

作为 Azure Databricks 组进行身份验证

组和组成员身份不会从 Azure Databricks 同步到 Postgres，Unity Catalog 权限也不会同步。但是，将 Azure Databricks 组添加到 Postgres 后，组中的任何 Azure Databricks 用户都可以使用用户的密码以组身份登录。这样，就可以在 Postgres 中的组级别管理权限。 Azure Databricks 组标识的任何直接或间接成员（用户或服务主体）都可以向 Postgres 进行身份验证，并作为 Azure Databricks 组 Postgres 角色登录。

使用用户或服务主体令牌以组标识身份进行身份验证时，仅在身份验证时验证组成员身份。如果成员在身份验证后被从组中删除，任何与组成员令牌有关的已打开连接都将保持打开状态。从已删除的组成员发送的任何新连接请求都会在身份验证期间被拒绝。

export PGPASSWORD='<OAuth token of a group member>'
export GROUPROLENAME=<pg-case-sensitive-group-role-name>

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUPROLENAME

仅支持为数据库实例 Azure Databricks 工作区分配的组进行基于组的 Postgres 登录。若要了解如何将组分配到工作区，请参阅向工作区分配组。

使用 Postgres 角色和密码进行身份验证

如果客户端在一小时后不支持凭据轮换，你可以使用密码创建本机 Postgres 角色：

在工作区边栏中单击 “计算 ”。
单击“ 数据库实例 ”选项卡。
选择要更新的数据库实例。
单击右上角的 “编辑 ”。
启用 PostgreSQL 原生角色登录功能。
单击“ 保存”。
登录到 Postgres 或使用 SQL 编辑器创建具有密码的角色。
```
CREATE ROLE new_role LOGIN PASSWORD 'your strong password';
```
向新角色授予其他 Postgres 权限。请参阅使用 PostgreSQL 向 Postgres 角色授予权限。

后续步骤

获取凭据（OAuth 令牌或密码）后，可以连接到数据库实例：

反馈

此页面是否有帮助？

Last updated on 2025-12-03

通过

对数据库实例进行身份验证

使用 Azure Databricks 标识进行身份验证

开始前的注意事项

在用户到计算机流中获取 OAuth 令牌

UI

CLI

Python SDK

Java SDK

在计算机对计算机流中获取 OAuth 令牌

CLI

Python SDK

Java SDK

排查令牌标识问题

CLI

Python SDK

Java SDK

使用 Microsoft Entra ID 进行身份验证

作为 Azure Databricks 组进行身份验证

使用 Postgres 角色和密码进行身份验证

后续步骤

反馈

其他资源