凭证覆盖
凭据覆盖允许你全局设置凭据数据。用户看不到这些数据,但 n8n 会在后台自动使用——例如通过「连接」按钮完成 OAuth 登录,而不暴露客户端密钥。
在编辑器 UI 中,n8n 默认隐藏所有被覆盖的字段,用户可通过凭据上的「连接」按钮使用 OAuth 认证。
有关用于配置凭证覆盖的环境变量,请参阅凭证环境变量。
观看凭证覆盖教程,其中包括如何使用 REST API 和现成的工作流模板 进行设置:
https://www.youtube.com/embed/VtCbCdKrqAE
使用环境变量
将 CREDENTIALS_OVERWRITE_DATA 设为 { CREDENTIAL_NAME: { PARAMETER: VALUE }}。
警告
不推荐这种方法。 n8n 中的环境变量不受保护,因此数据可能会泄露给用户。
使用 REST API
推荐通过自定义 REST 端点加载数据。
-
将
CREDENTIALS_OVERWRITE_ENDPOINT设置为端点应该可用的路径:sh export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials可选:设置
CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN,要求以 Bearer 令牌访问该端点。如果没有身份验证令牌,出于安全原因只能调用端点一次。
-
准备包含要覆盖凭据的 JSON 文件。例如 Asana 与 GitHub 的
oauth-credentials.json:json { "asanaOAuth2Api": { "clientId": "<id>", "clientSecret": "<secret>" }, "githubOAuth2Api": { "clientId": "<id>", "clientSecret": "<secret>" } } -
将文件发送到你的 n8n 实例:
sh curl -H "Content-Type: application/json" --data @oauth-credentials.json http://localhost:5678/send-credentials若
CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN设为secure-token:sh curl -H "Content-Type: application/json" -H "Authorization: Bearer secure-token" --data @oauth-credentials.json http://localhost:5678/send-credentials
提示
凭证可以扩展其他凭证。例如,googleSheetsOAuth2Api 扩展了 googleOAuth2Api。您可以在父级 (googleOAuth2Api) 上设置参数,所有子级凭据都将使用它们。
显示 OAuth scope 字段
默认情况下,当托管 OAuth 可用时,n8n 会隐藏 scope 字段。若要允许用户为特定的托管 OAuth 凭据类型配置 scope,请将 N8N_MANAGED_OAUTH_SHOW_SCOPES 设置为以逗号分隔的列表:
export N8N_MANAGED_OAUTH_SHOW_SCOPES=googleOAuth2Api
此设置仅适用于列表中的凭据类型,不适用于扩展所列类型的凭据类型。
警告
允许用户自行设置 scope 可能会破坏已验证的 OAuth 应用。许多提供商(例如 Google)要求您在应用验证期间定义并说明应用请求的每个 scope。如果用户添加了您未声明的 scope,提供商可能会暂停或封禁您的应用。仅当用户添加 scope 不会使应用验证面临风险时,才为相应凭据类型启用此设置。
持久性
若要将凭据覆盖存入数据库并在多实例或队列模式下传播到所有 worker,请启用:
export CREDENTIALS_OVERWRITE_PERSISTENCE=true
启用后,n8n 将加密后的覆盖项保存在 settings 表中,并广播 reload-overwrite-credentials 事件以便 worker 重新加载最新值。禁用时,覆盖项保留在加载它们的进程内存中,n8n 不会向 worker 传播,也不会在重启后保留。