单点登录 (SSO)
Coolify 支持通过 OpenID Connect (OIDC) 实现单点登录。SSO 功能在 Coolify 4.2 及更高版本中可用。
已测试的提供商
本指南目前包含 Okta，因为它是经过测试的 SSO 提供商。其他 OIDC 提供商可能也能正常工作，但此处暂未涵盖。
SSO 在 Coolify 中的工作原理
Coolify 作为 OIDC 客户端运行。您的身份提供商对用户进行身份验证后，会将浏览器重定向回 Coolify 并附带一个授权码。Coolify 将该代码交换为令牌，并根据您的设置使用返回的电子邮件地址登录用户或创建用户。
在 Coolify 中配置 SSO 的路径为：
https://<your-coolify-domain>/settings/oauth对于 OpenID Connect，请使用以下回调 URL 格式：
https://<your-coolify-domain>/auth/oidc/callback例如：
https://coolify.example.com/auth/oidc/callbackOkta 示例
在为 Coolify 创建 Okta OIDC 应用程序时，请使用此示例。
1. 创建 Okta 应用程序
在 Okta 管理控制台中：
- 转到 Applications（应用程序）。
- 点击 Create App Integration（创建应用集成）。
- 选择 OIDC - OpenID Connect 作为登录方式。
- 选择 Web Application（Web 应用程序） 作为应用程序类型。
- 将应用程序名称设置为
Coolify。 - 将您的 Coolify 回调 URL 添加到 Sign-in redirect URIs（登录重定向 URI） 中：
https://coolify.example.com/auth/oidc/callback- 将应用程序分配给应访问 Coolify 的用户或组。
- 保存应用程序。
- 复制 Client ID（客户端 ID） 和 Client Secret（客户端密钥）。
重定向 URI 必须匹配
Okta 中配置的重定向 URI 必须与 Coolify 发送的重定向 URI 完全一致。如果您的 Coolify 域名发生变化，请同时更新 Okta 和 Coolify 中的配置。
2. 配置 Coolify
在 Coolify 中进入 Settings（设置）→ Authentication（身份验证），然后配置 OpenID Connect 提供商。
| Coolify 字段 | 示例值 |
|---|---|
| Enabled（启用） | On（开启） |
| Client ID（客户端 ID） | 来自 Okta 的 Client ID |
| Client Secret（客户端密钥） | 来自 Okta 的 Client Secret |
| Redirect URI（重定向 URI） | https://coolify.example.com/auth/oidc/callback |
| Issuer URL（发行者 URL） | https://example.okta.com |
| Login Button Label（登录按钮标签） | Login with Okta |
| Scopes（作用域） | openid email profile groups |
| Clock Skew (seconds)（时钟偏差（秒）） | 60 |
| Allow OIDC user creation（允许 OIDC 用户创建） | 仅在 Okta 用户可自动创建 Coolify 账户时启用 |
| Require verified email（要求验证电子邮件） | 推荐：启用 |
| Use PKCE（使用 PKCE） | 推荐：启用 |
请将 example.okta.com 和 coolify.example.com 替换为您实际的 Okta 和 Coolify 域名。
发行者 URL (Issuer URL)
对于大多数 Okta 设置，发行者 URL 即为您的 Okta 域名：
https://example.okta.com如果您使用的是自定义 Okta 授权服务器，请使用该发行者 URL：
https://example.okta.com/oauth2/<authorization-server-id>Coolify 会使用此发行者 URL 来发现 OIDC 的授权、令牌、用户信息和 JWKS 端点。
作用域 (Scopes)
Okta 请使用以下作用域：
openid email profile groups必须包含 openid 作用域。必须包含 email 作用域，以便 Coolify 能够通过电子邮件识别用户。profile 作用域提供用户个人资料字段。groups 作用域是可选的，但如果您的 Okta 授权服务器配置为包含组声明，则非常有用。
注册行为
Coolify 可以通过 OIDC 登录现有用户。新用户创建取决于您的注册设置。
- 如果通过 Okta 认证的用户应自动在 Coolify 中创建，请启用 Allow OIDC user creation（允许 OIDC 用户创建）。
- 如果您希望管理员在用户使用 Okta 登录之前手动创建 Coolify 账户，请禁用该选项。
- 如果您希望用户仅通过已配置的 SSO 提供商进行注册，请启用 Disable password registration when OAuth is enabled（启用 OAuth 时禁用密码注册）。
故障排除
Okta 提示重定向 URI 无效
请检查 Okta 的 Sign-in redirect URI（登录重定向 URI） 是否与 Coolify 的 Redirect URI（重定向 URI） 完全一致：
https://coolify.example.com/auth/oidc/callback常见的不匹配情况包括：http 与 https 混用、域名不同、末尾多出了斜杠，或者错误地使用了 /auth/okta/callback 而非 /auth/oidc/callback。
Coolify 提示提供商配置不完整
请确保 OpenID Connect 提供商已填写以下字段：
- Client ID（客户端 ID）
- Client Secret（客户端密钥）
- Issuer URL（发行者 URL）
- Redirect URI（重定向 URI）
- Scopes（作用域）中包含
openid
登录失败，因为未返回电子邮件地址
请确保 Coolify 的作用域中包含 email，并且您的 Okta 应用程序或授权服务器会返回用户的电子邮件声明。
登录失败，因为电子邮件未经验证
如果启用了 Require verified email（要求验证电子邮件），Okta 必须返回 email_verified: true。您可以在 Okta 中验证用户的电子邮件，或者在 Coolify 中禁用 Require verified email（要求验证电子邮件）。
Okta 登录成功后 Coolify 登录失败
请首先检查以下值：
- Okta 发行者 URL 是否正确。
- 用户是否已分配到该 Okta 应用程序。
- Coolify 服务器时间是否准确。
- Clock Skew (seconds)（时钟偏差（秒）） 是否至少为
60。 - Okta 中配置的 Coolify URL 是否使用了用户实际访问的公开 URL。