Databricks 凭据
您可以使用这些凭据对以下节点进行身份验证:
- Databricks
- Databricks AI Agent(仅支持 OAuth2,用于 MLflow trace 导出)
- Databricks Chat Model 聊天模型(仅支持 OAuth2)
- Databricks Genie One MCP 服务器(仅支持使用用户登录的 OAuth2)
- Databricks Lakebase Chat Memory(仅支持 OAuth2)
- Databricks Trigger 触发器
- Databricks Vector Store(仅支持 OAuth2)
- Embeddings Databricks(仅支持 OAuth2)
先决条件
- 在 AWS、Azure 或 GCP 上拥有 Databricks 工作区。
- 使用用户登录 OAuth2:可在账户控制台创建自定义 OAuth 应用连接的 Databricks 账户管理员。
- 使用服务主体 OAuth2:可创建服务主体并生成 OAuth 密钥的 Databricks 管理员。
- 执行所需操作所需的Databricks 权限。
支持的认证方式
- 个人访问令牌:绑定到一个 Databricks 用户的令牌。仅 Databricks 节点支持此方式,且该节点的 Lakebase 资源不支持。
- OAuth2(用户登录):在浏览器中登录 Databricks 账户来连接凭证。操作使用该用户的权限运行,并以其身份出现在 Databricks 审计日志中。每位用户都可以创建自己的凭证,以自己的账户运行工作流。Databricks 建议将此方式用于有人参与的交互场景。
- OAuth2(服务主体):n8n 使用客户端 ID 和密钥以服务主体身份进行身份验证,无需用户交互。Databricks 建议将此方式用于无人值守场景,例如完全自动化的生产工作流。
所需 Databricks 权限
凭证所认证的身份(登录用户或服务主体)需要根据操作拥有以下权限:
| 操作 | 所需权限 |
|---|---|
| 所有操作 | Workspace access 权利 |
| Databricks SQL(执行查询) | Databricks SQL access 权利和 SQL 仓库的 CAN USE |
| Job 作业(Get 获取、Get Run 获取运行记录、Get Run Output 获取运行输出) | 作业的 CAN VIEW 权限 |
| Job 作业(Run 运行) | 作业的 CAN MANAGE RUN 权限 |
| Lakebase | 项目分支上的 Postgres 角色;该角色需授予 authenticator,并拥有操作所需的表和函数权限。请参阅为 Data API 设置 Lakebase |
| 读取或写入 Unity Catalog 数据 | 目录上的 USE CATALOG、schema 上的 USE SCHEMA,以及查询的表或视图上的 SELECT;函数和模型还需要 EXECUTE |
| Genie Agent(Databricks 节点) | Genie Agent 的 CAN RUN 和其 SQL 仓库的 CAN USE |
| Genie One MCP 服务器 | Genie One 可用于回答的每个 Genie Agent 都需要 CAN RUN,至少一个 SQL 仓库需要 CAN USE,并且需要对 system.ai.genie_one_mcp 拥有 EXECUTE。默认情况下,Databricks 会向所有用户授予 system.ai 服务的 EXECUTE 权限 |
| 模型服务(查询端点) | 服务端点的 CAN QUERY |
| Unity AI Gateway 模型服务(Databricks Chat Model、Embeddings Databricks) | 模型服务所在目录和架构的 USE CATALOG 与 USE SCHEMA,以及模型服务的 EXECUTE。默认情况下,Databricks 会向所有用户授予 system.ai 服务的 EXECUTE 权限 |
| 搜索 Vector Search 索引(Databricks Vector Store:Get Many、Retrieve Documents、Retrieve as Tool) | 索引所在 catalog 的 USE CATALOG、schema 的 USE SCHEMA,以及索引的 SELECT。对于同步所有列的 Delta Sync 索引,对源表拥有 SELECT 后,节点才能列出这些列。自管理索引还需要上方 Embeddings Databricks 节点所用的模型服务权限。Metadata Filter 元数据筛选器需要 Vector Search endpoint 的读取权限 |
| 插入文档(Databricks Vector Store:Insert Documents) | 搜索所需权限,以及索引的 MODIFY。只有 Direct Access 索引接受插入 |
| 将 trace 导出到 MLflow(Databricks AI Agent) | Experiment 的 CAN EDIT。节点在 /Shared 下创建的默认 experiment 无需额外授权,因为默认情况下所有工作区用户都对 /Shared 文件夹拥有 CAN MANAGE |
| 监视作业或管道(Databricks Trigger) | 作业或管道的 CAN VIEW 权限 |
提示
新服务主体没有权限
新建服务主体没有任何授权,因此首次操作会因权限错误而失败,错误中会指出缺少的授权。请在运行工作流前分配上述权限。
有关更多信息,请参阅 Databricks 权利、访问控制列表和 Unity Catalog 权限。
相关资源
有关此服务的更多信息,请参阅 Databricks 身份验证文档。
使用个人访问令牌
要配置此凭据,您需要:
- Host 主机:Databricks 工作区的 URL(例如
https://adb-1234567890123456.7.azuredatabricks.net)。 - Access Token 访问令牌:在 Databricks 工作区中生成的个人访问令牌。
生成个人访问令牌的步骤:
- 在 Databricks 工作区中,选择右上角的用户名,然后选择 Settings 设置。
- 选择 Developer 开发者。
- 在 Access tokens 访问令牌 旁边,选择 Manage 管理。
- 选择 Generate new token 生成新令牌。
- 可选输入 Comment 备注 以标识令牌,然后选择 Generate 生成。
- 复制令牌并妥善保存。关闭此对话框后将无法再次查看令牌。
- 在 n8n 凭据中将令牌输入为 Access Token 访问令牌。
提示
Token format 令牌格式
个人访问令牌以 dapi 开头,例如 dapi1234abcd5678efgh。
有关更多信息,请参阅 Databricks 个人访问令牌身份验证。
使用 OAuth2(用户登录)
此方法使用 Databricks OAuth 用户到机器(U2M)流程。您在浏览器中登录 Databricks 来连接凭证,操作会使用您的权限运行。共享凭证会以连接它的用户身份运行,因此不同身份应创建不同的凭证。
要配置此凭证,您需要:
- Host 主机:Databricks 工作区的 URL(例如
https://adb-1234567890123456.7.azuredatabricks.net)。 - Client ID 客户端 ID 和 Client Secret 客户端密钥:由 Databricks 账户管理员在账户控制台中创建的自定义 OAuth 应用连接提供。
设置此凭证分为三个步骤:
提示
需要账户控制台访问权限
创建自定义 OAuth 应用连接需要 Databricks 账户控制台。Databricks Free Edition 不提供账户控制台访问权限,因此 Free Edition 工作区请使用服务主体或个人访问令牌。
创建自定义 OAuth 应用连接
Databricks 账户管理员需要完成以下步骤:
- 在 n8n 中打开 Databricks 凭证,复制 OAuth Redirect URL(格式为
https://<your-n8n-instance>/rest/oauth2-credential/callback)。 - 登录对应云平台的 Databricks 账户控制台(AWS、Azure 或 GCP),然后在侧边栏选择 Settings 图标。
- 在 App connections 标签页选择 Add connection。
- 输入连接名称,例如
n8n。 - 将从 n8n 复制的 OAuth Redirect URL 添加为重定向 URL。
- 选择连接所需的访问 scope。Databricks 节点和 Databricks Chat Model 节点需要 All APIs。如果此连接只用于 Genie One MCP 服务器,请改为选择
ai-gateway:连接将无法调用 All APIs 所覆盖的 Databricks REST API,用户也只需同意范围更窄的授权。ai-gatewayscope 仍覆盖用户 Unity Catalog 权限内的其他 AI Gateway 服务,例如 Databricks SQL MCP 服务器。Databricks 会自动允许 n8n 保持连接所需的offline_accessscope。All APIs 选项不包含ai-gatewayscope,因此同时服务于该卡片和其他节点的连接需要两者。请参阅添加ai-gatewayscope。 - 启用客户端密钥生成。n8n 是机密客户端,因此需要密钥。
- 保存连接,然后复制 Client ID 和 Client Secret。Databricks 只显示一次密钥。
将客户端 ID 和密钥分享给需要创建凭证的 n8n 用户。所有用户可复用同一个 OAuth 应用连接,但每个用户都应创建并连接自己的 n8n 凭证,以自己的身份运行。
更多信息请参阅启用或禁用合作伙伴 OAuth 应用。
为 Genie One MCP 服务器添加 ai-gateway scope
Databricks Genie One MCP 服务器卡片通过工作区的 AI Gateway 端点调用 Genie One,并请求 ai-gateway 和 offline_access scope。All APIs 选项不包含 ai-gateway:在 n8n 的测试中,只有管理员把该 scope 加到连接上之后,带有 All APIs 的应用连接才会返回包含 ai-gateway scope 的 token。根据 Databricks 账户不同,用户会看到两种错误之一。要么连接凭据失败并显示:
access_denied: Scopes 'ai-gateway' are not assigned to the client <client-id>
要么连接成功,但 agent 一开始运行就失败并显示:
Invalid scope, required scopes: ai-gateway
要修复这两种错误,Databricks 账户管理员需要向应用连接添加 ai-gateway scope。如果账户控制台中的连接页面在 Add scope 选择器中提供 ai-gateway,请直接添加。否则,请使用已针对该账户完成身份验证的 Databricks CLI。CLI 更新会替换整个 scope 列表,因此必须包含应用所需的每个 scope。如果一个应用连接同时服务于 Databricks 节点、Databricks Chat Model 节点和 Genie One MCP 服务器,则需要以下三个 scope:
databricks account custom-app-integration update <integration-id> \
--json '{"scopes": ["all-apis", "ai-gateway", "offline_access"]}'
可以使用 databricks account custom-app-integration list 查找 <integration-id>,也可以在账户控制台的连接详情页中查看。API 参考请参阅 Update Custom OAuth App Integration。
管理员添加 scope 后,每个用户都要重新连接他们用于该卡片的凭据,这样 n8n 才会收到带有新 scope 的 token。刷新旧 token 不会加上这个 scope。
Databricks 同意页面不会显示 token 实际获得哪些 scope。在 n8n 的测试中,页面列出了 ai-gateway,但应用连接并没有该 scope,n8n 收到的 token 也不包含它。要检查设置,请在账户控制台查看应用连接的 scopes。
如果应用连接仅服务于 Genie One MCP 服务器,请将 scope 改为 ["ai-gateway", "offline_access"]。这样用户看到并同意的授权范围更窄,其中不包括 Databricks REST API,但仍包括其他 AI Gateway 服务。
警告
没有 ai-gateway scope 的应用连接
在卡片于 2026 年 10 月 30 日改用 AI Gateway 端点之前,它请求的是 genie scope。为 genie scope 设置的应用连接仍可用于它已经服务的节点,但该卡片需要加上 ai-gateway。管理员添加 scope 后,每个用户都要重新连接自己的 Genie One 凭据,这样 n8n 才会收到带有新 scope 的 token。所有用户都重新连接后,可以从连接中移除 genie,除非还有其他集成仍在调用 beta 端点。Databricks 将于 2026 年 11 月 30 日停用该端点。
配置令牌生命周期
应用连接的令牌访问策略决定用户连接保持有效的时长:
- 访问令牌 TTL:每个访问令牌的有效期,默认为 60 分钟。n8n 使用刷新令牌自动续期,因此可以保留默认值。
- 刷新令牌 TTL:刷新令牌的有效期,默认为 10080 分钟(7 天),最长 129600 分钟(90 天)。刷新令牌过期后,凭证会停止工作,直到用户在 n8n 中重新打开凭证并登录。
Databricks 账户管理员还可以通过账户 API 或 CLI设置绝对会话生命周期和一次性刷新令牌。达到绝对会话生命周期后,即使刷新令牌仍有效,会话也会结束。
警告
较短的生命周期会要求重新连接
较短的刷新令牌 TTL 或绝对会话生命周期意味着用户必须定期重新打开凭证并登录;在此期间使用该凭证的工作流会失败。对于运行定时工作流的凭证,请设置较长的生命周期,或改用服务主体。
在 n8n 中设置凭证
- 输入工作区 URL 作为 Host。
- 将 Grant Type 设置为 Authorization Code (User)。
- 输入自定义 OAuth 应用连接提供的 Client ID 和 Client Secret。
- 选择 Connect 连接,然后使用 Databricks 账户登录。
默认情况下,凭证请求 all-apis 和 offline_access 范围。offline_access 可使连接保持超过一小时,因此始终包含该范围:如果启用 Custom Scopes 并将其移除,n8n 会自动将其加回。
使用 OAuth2(服务主体)
此方法使用 Databricks 服务主体和 OAuth M2M(机器对机器)流程。这是自动化工作流的推荐方法,因为它不需要用户交互。
要配置此凭据,您需要:
- Host 主机:您的 Databricks 工作区的 URL(例如
https://adb-1234567890123456.7.azuredatabricks.net)。 - Client ID 客户端 ID:您的服务主体的应用 ID。
- Client Secret 客户端密钥:为服务主体生成的 OAuth 密钥。
设置此凭据需要两个步骤:
创建服务主体和 OAuth 密钥
- 在 Databricks 账户控制台中,选择 User management 用户管理。
- 选择 Service principals 服务主体,然后选择 Add service principal 添加服务主体。
- 输入服务主体的名称,然后选择 Add 添加。
- 打开服务主体,进入 Configuration 配置 选项卡,授予其所需的工作区权限。
- 进入 Secrets 密钥 选项卡,选择 Generate secret 生成密钥。
- 设置密钥的有效期天数(最长 730 天),然后选择 Generate 生成。
- 复制显示的 Secret 密钥 和 Client ID 客户端 ID(与应用 ID 相同)。密钥仅显示一次。
提示
Workspace assignment 工作空间分配
必须将服务主体分配给它将访问的工作区,并授予 Workspace access 权利。只存在于账户级别的服务主体会从工作区 token endpoint 收到 invalid_client,看起来像 client secret 错误。转到 Permissions 权限 选项卡并授予所需的用户或组访问权限来管理和使用服务主体。
警告
OAuth 密钥会过期
服务主体密钥最长有效期为 730 天。到期后凭证会停止工作,使用它的工作流会失败。请跟踪到期日期,在到期前生成新密钥,并更新 n8n 凭证中的 Client Secret。
有关更多信息,请参阅 通过 OAuth 授权服务主体访问 Databricks。
设置 OAuth2 凭证
在 n8n 凭据中:
- 将 Authentication 身份验证 设置为 OAuth2。
- 输入您的工作区 URL 作为 Host 主机。
- 将 Grant Type 授权类型 设置为 Client Credentials (Service Principal)(默认值)。
- 输入您从服务主体复制的 Client ID 客户端 ID。
- 输入您生成的 Client Secret 客户端密钥。
为 Data API 设置 Lakebase
Databricks 节点上的 Lakebase 资源通过 Lakebase Data API 读写数据行。API 默认关闭,凭据所认证的身份必须先拥有 Postgres 角色,才能执行任何操作。请按以下顺序完成设置。各步骤的作用域不同:每个项目只需启用一次 Data API 和 OpenAPI specification;每个分支都要创建一次 Postgres 角色并将其授予 authenticator;节点访问的每个数据库都要安装 databricks_auth extension,并授予表和函数权限。
提示
The Data API doesn't accept personal access tokens Data API 不接受个人访问令牌
节点会在调用 Data API 前检查,因此使用个人访问令牌会显示 Lakebase requires OAuth2 authentication,而不是 Databricks 返回的错误。请将节点的 Authentication 身份验证设为 OAuth2,并使用通过用户登录使用 OAuth2或通过服务主体使用 OAuth2。
启用 Data API
在 Databricks 中打开 Lakebase 项目,然后选择 App Backend > Data API > Enable Data API。此步骤没有 API 或 CLI。Databricks 会创建下方授权所需的 authenticator 角色。
API 默认仅公开 public schema。请在相同设置中添加需要访问的其他 schema。
启用 OpenAPI specification
在同一项目中,选择 Data API > API > Advanced settings > OpenAPI specification,然后选择 Follow privileges。选择 Save 应用更改;更改会立即生效。
节点读取此文档,以列出表、函数、表的列和函数参数。未启用时,Table 表、Function 函数和列列表会显示错误,Columns 列和 Arguments 参数 mapper 则保持为空并显示提示。每条消息都会指出相同设置:
Data API > API > Advanced settings > OpenAPI specification
Follow privileges 仅列出已连接身份可使用的对象。Ignore privileges 会列出所有对象,包括 Databricks 创建的内部表和函数。
为 n8n 身份创建 Postgres 角色
在 Lakebase SQL editor 中,以能够管理项目的身份运行:
CREATE EXTENSION IF NOT EXISTS databricks_auth;
SELECT databricks_create_role('<identity>', 'SERVICE_PRINCIPAL');
<identity> 是服务主体的 application ID。对于用户身份,请改为传入电子邮件地址和 'USER'。
Postgres extension 属于单个数据库。请在节点访问的每个数据库中运行 CREATE EXTENSION。角色覆盖整个分支,而不是单个数据库。对于身份尚无角色的每个分支,请再次运行 databricks_create_role。缺少角色时,Data API 返回 invalid token permissions(PGRST301)。
即使该身份已显示在 Databricks UI 中,也应使用这种方式创建角色。下一步只能用于通过 databricks_create_role 创建的角色。
将角色授予 authenticator
<role> 是传给 databricks_create_role 的身份。对于服务主体,请使用 application ID;对于用户,请使用电子邮件地址。
GRANT "<role>" TO authenticator;
请以角色创建者身份运行此语句。没有此授权,任何角色都无法访问 Data API。在执行该语句前,操作会失败并显示 permission denied to set role。
接下来像处理其他 Postgres 角色一样,授予该角色访问数据所需的权限。请在包含节点所用表或函数的每个数据库中运行:
GRANT USAGE ON SCHEMA <schema> TO "<role>";
GRANT SELECT, INSERT, UPDATE, DELETE ON <table> TO "<role>";
GRANT USAGE ON ALL SEQUENCES IN SCHEMA <schema> TO "<role>";
GRANT EXECUTE ON FUNCTION <function>(<argument-types>) TO "<role>";
除 public 外,每个 schema 都需要 USAGE。如果没有 sequence 授权,向 serial 列插入时会失败并显示 permission denied for sequence。
警告
Don't connect as the project owner 不要以项目所有者身份连接
Databricks 特意禁止数据库所有者使用 Data API。所有者无法将自己的角色授予 authenticator,授权会失败并显示 permission denied to grant role。请使用不拥有该项目的身份。