本文档介绍如何为你的工具插件添加 OAuth 支持。
对于需要通过第三方服务（如 Gmail 或 GitHub）访问用户数据的工具插件而言，OAuth 是一种更好的授权方式：在获得用户明确同意的情况下，允许工具插件代表用户执行操作，而无需用户手动输入 API 密钥。
Dify 的 OAuth 配置涉及两个独立流程，开发者应当充分理解并根据流程进行设计。
流程一：OAuth 客户端设置（由管理员 / 开发者完成）
在 Dify Cloud 上，Dify 团队会为热门工具插件创建 OAuth 应用并设置 OAuth 客户端，为用户节省自行配置的麻烦。而对于自托管的 Dify 实例，管理员需自行完成此设置流程。
- 前往 API 和服务 > OAuth 权限请求页面。
- 对于公开插件，选择 外部 受众群体类型。
- 填写应用名称、用户支持邮箱和开发者联系方式。
- （可选）添加授权域名。
- 选择 目标对象 > 测试用户，添加测试用户以进行测试。
- 前往 API 和服务 > 凭证。
- 点击 创建凭证 > OAuth 客户端 ID。
- 选择 Web 应用，点击 创建。
- 保存生成的凭证信息，包括客户端 ID 和客户端密钥。
在 OAuth 客户端配置窗口中，输入客户端 ID（client_ID）和客户端密钥（client_secret），以将工具供应商设置为客户端。
在 Google OAuth 客户端页面，填写由 Dify 生成的重定向 URI。
Dify 在 OAuth 客户端配置弹窗中显示redirect_uri，通常遵循以下格式：https://{your-dify-domain}/console/api/oauth/plugin/{plugin-id}/{provider-name}/{tool-name}/callback
your-dify-domain 应与 CONSOLE_WEB_URL 保持一致。 不同第三方服务的要求各异，请务必查阅目标集成服务的特定 OAuth 文档。
流程二：用户授权（由 Dify 用户完成）
OAuth 客户端配置完成后，Dify 用户即可授权插件访问他们的个人账户。
1. 在供应商的 Manifest 文件中定义 OAuth 的参数架构
供应商的 Manifest 文件中的 oauth_schema 字段为插件 OAuth 定义凭证需求及授权流程产出，涉及以下两种参数架构。
client_schema
定义 OAuth 客户端设置所需的输入参数架构。
oauth_schema:
client_schema:
- name: "client_id"
type: "secret-input"
required: true
url: "https://developers.google.com/identity/protocols/oauth2"
- name: "client_secret"
type: "secret-input"
required: true
url 字段直接链接至第三方服务的帮助文档，有助于为管理员/开发人员解惑。
credentials_schema
定义用户授权流程产生的凭证参数架构（由 Dify 自动管理）。
# 同样在 oauth_schema 下
credentials_schema:
- name: "access_token"
type: "secret-input"
- name: "refresh_token"
type: "secret-input"
- name: "expires_at"
type: "secret-input"
同时包含 oauth_schema 和 credentials_for_provider 字段，为用户提供 OAuth 和 API 密钥两种认证选项。
2. 在工具供应商中完成所需的 OAuth 方法实现
在实现 ToolProvider 的位置，添加以下代码：
from dify_plugin.entities.oauth import ToolOAuthCredentials
from dify_plugin.errors.tool import ToolProviderCredentialValidationError, ToolProviderOAuthError
ToolProvider 类必须实现以下三个 OAuth 方法（以 GmailProvider 为例）：
为避免安全隐患，在任何情况下都不应在 ToolOAuthCredentials 的凭证中返回 client_secret（客户端密钥）。
def _oauth_get_authorization_url(self, redirect_uri: str, system_credentials: Mapping[str, Any]) -> str:
"""
使用 OAuth 客户端设置流程中的凭据生成授权 URL。
此 URL 是用户授权应用程序访问其资源的地址。
"""
# 生成随机状态值用于 CSRF 保护（建议所有 OAuth 流程使用）
state = secrets.token_urlsafe(16)
# 定义 Gmail 特定的作用域范围。请求最小必要权限
scope = "read:user read:data" # 替换为所需的权限范围
# 组装 Gmail 特定的请求参数
params = {
"client_id": system_credentials["client_id"], # 来自 OAuth 客户端设置
"redirect_uri": redirect_uri, # 由 Dify 生成，请勿修改
"scope": scope,
"response_type": "code", # 标准 OAuth 授权码流程
"access_type": "offline", # 关键：获取刷新令牌（若支持）
"prompt": "consent", # 当权限范围变更时强制重新授权（若支持）
"state": state, # CSRF 保护
}
return f"{self._AUTH_URL}?{urllib.parse.urlencode(params)}"
3. 在工具中访问令牌
你可以在 Tool 实现中使用 OAuth 凭证进行经过身份验证的 API 调用，示例如下：
class YourTool(BuiltinTool):
def _invoke(self, user_id: str, tool_parameters: dict[str, Any]) -> ToolInvokeMessage:
if self.runtime.credential_type == CredentialType.OAUTH:
access_token = self.runtime.credentials["access_token"]
response = requests.get("https://api.service.com/data",
headers={"Authorization": f"Bearer {access_token}"})
return self.create_text_message(response.text)
self.runtime.credentials 自动提供当前用户的令牌。Dify 自动处理令牌刷新机制。
对于同时支持 OAuth 和 API 密钥认证的插件，可使用 self.runtime.credential_type 来区分两种认证类型。
4. 指定正确的版本
插件 SDK 和 Dify 的早期版本不支持 OAuth 认证。因此，需将插件 SDK 版本设置如下：
dify_plugin>=0.4.2,<0.5.0.
manifest.yaml中， 添加最低 Dify 版本要求：
meta:
version: 0.0.1
arch:
- amd64
- arm64
runner:
language: python
version: "3.12"
entrypoint: main
minimum_dify_version: 1.7.1
编辑此页面 | 提交问题
