> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO 接入指南

> 关于设置 SSO、了解 SCIM 相关注意事项，以及在 Devin Enterprise 中配置 IdP 组的完整指南。

本指南将引导企业管理员了解 Devin 中 SSO 的完整流程——从初始设置到 IdP 组配置——并说明在不使用 SCIM 的情况下，Devin 如何处理用户预配。

如需查看特定提供商的设置说明，请参阅 [Okta](/zh/enterprise/security-access/sso/okta)、[Microsoft Entra ID](/zh/enterprise/security-access/sso/azure)、[SAML](/zh/enterprise/security-access/sso/saml) 或 [Generic OIDC](/zh/enterprise/security-access/sso/oidc)。

***

<div id="1-setting-up-sso">
  ## 1. 配置 SSO (单点登录)
</div>

<div id="creating-your-sso-application">
  ### 创建你的 SSO 应用
</div>

在你的身份提供商 (Okta、Microsoft Entra ID 或任何兼容 SAML/OIDC 的 IdP) 中创建一个应用，并将以下凭据提供给你的 Cognition 团队：

| 连接类型                   | 协议                             | 需提供的内容                             |
| :--------------------- | :----------------------------- | :--------------------------------- |
| **Okta**               | OIDC (Okta Workforce Identity) | Okta 域名、客户端 ID、客户端密钥、作用域           |
| **Microsoft Entra ID** | OIDC (Microsoft Entra ID)      | Microsoft Entra ID 域名、客户端 ID、客户端密钥 |
| **SAML**               | SAML 2.0 (任何 IdP)              | 登录 URL、X.509 签名证书                  |
| **Generic OIDC**       | OIDC                           | Discovery URL、客户端 ID、客户端密钥、作用域     |

<Note>
  你还应提供一个或多个已验证的电子邮件域名，这样 Devin 就能知道应信任你的 IdP 提供的哪些电子邮件地址。
</Note>

<div id="what-happens-after-setup">
  ### 设置完成后会发生什么
</div>

一旦 Cognition 团队拿到凭据，他们就会配置 SSO 连接。设置完成后：

1. SSO 连接会关联到你的 Devin 企业
2. **登录时自动加入企业** 已启用——任何通过 SSO 进行身份验证的用户都会自动被添加到你的企业中
3. 你的电子邮件域名会被注册为受信任域——只接受来自这些域名的电子邮件地址
4. **基于组的角色分配 (RBAC)** 已启用——登录时传送的 IdP 组可以映射到 Devin 角色
5. 默认社交登录 (Google、GitHub) 会被禁用——SSO 将成为必需的身份验证方式

<div id="the-user-login-experience">
  ### 用户登录体验
</div>

1. 用户访问你的 Devin URL
2. 被重定向到已配置的 IdP (Okta、Microsoft Entra ID 等)
3. 用户按正常流程完成身份验证
4. IdP 将用户信息和所属组信息发回 Devin
5. Devin 会自动：
   * 如果这是用户首次登录，则为其创建账户 (即时预配)
   * 为其分配默认的 Enterprise 成员角色
   * 同步其 IdP 组成员关系——添加新组，移除不再适用的组
   * 在企业审计日志中记录此次登录

***

<div id="self-service-administration">
  ## 自助管理
</div>

以下功能可由企业管理员直接在 Devin Web 应用中使用。

<div id="idp-group-management">
  ### IdP 组管理
</div>

**设置 → 企业 → 身份提供商组**

* 查看所有通过用户登录同步的组
* 将组分配到企业级角色 (例如：“`Engineering-Admins`”中的所有人都会获得 Admin 角色)
* 将组分配到特定组织并授予特定角色 (例如：“`Team-Backend`”在 Backend 组织中拥有 Member 权限)
* 在多个组织中批量添加或移除组
* 查看每个组被分配到了多少个组织

<div id="member-management">
  ### 成员管理
</div>

**设置 → 企业 → 成员**

* 查看所有企业成员，包括其所属的 IdP 组
* 通过电子邮件邀请新成员
* 更新成员角色
* 移除成员

<div id="custom-roles">
  ### 自定义角色
</div>

**设置 → 企业版 → 角色**

* 创建具有细粒度权限的自定义角色
* 为单个用户或 IdP 组分配自定义角色

详情请参阅 [自定义角色与 RBAC](/zh/enterprise/security-access/custom-roles)。

<div id="api-for-automation">
  ### 自动化 API
</div>

Devin 提供了一个 V2 API，可用于自动化成员管理：

| 操作           | API 端点                                       |
| :----------- | :------------------------------------------- |
| 列出所有成员       | `GET /v2/enterprise/members`                 |
| 通过电子邮件批量邀请用户 | `POST /v2/enterprise/members/invite`         |
| 移除成员         | `DELETE /v2/enterprise/members/{user_id}`    |
| 批量更新成员角色     | `PATCH /v2/enterprise/members/roles`         |
| 在不同角色之间迁移成员  | `PATCH /v2/enterprise/members/migrate-roles` |
| 列出所有角色       | `GET /v2/enterprise/roles`                   |
| 列出所有 IdP 组   | `GET /v2/enterprise/groups`                  |
| 预先创建 IdP 组   | `PUT /v2/enterprise/groups`                  |
| 获取组的组织分配情况   | `GET /v2/enterprise/groups/{group_name}`     |

***

<div id="2-understanding-devin-without-scim">
  ## 2. 在不使用 SCIM 的情况下理解 Devin
</div>

Devin 目前尚不支持 SCIM 协议。所有用户和组管理都通过 SSO 登录事件以及 Devin UI/API 完成。以下将说明这在实际使用中的具体含义。

<div id="user-provisioning-login-triggered-only">
  ### 用户预配：仅在登录时触发
</div>

|            | 使用 SCIM                         | Devin (不使用 SCIM)                                        |
| :--------- | :------------------------------ | :------------------------------------------------------ |
| **如何创建用户** | 当用户被分配到应用时，IdP 会立即将创建用户的信息推送到应用 | 用户只有在首次通过 SSO 登录后，才会在 Devin 中创建；或者通过 UI 或 API 手动邀请后才会创建 |
| **何时发生**   | Admin 将应用分配给用户 → 用户会在几秒内出现      | Admin 将应用分配给用户 → 在用户登录之前，Devin 中不会有任何变化                 |
| **预先预配**   | 用户在首次访问应用之前，账户就已准备就绪            | 不会进行预先预配，除非 Admin 通过 Devin UI 或 API 明确邀请他们              |

为新员工办理入职时，Admin 可以选择提前邀请他们 (**设置 → 企业 → 成员 → 邀请**，或通过 API) ，也可以直接让他们在首次登录时自动完成预配。

<div id="user-deprovisioning-manual-only">
  ### 用户停用：仅限手动
</div>

|            | 使用 SCIM                 | Devin (不使用 SCIM)                            |
| :--------- | :---------------------- | :------------------------------------------ |
| **如何移除用户** | IdP 停用/移除用户 → 应用立即禁用该用户 | 在 IdP 中停用/移除用户，对 Devin 不会产生任何影响             |
| **离职处理**   | 离职员工会在几分钟内失去访问权限        | 离职员工会继续保留访问权限，直到管理员在 Devin 中手动将其移除，且其会话自然过期 |
| **合规性**    | 自动满足合规要求——不会出现孤儿账户      | 除非管理员同时维护两个系统，否则会有孤儿账户风险                    |

<Warning>
  这是最大的运维缺口。员工离职时，管理员必须另外在 Devin 中将其移除 (**设置 →  → 成员 → 移除**，或通过 API) 。活跃会话会一直有效，直到自然过期——IdP 不会触发即时会话撤销。
</Warning>

<div id="group-sync-login-time-only-not-real-time">
  ### 组同步：仅在登录时同步，而非实时同步
</div>

|                     | 使用 SCIM (组推送)            | Devin (不使用 SCIM)                        |
| :------------------ | :----------------------- | :-------------------------------------- |
| **同步时机**            | IdP 实时推送组成员变更            | 仅在用户登录时同步组信息                            |
| **添加到组**            | Admin 将用户加入组中 → 应用会立即反映  | Admin 将用户加入组中 → Devin 要等到用户下次登录时才会感知到   |
| **从组中移除**           | Admin 将用户从组中移除 → 应用会立即反映 | Admin 将用户从组中移除 → Devin 在下次登录前仍会显示旧的成员关系 |
| **Source of truth** | IdP 始终是权威数据源             | IdP 仅在登录时才是权威数据源——两次登录之间可能出现偏差          |

如果管理员更改了某人的 IdP 组 (例如将其从工程组移到销售组) ，Devin 在该用户再次登录前都不会反映这一变化。在此期间，用户仍会保留原有的基于组的角色和组织访问权限。

<div id="built-in-alternatives-to-scim">
  ### SCIM 的内置替代方案
</div>

Devin 提供了多项功能，可覆盖 SCIM 的常见使用场景：

1. **即时预配** — 用户首次通过 SSO 登录时会自动创建，并分配默认的 Enterprise 角色
2. **每次登录时的全量组同步** — 每次用户登录时，Devin 都会对其 IdP 组执行一次完整 diff：添加新组、移除旧组
3. **基于组的 RBAC** — 你可以在 Devin 设置中将 IdP 组映射到 Enterprise 角色和组织访问权限，并在用户下次登录时生效
4. **用于 automation 的 V2 API** — 可通过脚本实现邀请、移除以及批量角色变更，以弥补预配/取消预配方面的不足
5. **审计日志** — 每次登录都会被记录，便于了解哪些人访问过 Devin

***

<div id="3-configuring-idp-managed-groups">
  ## 3. 配置由 IdP 管理的组
</div>

如果你也在其他应用 (例如 Slack、Box) 中使用 SCIM，本节将说明 Devin 的组模型是如何运作的，以及如何正确配置你的 IdP。

<div id="context-scim-groups-vs-idp-groups">
  ### 背景：SCIM 组与 IdP 组
</div>

* **SCIM 组：** 下游应用会告知 IdP 存在哪些组 (即 IdP 会“导入”这些组) 。应用是组结构的权威数据源。IdP 会将用户同步到这些由应用定义的组中。
* **IdP 组 (Devin 使用的方式) ：** IdP 是权威数据源。组在 IdP 的目录中定义，组成员关系会在登录时通过 SAML/OIDC 声明同步到 Devin。

由于 Devin 不使用 SCIM，你实际上已经处于“IdP 组”模式。关键在于确保你的 IdP 发送了正确的组，并在 Devin 中正确完成映射。

<div id="step-1-define-groups-in-the-idp">
  ### 步骤 1：在 IdP 中定义组
</div>

在你的 IdP Admin Console 中 (以下示例使用 Okta) ：

1. 前往 **Directory → Groups**
2. 创建与 Devin 访问级别相对应的组 (例如 `Devin-Engineering`、`Devin-Admins`、`Devin-DataScience`)
3. 将用户分配到这些组

这些都是 IdP 原生组——谁属于哪个组，以你的 IdP 为准。

<div id="step-2-configure-group-claims-in-the-idp-app">
  ### 步骤 2：在 IdP 应用中配置组声明
</div>

必须在身份验证响应中包含这些组信息，以便 Devin 读取。

<div id="for-saml-connections">
  #### 对于 SAML 连接
</div>

1. 前往 **Applications → \[Devin App] → SAML Settings → Edit**
2. 在 **Group Attribute Statements** 下添加：
   * **名称：** `groups`
   * **筛选器：** "开头为" → `Devin-` (或使用 "匹配正则表达式" 来匹配更复杂的模式)
3. 这会告知 IdP 在 SAML 断言中包含匹配的组名

<div id="for-oidc-connections">
  #### 对于 OIDC 连接
</div>

1. 前往 **Applications → \[Devin App] → Sign On → Edit**
2. 在 **OpenID Connect ID Token → Groups claim type** 下，选择 "Filter"
3. 将过滤器设置为匹配 Devin 组 (例如，"Starts with" → `Devin-`)

<Tip>
  使用 `Devin-` 这样的过滤前缀，以便只发送相关组。无需发送组织中的每个 IdP 组。
</Tip>

<div id="step-3-map-groups-to-roles-and-orgs-in-devin">
  ### 步骤 3：在 Devin 中将组映射到角色和组织
</div>

登录时组信息成功传递后，请在 Devin 中进行映射。

<div id="in-the-devin-ui">
  #### 在 Devin UI 中
</div>

1. **Settings → Enterprise → Identity Provider Groups**
2. 当任一组的成员登录后，该组会自动显示
3. 点击某个组 → 为其分配企业级角色 (例如 Enterprise Admin 或自定义角色)
4. 点击某个组 → 将其分配到特定组织，并授予相应的组织级角色

<div id="via-the-api-for-pre-setup-or-automation">
  #### 通过 API (用于预配置或自动化)
</div>

* 在任何人登录前预先创建组：`PUT /v2/enterprise/groups`
* 列出组及其组织归属：`GET /v2/enterprise/groups`

<div id="step-4-if-migrating-from-scim-groups-in-other-apps">
  ### 步骤 4：如果要从其他应用中的 SCIM 组迁移
</div>

如果你要将整体 IdP 策略从由 SCIM 管理的组，调整为在各个工具中由 IdP 管理的组 (不只是 Devin) ：

1. 在其他应用中**停止导入 SCIM 组**：
   * 在 IdP 中：前往应用的 **Provisioning → Integration** 选项卡 → 取消选中“Import Groups”
   * 这样会使下游应用不再作为组的权威数据源
2. 在 IdP 目录中**创建对应的组**：
   * 前往 **Directory → Groups**，创建与下游应用中现有组相对应的组
   * 将用户分配到这些 IdP 原生组
3. **配置组推送** (适用于支持该功能的应用) ：
   * 在应用的 IdP 配置中：**Push Groups** 选项卡 → 按名称查找组 → 链接到现有的下游组
   * 这样会让 IdP 覆盖应用内部的成员关系，IdP 将成为唯一的权威数据源
   * Devin 不需要组推送，因为它会直接从登录断言中读取组信息
4. 在其他应用中**禁用 SCIM 组同步**：
   * 确保“Import Groups”保持关闭，以防止下游应用重新成为权威数据源

对于 Devin，无需迁移。只需确保已完成上述步骤 1–3 (即在你的 IdP 中定义组、配置声明，并在 Devin 中设置映射) 。

***

<div id="key-considerations">
  ## 关键注意事项
</div>

<AccordionGroup>
  <Accordion title="IdP 中的组重命名">
    如果某个组被重命名，Devin 会将其视为一个新组。旧组的角色映射不会自动继承——你需要在 Devin 的设置中重新配置新的组名。
  </Accordion>

  <Accordion title="添加到组并不意味着会立即获得 Devin 访问权限">
    用户被添加到映射到 Devin 的 IdP 组后，只有在登录后才会获得相应访问权限。
  </Accordion>

  <Accordion title="从组中移除并不意味着会立即失去 Devin 访问权限">
    将用户从 IdP 组中移除后，其 Devin 访问权限不会立即被撤销。在用户下次登录时，Devin 会进行同步并移除过期的组成员身份。任何直接成员身份 (即在组之外分配的成员身份) 都不会受到影响。
  </Accordion>

  <Accordion title="组名必须精确匹配">
    IdP 中的组名必须与 Devin 识别到的名称完全一致。区分大小写。
  </Accordion>

  <Accordion title="不支持嵌套组">
    Devin 不支持嵌套/层级组。如果 IdP 发送的是父组，子组成员不会自动包含在内。每个组都必须显式分配。
  </Accordion>
</AccordionGroup>

***

<div id="recommended-setup-for-scim-like-behavior">
  ## “类 SCIM”行为的推荐配置
</div>

如果你不使用 SCIM，但又希望获得尽可能严格的控制，请采用以下方法：

<Steps>
  <Step title="配置你的 Identity Provider（权威数据源）">
    1. 定义组：`Devin-Admins`、`Devin-Backend`、`Devin-Frontend` 等
    2. 将用户分配到相应组
    3. 配置 SAML/OIDC 组声明，并将过滤条件设为“Starts with: `Devin-`”
  </Step>

  <Step title="Devin 在每次登录时同步">
    当用户通过 SSO 登录时，Devin 会自动：

    * 如果是新用户，则自动创建该用户
    * 执行完整的组同步 (添加新组，移除失效组)
    * 立即应用组到角色和组到组织的映射
  </Step>

  <Step title="可选：使用 V2 API 实现自动化">
    设置一个定时任务来补齐 SCIM 的缺口：

    1. 从你的 IdP API 读取活跃用户
    2. 从 `GET /v2/enterprise/members` 读取 Devin 成员
    3. 通过 `POST /v2/enterprise/members/invite` 邀请新员工
    4. 通过 `DELETE /v2/enterprise/members/{user_id}` 移除已离职员工

    这样，即使不使用 SCIM，你也能实现推送式的预配和取消预配。
  </Step>
</Steps>

<div id="what-this-gives-you">
  ### 这能为你带来什么
</div>

* 将你的 IdP 作为组结构和成员关系的唯一可信权威数据源
* 每次登录时自动授予基于组的访问权限
* 通过 API 驱动的预配/去预配来弥补原本通常由 SCIM 填补的空缺
* 为所有登录和成员变更提供完整的审计记录

<div id="current-limitations">
  ### 当前限制
</div>

* **登录间的组实时同步** — 组仅在用户登录时更新
* **取消预配后立即撤销会话** — 会话会一直保持有效，直到过期
* **由 IdP 发起的生命周期事件** (如 suspend/reactivate) 暂不支持