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

# SAML SSO 设置

> 使用 SAML 身份提供商配置单点登录

如果你的组织使用基于 SAML 的身份提供商 (例如通过 SAML 的 Microsoft Entra ID、ADFS、Ping Identity、OneLogin，或其他符合 SAML 2.0 的 IdP) ，你可以使用通用 SAML 为 Devin Enterprise 配置 SSO 功能。

<Note>
  本指南适用于希望使用 **SAML**，而不是原生 [Microsoft Entra ID (OIDC) ](/zh/enterprise/security-access/sso/azure) 或 [Okta (OIDC) ](/zh/enterprise/security-access/sso/okta) 集成的客户。我们通常建议在可能的情况下使用原生 OIDC 集成，但在某些情况下，SAML SSO 会是更合适的选择。
</Note>

<div id="what-youll-need">
  ## 所需准备
</div>

要为 Devin 配置 SAML SSO (单点登录) ，您需要以下信息。您将在下面的设置步骤中收集这些信息，并在最后一步将其发送给您的 Cognition 账户团队。

* **Sign In URL** - 您的 IdP 的 SAML SSO 端点 (例如：`https://idp.example.com/sso/saml`)
* **X509 Signing Certificate** - 您的 IdP 用于对 SAML 断言进行签名的公钥证书
* **Identity Provider Domains** - 所有将通过此 IdP 进行身份验证的公司电子邮件域名 (例如：`example.com`、`subsidiary.example.com`)
* **Group Attribute Name** (如果使用 IdP 组) - 您的 IdP 用于发送组成员信息的 SAML 属性名称

<div id="setup-instructions">
  ## 设置说明
</div>

<div id="step-1-create-a-saml-application-in-your-idp">
  ### 步骤 1：在您的 IdP 中创建一个 SAML 应用
</div>

在身份提供方的管理控制台中，创建一个新的 SAML 2.0 应用，并按以下设置配置：

| 设置                                       | 值                                                                            |
| :--------------------------------------- | :--------------------------------------------------------------------------- |
| **ACS (Assertion Consumer Service) URL** | `https://auth.devin.ai/login/callback`                                       |
| **Entity ID / Audience URI**             | 暂时留空——参见[步骤 5](#step-5-complete-configuration-with-cognition)                |
| **Name ID Format**                       | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` (推荐) 或 `persistent` |
| **Name ID Value**                        | 用户的电子邮箱地址                                                                    |
| **Signature Algorithm**                  | RSA-SHA256                                                                   |
| **Digest Algorithm**                     | SHA256                                                                       |
| **Response Binding**                     | HTTP-POST                                                                    |

<div id="step-2-configure-saml-attributes">
  ### 步骤 2：配置 SAML 属性
</div>

确保你的 IdP 在 SAML 断言中发送以下属性：

| SAML 属性                                                                | 描述                     | 是否必需 |
| :--------------------------------------------------------------------- | :--------------------- | :--- |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` | 唯一用户标识符 (通常是用户的电子邮件地址) | 是    |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`   | 用户的电子邮件地址              | 是    |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`           | 用户的显示名称                | 建议   |

<Note>
  Devin 使用 `nameidentifier` 属性来标识用户。大多数 IdP 会自动从 SAML **Name ID** 值填充该属性。如果你的 IdP 未将 `nameidentifier` 作为单独属性发送，请确保在步骤 1 中将 **Name ID Value** 设置为用户的电子邮件地址。
</Note>

<div id="step-3-configure-group-assertions-required-for-idp-groups">
  ### 步骤 3：配置组断言 (使用 IdP 组时必需)
</div>

<Warning>
  如果你想在 Devin 中使用 [IdP 组集成](/zh/enterprise/security-access/idp-groups)来进行基于角色的访问控制，你**必须**将 IdP 配置为在 SAML 断言中发送组成员信息。否则，用户虽然可以成功完成认证，但 IdP 组将无法同步。
</Warning>

要启用 IdP 组同步，请在你的 SAML 应用中配置一个**组属性 (group attribute) **：

| SAML Attribute      | Value                                     |
| :------------------ | :---------------------------------------- |
| **Attribute Name**  | `http://schemas.xmlsoap.org/claims/Group` |
| **Attribute Value** | 用户的组成员关系 (用户所属的所有组)                       |

<Note>
  具体的属性名称可能会因 IdP 不同而有所差异。组常见的属性名称包括：

  * `http://schemas.xmlsoap.org/claims/Group`
  * `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`
  * `groups`
  * `memberOf`

  **请将你配置的精确属性名分享给 Cognition 客户团队**，以便我们在我们这边正确完成映射。
</Note>

<div id="microsoft-entra-id-with-saml">
  #### 使用 SAML 的 Microsoft Entra ID
</div>

如果您使用的是基于 SAML 的 Microsoft Entra ID，而不是原生的 OIDC 集成：

1. 在 Azure 门户中，前往 **Enterprise Applications** > 您的 SAML 应用 > **Single sign-on**
2. 在 **Attributes & Claims** 下，点击 **Add a group claim**
3. 选择 **Groups assigned to the application** (推荐) 或 **All groups**
4. 将 **Source attribute** 设置为适合您环境的值 (例如 `sAMAccountName` 或 `Display name`)
5. 记录 Azure 生成的 **Claim name** (例如 `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`) ，并将其分享给您的 Cognition 账户团队

<div id="other-saml-identity-providers">
  #### 其他 SAML 身份提供商
</div>

对于其他 IdP (ADFS、Ping Identity、OneLogin 等) ：

1. 在你的 SAML 应用配置中添加一个组属性声明
2. 将其配置为发送用户所属的组信息
3. 记录下该属性的准确名称，并将其提供给你的 Cognition 客户经理团队

<div id="step-4-send-configuration-to-cognition">
  ### 步骤 4：将配置发送给 Cognition
</div>

将以下信息发送给你的 Cognition 客户团队：

1. **登录 URL** (例如 `https://idp.example.com/sso/saml`)
2. **X509 签名证书** (公钥证书文件或 PEM 编码文本)
3. **身份提供商域名** (此 IdP 的所有邮箱域名)
4. **组属性名称** (如果使用 IdP 组) — 在步骤 3 中配置的 SAML 属性名称 (需完全一致)

<div id="step-5-complete-configuration-with-cognition">
  ### 步骤 5：与 Cognition 完成配置
</div>

在收到你的配置信息后，Cognition 客户团队将会：

1. 创建 SAML 连接，并向你提供 **Entity ID / Audience URI** 和一个 **connection name (连接名称) **
2. 映射你的组属性 (如果适用) ，以便在每次用户登录时自动同步 IdP 组

在收到 Entity ID 后，请将你的 SAML 应用中的 **Entity ID / Audience URI** 设置更新为提供的值。

<Note>
  Devin 会发送带签名的 SAML 身份验证请求。你的 SAML 元数据文件可在以下地址获取：

  ```
  https://auth.devin.ai/samlp/metadata?connection=<connection_name>
  ```

  其中 `<connection_name>` 是 Cognition 客户团队提供的连接名称。将此元数据导入到你的 IdP 中，以完成信任配置并启用请求签名验证。
</Note>

<div id="verifying-your-setup">
  ## 验证你的设置
</div>

在你更新 Entity ID 并且 Cognition 客户团队确认已完成配置之后：

1. 访问你的 Devin Enterprise URL (例如：`https://<your_subdomain>.devinenterprise.com`)
2. 点击 **Sign in with SAML** (或相应的 SSO 按钮) 以开始登录流程
3. 系统会将你重定向到 IdP 的登录页面
4. 完成认证后，你应当进入你的 Devin Enterprise 组织

要验证 IdP 组是否正常工作：

1. 在 Devin 网页应用中，前往 **Settings** > **IdP Groups**
2. 在至少有一名组成员登录之后，你应当能看到你的 IdP 组被列出
3. 组会在每次登录时同步，因此在 IdP 中进行的任何成员变动都会在用户下次登录时生效

<Note>
  IdP 组会在用户登录时获取，因此组成员变更需要用户重新认证。有关配置基于组的访问控制的更多详细信息，请参阅 [IdP Group Integration](/zh/enterprise/security-access/idp-groups)。
</Note>