跳转到主要内容
登录通过浏览器完成，使用公司的单点登录，difyctl 全程接触不到你的企业密码。
外部 SSO 面向 没有 Dify 账户的用户。如果你的邮箱已对应某个 Dify 账户，此登录会被拒绝，请改为以 账户用户 身份登录。

​
登录

1

运行登录命令

difyctl auth login --host https://dify.example.com
使用管理员提供给你的主机 URL。不带协议的主机默认按 https:// 处理。
若不想自动打开浏览器，可传入 --no-browser。
2

用企业身份登录

difyctl 会打印一次性验证码和一个验证 URL，在默认浏览器中打开该 URL，然后等待：
! Copy this one-time code: WDJP-XKLM
  Open: https://dify.example.com/device
浏览器会引导你完成公司惯常的登录流程（与你登录其他企业工具时相同），然后要求输入一次性验证码。如果没有浏览器打开（通过 SSH 或在无图形界面的会话中属正常现象），从终端复制 URL，在任意设备上打开。验证码 15 分钟后过期。
3

确认会话

回到终端：
✓ Logged in to dify.example.com as <your-email> (external SSO, issuer: <your-identity-provider>)
external SSO 表示你是通过公司的身份提供商登录的，而非 Dify 账户。issuer 即为该提供商，由它为你做身份背书。

​
重新登录

如果某条命令以 auth_expired（退出码 4）失败，说明服务器已使你的会话过期或将其吊销。 重新运行 difyctl auth login。无需先登出，新的登录会替换已存储的 token。

​
Token 的存储位置

登录后会存储一个 OAuth bearer token，可通过 dfoe_ 前缀识别。它代表你在这台 Dify 主机上的企业身份，仅携带公司授予它的访问权限。该权限的具体范围，参见 权限范围与限制。 只要操作系统提供凭据存储，difyctl 就会把 token 存入其中：macOS 上是 Keychain，Windows 上是 Credential Manager，Linux 上是 Secret Service。如果没有可用的凭据存储，则回退到 difyctl 配置目录下一个权限为 0600 的 tokens.yml 文件，与 hosts.yml 中的会话元数据并列存放。 配置目录在 macOS 和 Linux 上是 ~/.config/difyctl，在 Windows 上是 %APPDATA%\difyctl。设置 DIFY_CONFIG_DIR 可覆盖此路径。

​
查看当前登录身份

difyctl auth whoami

<your-email> (external SSO, issuer: <your-identity-provider>)
要在脚本中读取身份信息，加上 --json： 
difyctl auth whoami --json

{"subject_type":"external_sso","email":"<your-email>","issuer":"<your-identity-provider>"}

​
登出

difyctl auth logout

✓ Logged out of dify.example.com
这会从你的机器上删除 token 和会话记录。但它不会结束服务器上的会话：该会话会一直保持活跃，直到其自行过期。 无需为重新认证而登出：对同一主机重新运行 difyctl auth login 会替换该会话。

​
故障排查

问题处理方法
浏览器始终未打开从终端复制 URL，在任意设备上打开。通过 SSH 或在无图形界面的会话中属正常现象。
验证码已过期验证码有效期为 15 分钟。重新运行 difyctl auth login 获取一个新的。
登录被拒绝（access_denied）授权在浏览器步骤中被拒。请与管理员确认你的账户已启用 Dify。
浏览器提示你的邮箱属于某个 Dify 账户外部 SSO 仅面向没有 Dify 账户的用户。请改为以 账户用户 身份登录。
主机被拒绝只接受 https:// 主机；不带协议的主机默认按 https:// 处理。
后续某条命令以 auth_expired 失败服务器已使你的会话过期或将其吊销。重新登录。
其余问题详见 故障排查。