AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

单点验证

更新时间：
复制为 MD 格式
产品详情
我的收藏

本文介绍 QoderWork CN 和 Qoder CN CLI 企业标准版，如何为组织配置单点登录（SSO），支持 SAML 2.0 和 OIDC 两种协议。

概述

单点登录（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 配置过程都包括以下步骤：image

步骤 1：验证邮箱域名

在配置 SSO 之前，你需要先验证公司邮箱域名的所有权，以确保只有使用已验证公司邮箱域名的用户，才能通过组织的 SSO 登录。配置说明参见域名验证。

步骤 2：创建 SSO 配置

  1. 管理员前往 组织设置 > 安全与身份。

  2. 根据你的 IDP 选择 SAML 设置 或 OIDC 设置。

SAML

为你的组织创建 SAML 配置。系统将自动生成 SP 的证书和密钥。初始化后，Qoder 将自动生成以下信息供你查看，你在后续配置身份提供商（IDP）时将需要使用：

  • SP 实体 ID (SP Entity ID)

  • SP 元数据 URL (SP Metadata URL)

  • SP ACS (断言消费者服务) URL

  • SP 证书和私钥

生成的 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}

OIDC

为你的组织创建 OIDC 配置。系统将自动生成回调地址（Redirect URI）和登录入口 URL，你在后续 IDP 侧注册 OAuth 2.0/OIDC 应用时将需要使用。生成的 SP 信息示例：

字段

示例值

Redirect URI (回调地址)

https://qoder.com.cn/sso/callback/oidc/{org_id}

登录入口 URL (Login URL)

https://qoder.com.cn/sso/login/oidc/{org_id}

请前往 IDP 控制台创建 OAuth 2.0 / OIDC 应用，将上述 Redirect URI 添加到应用允许的回调地址列表中。创建完成后，IDP 会颁发 Client ID 与 Client Secret，你将在步骤 3 中使用。

步骤 3：配置身份提供商（IDP）

SAML

你可以使用以下两种方法来配置 SAML IDP：

方法 A：自动配置 (推荐)

如果你的 IDP 提供元数据 URL，请使用此方法进行自动配置：

  1. 在 SAML 配置页面，找到 IDP 元数据配置 (Identity Provider Metadata Configuration) 部分。

  2. 选择 元数据 URL (Import from URL) 配置模式。

  3. 输入你的 IDP 元数据 URL (例如，https://your-idp.example.com/app/metadata)。

  4. 点击 保存。

系统将自动获取并解析以下信息：

  • IDP 实体 ID

  • SSO URL

  • 签名证书

方法 B：手动配置

如果你的 IDP 不提供元数据 URL，请按以下步骤手动配置设置：

  1. 在 SAML 配置页面，选择 手动配置 (Manual Configuration) 模式。

  2. 填写以下字段：

    • IDP 实体 ID (IDP Entity ID)： 身份提供商的实体标识符。

    • IDP SSO URL： SSO 登录端点 URL。

    • IDP 公钥证书 (IDP Public Certificate)： PEM 格式的签名证书（可选，但推荐）。

  3. 点击 保存。

OIDC

你可以使用以下两种方法来配置 OIDC IDP：

方法 A：Issuer URL 自动发现 (推荐)

如果你的 IDP 符合 OpenID Connect Discovery 规范（即暴露 /.well-known/openid-configuration 端点），请使用此方法：

  1. 在 OIDC 配置页面，选择 Issuer URL 自动发现 配置模式。

  2. 填写以下字段：

    • Issuer URL： IDP 的签发者地址（例如 https://login.company.com、https://oauth.aliyun.com、https://your-tenant.authing.cn/oidc）。

    • Client ID： IDP 中为 Qoder 应用颁发的客户端 ID。

    • Client Secret： IDP 中为 Qoder 应用颁发的客户端密钥。

    • Scopes（可选）：请求的权限范围，默认包含 openid，推荐使用 openid email profile。

  3. 点击 保存。

系统将自动从 {Issuer URL}/.well-known/openid-configuration 获取并解析：

  • Authorization Endpoint

  • Token Endpoint

  • UserInfo Endpoint

  • JWKS URL（用于验证 ID Token 签名）

  • 支持的签名算法

方法 B：手动配置

如果你的 IDP 不支持 Discovery，请手动填写：

  • Issuer URL、Client ID、Client Secret、Scopes

  • JWKS URL： JSON Web Key Set URL，用于验证 ID Token 签名。

  • End Session URL（可选）：登出时重定向到 IDP 的会话结束端点。

openid 是 OIDC 协议的必选 Scope，如果未填写系统会自动补齐。

步骤 4：配置身份提供商（IDP）

SAML

你可以使用以下两种方法来配置 SAML IDP：

方法 A：自动配置 (推荐)

如果你的 IDP 提供元数据 URL，请使用此方法进行自动配置：

  1. 在 SAML 配置页面，找到 IDP 元数据配置 (Identity Provider Metadata Configuration) 部分。

  2. 选择 元数据 URL (Import from URL) 配置模式。

  3. 输入你的 IDP 元数据 URL (例如，https://your-idp.example.com/app/metadata)。

  4. 点击 保存。

系统将自动获取并解析以下信息：

  • IDP 实体 ID

  • SSO URL

  • 签名证书

方法 B：手动配置

如果你的 IDP 不提供元数据 URL，请按以下步骤手动配置设置：

  1. 在 SAML 配置页面，选择 手动配置 (Manual Configuration) 模式。

  2. 填写以下字段：

    • IDP 实体 ID (IDP Entity ID)： 身份提供商的实体标识符。

    • IDP SSO URL： SSO 登录端点 URL。

    • IDP 公钥证书 (IDP Public Certificate)： PEM 格式的签名证书（可选，但推荐）。

  3. 点击 保存。

OIDC

  1. 在 OIDC 配置页面，滚动到 属性映射 (Attribute Mapping) 部分。

  2. 配置 OIDC UserInfo 中的 Claim 与系统字段的映射：

    • Email Claim： 用户邮箱对应的 Claim 名，通常为 email。（必填）

    • Name Claim： 用户显示名称对应的 Claim 名，通常为 name 或 nickname。

    • Open ID Claim： 用户唯一标识 Claim，通常为 sub，也可使用 email。

  3. 点击 保存。

Email 必填： 如果 IDP 返回的 UserInfo 中未包含有效 Email，认证将失败。请确保你在 IDP 侧已将 email Scope 授权给 Qoder 应用。

步骤 5：测试配置

在激活前，请先测试 SSO 配置，以确保所有设置均已正确无误：

  1. 在 SSO 配置页面，点击 测试配置 (Test SSO) 按钮。

  2. 系统将运行一系列验证检查（证书/签名、元数据端点、Discovery 文档、属性映射等）。

  3. 查看测试结果。

步骤 6：激活 SSO

测试通过后，即可激活 SSO：

  1. 在 SSO 配置页面，确保所有测试检查均已通过。

  2. 点击 启用 SSO 开关。

  3. 在弹出的对话框中确认信息后激活。

激活后：

  • SSO 的状态将变为已激活。

  • 组织成员现可使用 SAML 或 OIDC SSO 登录。

  • 符合已验证邮箱域名的用户，在登录页输入邮箱后将被自动导向组织的 SSO 登录。

建议激活 SSO 后，当前管理员不要立即登出，另使用一个符合域名的用户尝试 SSO 登录进行验证，确保如 SSO 配置异常管理员有权限可以修改调整。

上一篇：域名验证下一篇：动态与公告