Documentation Index
Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
Use this file to discover all available pages before exploring further.
概述
单点登录（SSO）允许组织成员使用企业身份提供商（Identity Provider，IDP）进行认证，无需在 Qoder 管理独立的登录凭证。Qoder 支持两种主流的 SSO 协议：- SAML 2.0：基于 XML 的成熟企业级认证标准，广泛应用于 Okta、Microsoft Entra ID（Azure AD）、OneLogin、阿里云 IDaaS 等 IDP。
- OIDC（OpenID Connect）：构建于 OAuth 2.0 之上的现代身份协议，支持通过 Discovery URL 一键自动发现配置，典型提供商包括 Okta、Azure AD、Google Workspace、Auth0、Authing、阿里云 RAM 等。
SSO 的优势
- 增强安全性： 通过你的企业身份提供商进行集中式认证。
- 改善用户体验： 一套凭证即可访问企业的所有应用程序。
- 简化用户管理： 已验证域名下的用户首次登录时自动创建账号并加入组织。
如何选择协议？
| 协议 | 适用场景 |
|---|---|
| SAML | IDP 仅提供 SAML 协议；需要 IdP 发起登录（IdP-initiated SSO）；已有基于 SAML 的企业认证体系 |
| OIDC | IDP 提供 OIDC / OAuth 2.0；希望通过 Discovery URL 自动发现端点；需要更轻量的 JSON 化集成方式 |
每个组织同一时间只能启用一种 SSO 协议。如需切换协议，请先停用当前协议再创建新协议的配置。
前提条件
在配置 SSO 之前，请确保你已具备以下条件：- 管理员权限： 你在组织内拥有管理员权限。
- 身份提供商权限： 你拥有在组织的 IDP 中创建和配置应用的权限。
- DNS 访问权限：你拥有在组织的邮箱域名添加 TXT 记录以进行验证的权限。
配置流程
无论选择 SAML 还是 OIDC，SSO 配置过程都包括以下步骤：
步骤 1：验证邮箱域名
在配置 SSO 之前，你需要先验证公司邮箱域名的所有权，以确保只有使用已验证公司邮箱域名的用户，才能通过组织的 SSO 登录。 配置说明参见域名验证。步骤 2：创建 SSO 配置
- 管理员前往 组织设置 > 安全与身份。
- 根据你的 IDP 选择 SAML 设置 或 OIDC 设置。
- SAML
- OIDC
为你的组织创建 SAML 配置。系统将自动生成 SP 的证书和密钥。初始化后，Qoder 将自动生成以下信息供你查看，你在后续配置身份提供商（IDP）时将需要使用：
- SP 实体 ID (SP Entity ID)
- SP 元数据 URL (SP Metadata URL)
- SP ACS (断言消费者服务) URL
- SP 证书和私钥
| 字段 | 示例值 |
|---|---|
| SP 实体 ID | https://qoder.com/saml/metadata/{org_id} |
| SP 元数据 URL | https://qoder.com/saml/metadata/{org_id} |
| SP ACS URL | https://qoder.com/sso/callback/saml/{org_id} |
步骤 3：配置身份提供商（IDP）
- SAML
- OIDC
你可以使用以下两种方法来配置 SAML IDP：
方法 A：自动配置 (推荐)
如果你的 IDP 提供元数据 URL，请使用此方法进行自动配置：- 在 SAML 配置页面，找到 IDP 元数据配置 (Identity Provider Metadata Configuration) 部分。
- 选择 元数据 URL (Import from URL) 配置模式。
- 输入你的 IDP 元数据 URL (例如，
https://your-idp.example.com/app/metadata)。 - 点击 保存。
- IDP 实体 ID
- SSO URL
- 签名证书
方法 B：手动配置
如果你的 IDP 不提供元数据 URL，请按以下步骤手动配置设置：- 在 SAML 配置页面，选择 手动配置 (Manual Configuration) 模式。
-
填写以下字段：
- IDP 实体 ID (IDP Entity ID)： 身份提供商的实体标识符。
- IDP SSO URL： SSO 登录端点 URL。
- IDP 公钥证书 (IDP Public Certificate)： PEM 格式的签名证书（可选，但推荐）。
-
点击 保存。
步骤 4：配置属性映射
SSO 可以自动创建和映射用户，因此需要配置如何将来自身份提供商 (IDP) 的用户属性映射到系统字段。- SAML
- OIDC
- 在 SAML 配置页面，滚动到 属性映射 (Attribute Mapping) 部分。
- 配置属性映射：
- 邮箱属性 (Email Attribute)： IDP 中用于邮箱字段的属性名称，如
user.email。（必填） - 名称属性 (Name Attribute)： IDP 中用于显示用户名称的属性名称，如
user.name。
- 邮箱属性 (Email Attribute)： IDP 中用于邮箱字段的属性名称，如
- 点击 保存。
步骤 5：测试配置
在激活前，请先测试 SSO 配置，以确保所有设置均已正确无误：- 在 SSO 配置页面，点击 测试配置 (Test SSO) 按钮。
- 系统将运行一系列验证检查（证书/签名、元数据端点、Discovery 文档、属性映射等）。
- 查看测试结果。
步骤 6：激活 SSO
测试通过后，即可激活 SSO：- 在 SSO 配置页面，确保所有测试检查均已通过。
- 点击 启用 SSO 开关。
- 在弹出的对话框中确认信息后激活。
- SSO 的状态将变为已激活。
- 组织成员现可使用 SAML 或 OIDC SSO 登录。
- 符合已验证邮箱域名的用户，在登录页输入邮箱后将被自动导向组织的 SSO 登录。
建议激活 SSO 后，当前管理员不要立即登出，另使用一个符合域名的用户尝试 SSO 登录进行验证，确保如 SSO 配置异常管理员有权限可以修改调整。