> ## 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），支持 SAML 2.0 和 OIDC 两种协议。

<Info>
  适用版本：Teams, Enterprise
</Info>

## 概述

单点登录（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 化集成方式 |

<Note>
  每个组织同一时间只能启用一种 SSO 协议。如需切换协议，请先停用当前协议再创建新协议的配置。
</Note>

## **前提条件**

在配置 SSO 之前，请确保你已具备以下条件：

* **管理员权限：** 你在组织内拥有管理员权限。
* **身份提供商权限：** 你拥有在组织的 IDP 中创建和配置应用的权限。
* **DNS 访问权限**：你拥有在组织的邮箱域名添加 TXT 记录以进行验证的权限。

<img src="https://mintcdn.com/qoder/nVTofMdrAHbRY3l4/images/saml.jpg?fit=max&auto=format&n=nVTofMdrAHbRY3l4&q=85&s=30b1a43e9dc4d18a85e908899c6a6853" alt="image" width="2514" height="1120" data-path="images/saml.jpg" />

## 配置流程

无论选择 SAML 还是 OIDC，SSO 配置过程都包括以下步骤：

<img src="https://mintcdn.com/qoder/nVTofMdrAHbRY3l4/images/SAML-configuration-process.png?fit=max&auto=format&n=nVTofMdrAHbRY3l4&q=85&s=34c22d8c9c81ad3c07646d4f4a93adda" alt="image" width="613" height="372" data-path="images/SAML-configuration-process.png" />

### 步骤 1：验证邮箱域名

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

配置说明参见[域名验证](https://docs.qoder.com/zh/account/teams/domains)。

### 步骤 2：创建 SSO 配置

1. 管理员前往 **组织设置 > 安全与身份**。
2. 根据你的 IDP 选择 **SAML 设置** 或 **OIDC 设置**。

<Tabs>
  <Tab title="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}` |

    <img src="https://mintcdn.com/qoder/nVTofMdrAHbRY3l4/images/saml-1.jpg?fit=max&auto=format&n=nVTofMdrAHbRY3l4&q=85&s=a749023b715128c1fc58385fbcd590d6" alt="image" width="2518" height="1114" data-path="images/saml-1.jpg" />
  </Tab>

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

    **生成的 SP 信息示例：**

    | **字段**               | **示例值**                                        |
    | -------------------- | ---------------------------------------------- |
    | Redirect URI (回调地址)  | `https://qoder.com/sso/callback/oidc/{org_id}` |
    | 登录入口 URL (Login URL) | `https://qoder.com/sso/login/oidc/{org_id}`    |

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

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

<Tabs>
  <Tab title="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. 点击 **保存**。

           <img src="https://mintcdn.com/qoder/nVTofMdrAHbRY3l4/images/saml-2.jpg?fit=max&auto=format&n=nVTofMdrAHbRY3l4&q=85&s=350a38e01c79960e76877b676b454b52" alt="image" width="2448" height="998" data-path="images/saml-2.jpg" />
  </Tab>

  <Tab title="OIDC">
    #### **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 签名）
    * 支持的签名算法
  </Tab>
</Tabs>

### 步骤 4：配置属性映射

SSO 可以自动创建和映射用户，因此需要配置如何将来自身份提供商 (IDP) 的用户属性映射到系统字段。

<Tabs>
  <Tab title="SAML">
    1. 在 **SAML 配置**页面，滚动到 **属性映射** (Attribute Mapping) 部分。
    2. 配置属性映射：
       * **邮箱属性 (Email Attribute)：** IDP 中用于邮箱字段的属性名称，如 `user.email`。（必填）
       * **名称属性 (Name Attribute)：** IDP 中用于显示用户名称的属性名称，如 `user.name`。
    3. 点击 **保存**。
  </Tab>

  <Tab title="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. 点击 **保存**。

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

### 步骤 5：测试配置

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

1. 在 **SSO 配置**页面，点击 **测试配置** (Test SSO) 按钮。
2. 系统将运行一系列验证检查（证书/签名、元数据端点、Discovery 文档、属性映射等）。
3. 查看测试结果。

<img src="https://mintcdn.com/qoder/nVTofMdrAHbRY3l4/images/saml-3.jpg?fit=max&auto=format&n=nVTofMdrAHbRY3l4&q=85&s=b415acca76d9b1a4839720c20f25ec7f" alt="image" width="1934" height="330" data-path="images/saml-3.jpg" />

### 步骤 6：激活 SSO

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

1. 在 **SSO 配置**页面，确保所有测试检查均已通过。
2. 点击 **启用 SSO** 开关。
3. 在弹出的对话框中确认信息后激活。

**激活后：**

* SSO 的状态将变为**已激活**。
* 组织成员现可使用 SAML 或 OIDC SSO 登录。
* 符合已验证邮箱域名的用户，在登录页输入邮箱后将被自动导向组织的 SSO 登录。

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