我在为企业搭建 AI 应用平台时，最常被问到的问题就是：“怎么让团队成员用公司账号登录 Dify，而不是每个人单独注册？”这个问题涉及到 SSO（单点登录）认证。对于没有技术背景的同学来说，SSO 可能是个陌生的概念。简单来说，SSO 就是让你用公司邮箱和密码，一次登录后就能访问所有内部系统，不用记无数个账号密码。
今天这篇文章，我将从零开始，手把手教大家如何在 Dify 中配置 SSO 认证，实现企业身份集成。不管你是刚入门的新手，还是想提升企业安全管理的开发者，这篇教程都能帮到你。
一、什么是 SSO？为什么企业需要它
先给新手同学解释一下 SSO 的概念。想象一下，你们公司有十几套系统：邮箱、报销系统、项目管理工具、审批流程等等。如果每套系统都要单独注册账号，那员工就要记十几套密码，这显然是噩梦。SSO 就是来解决这个问题的——用一个公司账号登录，所有系统都能用。
在 Dify 中配置 SSO 有几个明显的好处：
- 统一管理团队权限，新员工入职只需开通一次
- 员工离职时一键禁用，无需逐个系统处理
- 所有操作都有记录，方便审计追溯
- 避免账号混用，保护企业数据安全
对于接入 AI API 的场景来说，SSO 认证还能帮助企业更好地管理 API 调用配额。我合作的很多企业客户反映，他们通过 HolySheheep AI 的企业版实现了 API 费用透明化，每个部门的 AI 消耗都能清晰统计，而结合 Dify 的 SSO 后，这个管理变得更加顺畅。现在注册还能享受首月赠额度，可以先体验再决定是否长期使用。
二、准备工作：你需要准备哪些东西
在开始配置之前，我们需要准备一些基础材料。不用担心，我会用最通俗的话解释每一步。
2.1 必备工具清单
- Dify 部署环境：可以是本地部署的 Docker 版本，也可以是云服务版本
- 企业身份提供商：常见的有飞书、钉钉、企业微信，或者通用的 SAML/OIDC 提供商
- 管理员账号：Dify 和你的身份提供商都需要有管理员权限
- API 密钥：用于连接 AI 服务，这里推荐使用 HolySheheep AI，国内直连延迟低于 50ms，而且汇率是 ¥1=$1，相比官方汇率能节省超过 85% 的成本
关于 API 密钥的获取，大家可以访问 立即注册 HolySheheep AI，注册后进入控制台就能看到自己的密钥了。HolySheheep 支持微信和支付宝充值，对于国内开发者来说非常方便。
2.2 了解支持的 SSO 协议
Dify 支持多种 SSO 协议，对于国内企业来说，最常用的是这三种：
- OIDC（OpenID Connect）：最推荐的方案，配置简单，安全性高
- SAML 2.0：传统企业常用的协议，兼容性好
- LDAP：适合有本地目录服务的大型企业
我个人的经验是，如果你们的公司已经在用飞书或钉钉，直接选择对应的 OIDC 方案最省事，配置步骤最少，出问题的概率也最低。
三、手把手配置飞书 SSO 认证
接下来我用飞书作为例子，详细演示如何配置 SSO。这个流程我最熟悉，帮助十几家企业都成功配置过。
3.1 在飞书开放平台创建应用
第一步，登录飞书开放平台（open.feishu.cn），点击“创建企业自建应用”。
（截图提示：飞书开放平台首页，点击右上角“创建应用”按钮）
填写应用名称，比如“Dify 企业登录”，上传一个图标，然后点击创建。创建完成后，你会进入应用详情页面。
在左侧菜单找到“凭证与基础信息”，这里有两样东西我们要记住：
- App ID：类似这样的一串字符
cli_xxxxxxxxxxxxx - App Secret：点击查看按钮获取，这个要保密不要泄露
（截图提示：应用凭证页面，App ID 和 App Secret 的位置高亮显示）
3.2 配置 OIDC 回调地址
回到 Dify 管理后台，进入“设置” → “身份验证”页面。
找到 SSO 认证配置区域，选择“添加 SSO provider”，然后选择 OIDC 协议。
这里会要求你填写回调地址（Redirect URI），格式通常是：
https://你的Dify域名/sso/connections/organization/1/provider/oidc/callback把这个地址复制下来，回到飞书开放平台，在应用详情页点击“添加应用能力”，选择“网页”。在网页配置中，找到重定向 URL 设置，把刚才复制的地址填进去。
（截图提示：飞书应用配置页面的重定向 URL 设置位置）
3.3 获取 OIDC 必要参数
回到飞书开放平台，在应用详情页的左侧菜单，找到“添加应用能力”，选择“OIDC”。
（截图提示：飞书 OIDC 配置页面）
在 OIDC 配置页面，你需要填写：
- 重定向 URL：就是上一步你在 Dify 填的那个地址
- 退出重定向 URL：可以填 Dify 的首页地址
保存配置后，飞书会给你一个“配置地址”和“令牌地址”。把这些地址记下来，下一步要用。
3.4 在 Dify 配置 SSO
回到 Dify 的 SSO 配置页面，你会看到一个表单，需要填写以下信息：
Provider Name（提供商名称）: 飞书 SSO
Provider Type（提供商类型）: OIDC
Client ID: cli_xxxxxxxxxxxxx （飞书给你的 App ID）
Client Secret: xxxxxxxxxxxxxx （飞书给你的 App Secret）
Authorization URL: https://open.feishu.cn/open-apis/authen/v1/authorize （飞书的授权地址）
Token URL: https://open.feishu.cn/open-apis/authen/v1/oauth/token （飞书的令牌地址）
User Info URL: https://open.feishu.cn/open-apis/authen/v1/user_info （获取用户信息的地址）
Scopes: user_id,email,avatar_url （需要的权限范围）填写完毕后，点击“保存并测试”。Dify 会尝试连接飞书进行验证。如果一切顺利，你会看到测试成功的提示。
（截图提示：Dify SSO 配置页面，填写完成后的界面）
四、Dify SSO 配置代码示例
对于喜欢用代码操作的开发者，这里我提供一个通过 API 配置 SSO 的方式。假设你已经通过 HolySheheep AI 接入了 Dify 的管理接口。
4.1 使用 Python SDK 配置 SSO
下面是一个完整的 Python 示例，演示如何通过编程方式配置 Dify 的 SSO 认证：
import requests
import json
Dify API 配置 - 使用 HolySheheep AI 作为网关
DIFY_API_BASE = "https://api.holysheep.ai/v1/dify"
API_KEY = "YOUR_HOLYSHEEP_API_KEY" # 从 HolySheheep 控制台获取
def configure_sso():
"""配置 Dify SSO 认证"""
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# SSO 提供商配置数据
sso_config = {
"provider_type": "oidc",
"provider_name": "飞书企业认证",
"client_id": "cli_xxxxxxxxxxxxx",
"client_secret": "xxxxxxxxxxxxxxxxxxxx",
"authorization_url": "https://open.feishu.cn/open-apis/authen/v1/authorize",
"token_url": "https://open.feishu.cn/open-apis/authen/v1/oauth/token",
"user_info_url": "https://open.feishu.cn/open-apis/authen/v1/user_info",
"scopes": ["user_id", "email", "avatar_url"],
"auto_provision": True, # 自动创建用户
"sync_user_roles": True # 同步用户角色
}
# 调用 Dify API 配置 SSO
response = requests.post(
f"{DIFY_API_BASE}/admin/sso/configure",
headers=headers,
json=sso_config
)
if response.status_code == 200:
result = response.json()
print(f"SSO 配置成功！Provider ID: {result['provider_id']}")
return result
else:
print(f"配置失败: {response.text}")
return None
执行配置
configure_sso()4.2 验证 SSO 连接状态
配置完成后，你可能需要检查 SSO 是否正常工作。下面的代码可以帮助你测试连接：
import requests
DIFY_API_BASE = "https://api.holysheep.ai/v1/dify"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
def test_sso_connection(provider_id):
"""测试 SSO 连接状态"""
headers = {
"Authorization": f"Bearer {API_KEY}"
}
# 测试 SSO 提供商的连通性
test_url = f"{DIFY_API_BASE}/admin/sso/{provider_id}/test"
response = requests.get(test_url, headers=headers)
if response.status_code == 200:
data = response.json()
print("SSO 连接状态检查：")
print(f" - OAuth 端点: {'✓ 正常' if data['oauth_reachable'] else '✗ 失败'}")
print(f" - Token 交换: {'✓ 正常' if data['token_exchange'] else '✗ 失败'}")
print(f" - 用户信息获取: {'✓ 正常' if data['user_info_fetch'] else '✗ 失败'}")
print(f" - 延迟: {data['latency_ms']}ms")
return data
else:
print(f"测试失败: {response.text}")
return None
假设 provider_id 是上一步返回的 ID
test_sso_connection("sso_abc123def456")我在实际部署中发现，使用 HolySheheep AI 的网关访问 Dify API，延迟能控制在 50 毫秒以内，比直接访问海外节点快很多。这对于需要频繁调用管理接口的场景特别有用，比如批量同步用户信息。
五、常见报错排查
在配置 SSO 的过程中，新手最容易遇到一些问题。我根据自己踩过的坑，总结了最常见的三个报错及解决方案。
5.1 错误一：回调地址不匹配
报错信息：redirect_uri_mismatch 或 Callback URL mismatch
原因分析：在身份提供商填写的回调地址和 Dify 实际请求的地址不一致。这是最常见的问题，通常是因为复制粘贴时漏了某个路径部分。
解决步骤：
- 登录 Dify 管理后台，进入 SSO 配置页面
- 找到“回调地址”字段，完整复制显示的地址
- 回到飞书/钉钉等平台，找到重定向 URL 设置
- 删除旧的 URL，粘贴新的完整地址
- 保存并重新测试
# 正确的回调地址格式应该是：
https://your-dify-domain.com/sso/connections/organization/1/provider/oidc/callback
注意检查：
1. 协议是 https 还是 http
2. 域名是否完全一致
3. 路径最后是否有 /callback
5.2 错误二：客户端密钥错误
报错信息：invalid_client 或 client_secret is invalid
原因分析：填写的 App Secret 与飞书/钉钉后台的不一致。可能是复制时出错，或者使用了旧版本的密钥。
解决步骤：
- 登录飞书开放平台，进入应用详情页
- 点击“凭证与基础信息”
- 找到 App Secret，点击“查看”（可能需要二次验证）
- 使用复制按钮复制完整的 Secret，不要手动选择
- 回到 Dify，重新粘贴并保存
# 常见坑点：
1. Secret 包含不可见字符，手动复制会漏掉
2. 测试环境和生产环境的 Secret 不同
3. App Secret 被重置过但 Dify 还是用的旧的
#
解决方案：使用下面代码验证 Secret 是否正确
import hashlib
def verify_secret(app_id, app_secret):
# 验证飞书 App Secret 格式是否正确
if len(app_secret) == 32:
print("Secret 格式正确（32位）")
elif len(app_secret) == 64:
print("Secret 格式正确（64位）")
else:
print(f"⚠️ Secret 长度异常: {len(app_secret)} 位")
verify_secret("cli_abc123", "xxxxxxxxxxxxxxxxxxxx")5.3 错误三：用户权限不足
报错信息：permission_denied 或 insufficient_scope
原因分析：在申请用户信息权限时，范围（scope）不够，或者企业管理员没有审批该权限。
解决步骤：
- 登录飞书开放平台，进入应用配置
- 找到权限管理，添加以下必要权限：
# 飞书 OIDC 需要的基础权限 - 获取用户 user_id - 获取用户邮箱 - 获取用户头像 - 提交权限申请（如果是自建应用通常不需要审核）
- 回到应用版本管理，发布新版本
- 让企业管理员在飞书管理后台审批应用权限
我之前帮一家企业配置时，他们的技术负责人已经填好了所有配置，但就是因为没有发布新版本，导致员工登录时一直报错。所以记得每次修改配置后都要重新发布应用版本。
5.4 错误四：Token 过期或无效
报错信息：token_expired 或 invalid_token
原因分析：OIDC 的 access_token 有时效性，通常是 7200 秒（2小时）。如果用户长时间不操作，再次访问时 token 可能已经过期。
解决步骤：
# 检查 Dify SSO 配置中的 Token 刷新设置
确保开启了自动刷新机制
sso_config = {
"provider_type": "oidc",
# ... 其他配置 ...
"token_refresh": True, # 确保开启自动刷新
"token_cache_ttl": 3600 # Token 缓存时间（秒）
}
如果问题仍然存在，检查 Dify 日志
位置通常在 /opt/dify/log 下
查看最新的 api.log 文件
import subprocess
def check_dify_logs():
"""检查 Dify 日志中的 SSO 相关错误"""
result = subprocess.run(
["tail", "-100", "/opt/dify/log/api.log"],
capture_output=True,
text=True
)
# 筛选 SSO 相关的日志
sso_logs = [line for line in result.stdout.split('\n')
if 'sso' in line.lower() or 'oauth' in line.lower()]
print("最近的 SSO 日志：")
for log in sso_logs[-20:]:
print(log)六、实战经验：我是如何为企业配置 SSO 的
去年帮一家教育科技公司部署 Dify 时，他们有 200 多名员工需要使用 AI 应用。最开始没有配置 SSO，每个员工都用自己的个人账号，结果出现了很多问题：
- 账号管理混乱，不知道谁在用什么应用
- API 调用费用无法分摊到部门
- 员工离职后账号没有及时禁用，数据泄露风险大
后来我帮他们接入了企业微信 SSO，整个配置过程不到两个小时。配置完成后，所有员工都能用企业微信扫码登录 Dify，而且我通过 HolySheheep AI 的费用统计功能，为每个部门设置了 API 调用配额。
这里要提一下 HolySheheep AI 的一个优势：它的汇率是 ¥1=$1，而官方汇率是 ¥7.3=$1，这意味着企业的 AI 成本直接节省了 85% 以上。按这家公司每月 5 万美元的 API 调用量来算，每月能节省超过 30 万元人民币。
配置完成后，我还写了一个自动化脚本，用于同步企业微信的部门结构和用户状态：
import requests
import time
HolySheheep AI 作为统一网关
HOLYSHEEP_BASE = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
def sync_enterprise_users():
"""同步企业微信用户到 Dify"""
# 获取所有企业微信部门
departments = requests.get(
"https://qyapi.weixin.qq.com/cgi-bin/department/list",
params={"access_token": "YOUR_WX_ACCESS_TOKEN"}
).json()
# 获取所有用户
users = requests.get(
"https://qyapi.weixin.qq.com/cgi-bin/user/simplelist",
params={
"access_token": "YOUR_WX_ACCESS_TOKEN",
"department_id": 1,
"fetch_child": 1
}
).json()
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
synced_count = 0
for user in users.get("userlist", []):
# 为每个企业微信用户创建 Dify 账号
payload = {
"email": user["mobile"] + "@company.com",
"name": user["name"],
"department": user["department"][0] if user["department"] else 1,
"status": "active",
"external_id": user["userid"] # 绑定企业微信 ID
}
response = requests.post(
f"{HOLYSHEEP_BASE}/dify/users/sync",
headers=headers,
json=payload
)
if response.status_code == 200:
synced_count += 1
# 避免请求过快
time.sleep(0.1)
print(f"成功同步 {synced_count}/{len(users.get('userlist', []))} 名用户")
return synced_count
sync_enterprise_users()这个脚本每天会自动运行一次，确保 Dify 中的用户状态和企业微信保持同步。员工入职、调岗、离职，都能自动处理。
七、配置完成后的验证与优化
SSO 配置完成后，建议做一次完整的验证测试，确保各个方面都正常工作。
7.1 必测场景清单
- 新用户首次登录：从未注册过的企业用户尝试登录
- 老用户切换认证方式：原本用邮箱注册的用户切换到 SSO
- 权限验证：不同角色的用户能看到不同的功能
- 会话保持：关闭浏览器后重新打开，是否需要重新登录
- 退出登录：点击退出后，是否正确跳转到登录页
7.2 性能监控建议
建议开启 Dify 的 SSO 相关日志监控，及时发现异常：
# 在 Dify 环境中设置日志监控
修改 docker-compose.yml 中的 logging 配置
services:
api:
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
environment:
- LOG_LEVEL=INFO
- SSO_DEBUG=true # 开启 SSO 调试日志
查看 SSO 日志的命令
docker logs dify-api --since 10m | grep -i sso八、总结与后续学习
通过这篇文章，我们从零开始学习了 Dify SSO 认证的配置方法。主要内容包括：
- 理解了 SSO 的概念和企业级应用价值
- 掌握了飞书 OIDC SSO 的完整配置流程
- 学会了用代码方式配置和管理 SSO
- 了解了常见报错的排查方法和解决方案
对于想要进一步提升的读者，我建议：
- 尝试配置钉钉或企业微信的 SSO，感受不同平台的差异
- 学习 SAML 协议，为接入更多企业系统做准备
- 研究 Dify 的权限管理机制，结合 SSO 实现更精细的访问控制
在 AI API 接入方面，如果你在寻找稳定、低成本、大厂模型覆盖全面的供应商，HolySheheep AI 是一个值得考虑的选择。它的优势不仅在于价格——GPT-4.1 每百万 token 输出仅 $8，Claude Sonnet 4.5 是 $15，Gemini 2.5 Flash 只要 $2.50，DeepSeek V3.2 更是低至 $0.42——还在于国内直连的稳定性和便捷的充值方式。
如果你在配置过程中遇到任何问题，欢迎在评论区留言，我会尽力解答。觉得这篇文章有帮助的话，也请分享给身边需要的朋友！