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

# SAML SSO 设置

> 为您的 Krea 企业工作区配置 SAML 单点登录，并与您的身份提供商集成，以实现安全、集中的团队身份验证。

<Info>
  **仅限 Krea 企业版** — SAML SSO 仅向 Krea 企业版客户开放。[联系我们的销售团队](mailto:sales@krea.ai)了解更多关于企业计划的信息。
</Info>

本指南将引导您为 Krea 工作区配置 SAML 单点登录 (SSO)。配置完成后，使用您已验证域名电子邮件地址的用户可以使用您组织的身份提供商 (IdP) 登录。

## 前提条件

在开始之前，请确保您已具备：

<CardGroup cols={2}>
  <Card title="已验证的域名" icon="circle-check">
    先完成[域名验证](/user-guide/help-and-support/domain-verification)
  </Card>

  <Card title="工作区角色" icon="user-shield">
    您必须是**工作区所有者**或**管理员**
  </Card>

  <Card title="身份提供商访问权限" icon="key">
    您的 IdP（Okta、Google Workspace 等）的管理员访问权限
  </Card>

  <Card title="企业计划" icon="building">
    有效的 Krea 企业版订阅
  </Card>
</CardGroup>

## 第 1 步：获取 Krea 的服务提供商详情

完成域名验证后，设置弹窗将显示 SAML 配置部分。

![SAML 配置弹窗](https://s.krea.ai/docs/sso-saml-config-modal.png)

您需要以下两个值来配置您的身份提供商：

| 字段               | 值                                                  |
| ---------------- | -------------------------------------------------- |
| **ACS URL**      | `https://superb.krea.ai/auth/v1/sso/saml/acs`      |
| **Entity ID**    | `https://superb.krea.ai/auth/v1/sso/saml/metadata` |
| **Metadata XML** | `https://superb.krea.ai/auth/v1/sso/saml/metadata` |

<Tip>
  点击弹窗中每个 URL 旁边的**复制图标**以准确复制它们。
</Tip>

## 第 2 步：配置您的身份提供商

使用第 1 步中的值在您的身份提供商中创建 SAML 应用程序。

<Tabs>
  <Tab title="Okta">
    <Steps>
      <Step title="访问应用程序">
        登录 Okta 管理控制台（通常是 `https://your-org.okta.com/admin`），然后在侧边栏中转到**应用程序** → **应用程序**。
      </Step>

      <Step title="创建应用程序集成">
        点击**创建应用程序集成**。

        选择 **SAML 2.0** 作为登录方式，然后点击**下一步**。
      </Step>

      <Step title="配置常规设置">
        输入 **Krea** 作为应用程序名称。

        可选择上传徽标以便识别。

        点击**下一步**。
      </Step>

      <Step title="配置 SAML 设置">
        输入以下值：

        | 字段                          | 值                                                  |
        | --------------------------- | -------------------------------------------------- |
        | Single sign-on URL          | `https://superb.krea.ai/auth/v1/sso/saml/acs`      |
        | Audience URI (SP Entity ID) | `https://superb.krea.ai/auth/v1/sso/saml/metadata` |
        | Name ID format              | **EmailAddress**                                   |
        | Application username        | **Email**                                          |
      </Step>

      <Step title="完成设置">
        点击**下一步**。

        在反馈页面，选择"I'm an Okta customer adding an internal app"，然后点击**完成**。
      </Step>

      <Step title="获取 Metadata URL">
        在应用程序页面，转到 **Sign On** 选项卡。

        向下滚动至 **SAML Signing Certificates**，找到 **Metadata URL**。点击 **Actions** → **View IdP metadata** 获取 URL。
      </Step>

      <Step title="分配用户">
        转到 **Assignments** 选项卡，并分配应有 Krea 访问权限的用户或组。
      </Step>
    </Steps>

    <Info>
      参考：[Okta 帮助 - 创建 SAML 应用集成 ↗](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm)
    </Info>
  </Tab>

  <Tab title="Google Workspace">
    <Steps>
      <Step title="打开管理控制台">
        使用超级管理员账户登录 [Google 管理控制台 ↗](https://admin.google.com)。

        转到**应用** → **网络和移动应用**。
      </Step>

      <Step title="添加自定义 SAML 应用">
        点击**添加应用** → **添加自定义 SAML 应用**。

        输入 **Krea** 作为应用名称并可选择上传徽标。

        点击**继续**。
      </Step>

      <Step title="下载 IdP 元数据">
        在 **Google Identity Provider details** 页面，您有两个选项：

        **选项 1（推荐）：**点击**下载元数据**以下载 XML 文件。

        **选项 2：**复制 **SSO URL**、**Entity ID**，然后下载**证书**。

        点击**继续**。
      </Step>

      <Step title="配置服务提供商详情">
        输入以下值：

        | 字段             | 值                                                  |
        | -------------- | -------------------------------------------------- |
        | ACS URL        | `https://superb.krea.ai/auth/v1/sso/saml/acs`      |
        | Entity ID      | `https://superb.krea.ai/auth/v1/sso/saml/metadata` |
        | Name ID format | **EMAIL**                                          |
        | Name ID        | **Basic Information > Primary email**              |

        点击**继续**。
      </Step>

      <Step title="配置属性映射（可选）">
        基本 SSO 设置可以跳过属性映射。

        点击**完成**。
      </Step>

      <Step title="开启应用">
        在应用详情页面，点击**用户访问**。

        选择**对所有人开启**（或为特定组织单位配置）。

        点击**保存**。
      </Step>
    </Steps>

    <Note>
      Google Workspace 不提供可公开访问的元数据 URL。您需要在 Krea 中使用 **Metadata XML** 选项（请参阅第 3 步）。
    </Note>

    <Info>
      参考：[Google Workspace 管理员帮助 - 设置自定义 SAML 应用 ↗](https://support.google.com/a/answer/6087519)
    </Info>
  </Tab>
</Tabs>

## 第 3 步：将您的 IdP 连接到 Krea

回到 Krea 弹窗，提供您 IdP 的元数据：

<Tabs>
  <Tab title="URL（推荐）">
    \*\*最适合：\*\*Okta 以及其他提供公共元数据 URL 的 IdP

    1. 在 Krea 弹窗中，选择 **URL** 选项卡
    2. 将您 IdP 的 **Metadata URL** 粘贴到文本字段中
    3. 点击**保存更改**

    <Info>
      使用 URL 可以让 Krea 在您的 IdP 轮换证书时自动获取更新的证书。
    </Info>
  </Tab>

  <Tab title="Metadata XML">
    \*\*最适合：\*\*Google Workspace 或您的元数据 URL 不可公开访问的情况

    1. 在文本编辑器中打开下载的 SAML 元数据 XML 文件
    2. 复制所有内容
    3. 在 Krea 弹窗中，选择 **Metadata XML** 选项卡
    4. 将 XML 内容粘贴到文本区域中
    5. 点击**保存更改**

    <Warning>
      如果您使用 XML，则在您的 IdP 轮换证书时需要手动更新它。
    </Warning>
  </Tab>
</Tabs>

## 第 4 步：测试您的配置

<Steps>
  <Step title="打开无痕窗口">
    使用一个全新的无痕/隐私浏览器窗口，以避免缓存会话。
  </Step>

  <Step title="转到 Krea 登录页">
    导航至 [krea.ai/login ↗](https://krea.ai/login)
  </Step>

  <Step title="点击 SSO 按钮">
    在登录页面，点击 **SSO** 按钮以发起 SAML 身份验证。

    <Warning>
      Krea 不会根据您的电子邮件域名自动重定向。您必须点击 **SSO** 按钮才能使用 SAML 身份验证。设置了密码的用户仍可以使用电子邮件和密码登录。
    </Warning>
  </Step>

  <Step title="输入您的电子邮件">
    输入您已验证域名的电子邮件地址（例如 `you@acme.com`）
  </Step>

  <Step title="通过您的 IdP 进行身份验证">
    您应该会被重定向到您组织的登录页面。
  </Step>

  <Step title="确认访问">
    成功通过身份验证后，您将登录到 Krea。
  </Step>
</Steps>

<Check>
  \*\*成功！\*\*如果您能够登录，则您的 SAML SSO 配置正确。邀请您的团队成员使用工作电子邮件通过 SSO 按钮登录。
</Check>

## 强制使用 SAML SSO

SSO 配置并测试完成后，您可以为所有使用已验证域名的用户强制使用 SSO。这可确保组织中的每个人都通过您的身份提供商进行身份验证。

![工作区设置中的 SSO 强制开关](https://s.krea.ai/docs/sso-enforcement.png)

<Steps>
  <Step title="转到工作区设置">
    导航至[工作区设置 ↗](https://www.krea.ai/settings/workspace-settings)，并滚动至**单点登录 (SSO)** 部分。
  </Step>

  <Step title="找到 SSO 强制选项">
    在您已验证域名的 SSO 卡片上找到 **SSO 强制**开关。
  </Step>

  <Step title="启用开关">
    点击开关以启用 SSO 强制。
  </Step>

  <Step title="确认">
    查看确认对话框并确认以启用强制。
  </Step>
</Steps>

<Warning>
  **启用强制后：**

  * 所有使用已验证域名的用户都将被要求通过您的身份提供商登录
  * 这些用户的密码和魔术链接登录将被禁用
  * 当前会话将持续到用户下次登录，届时他们必须使用 SSO
</Warning>

### 禁用强制

如果您需要禁用 SSO 强制：

1. 转到[工作区设置 ↗](https://www.krea.ai/settings/workspace-settings)
2. 在**单点登录 (SSO)** 部分，找到**强制 SSO** 开关
3. 点击开关以禁用强制
4. 用户将重新获得使用密码或魔术链接登录的能力

<Note>
  禁用强制不会禁用 SSO 本身 — 用户仍然可以通过登录页面上的 SSO 按钮选择使用 SSO 登录。
</Note>

## 故障排查

<AccordionGroup>
  <Accordion title="无法配置 SSO">
    * **检查 URL** — 确保 ACS URL 和 Entity ID 与所示完全一致（没有尾部斜杠）
    * **验证元数据访问** — 如果使用 URL，请确保它可公开访问
    * **改用 XML** — 如果 URL 不起作用，请下载并直接粘贴 XML
    * **检查证书是否过期** — IdP 证书过期将导致配置失败
  </Accordion>

  <Accordion title="用户无法登录">
    * **点击 SSO 按钮** — 用户必须点击登录页面上的 SSO 按钮（而不仅仅是输入他们的电子邮件）
    * **在 IdP 中分配用户** — 用户必须在您的 IdP 中分配到 Krea SAML 应用
    * **检查 Name ID** — 验证在您的 IdP 中 Name ID 设置为 email/EmailAddress 格式
    * **验证电子邮件域名** — 用户电子邮件必须与已验证的域名完全匹配
    * **检查用户配置** — 用户可能需要先被邀请到 Krea 工作区
  </Accordion>

  <Accordion title="出现 Invalid SAML response 错误">
    * **时钟偏差** — 确保您的 IdP 服务器时钟准确（与实际时间相差在 5 分钟内）
    * **断言条件** — 检查 SAML 断言的 NotBefore/NotOnOrAfter 条件是否有效
    * **签名问题** — 验证使用了正确的证书
  </Accordion>

  <Accordion title="重定向循环或空白页面">
    * **清除 Cookie** — 清除所有与 Krea 相关的 Cookie，然后重试
    * **检查 ACS URL** — 确保您 IdP 中配置的 ACS URL 没有错字
    * **验证域名** — 确认域名验证仍然有效
  </Accordion>
</AccordionGroup>

## 管理 SSO

### 查看 SSO 状态

1. 转到[工作区设置 ↗](https://www.krea.ai/settings/workspace-settings)
2. 滚动至**域名管理**部分
3. SSO 卡片显示：
   * 带有绿色指示器的**已启用**状态
   * 您已验证的**域名**
   * **配置**按钮，用于修改设置

### 更新 IdP 元数据

如果您需要更新 IdP 元数据（例如，在证书轮换后）：

1. 转到[工作区设置 ↗](https://www.krea.ai/settings/workspace-settings)
2. 在**域名管理**部分，点击 SSO 卡片上的**配置**
3. 更新元数据 URL 或 XML
4. 点击**保存更改**

### 禁用 SSO

<Warning>
  禁用 SSO 将要求所有用户使用电子邮件和密码登录。请在禁用之前确保用户已设置密码。
</Warning>

1. 转到[工作区设置 ↗](https://www.krea.ai/settings/workspace-settings)
2. 在**域名管理**部分，点击 SSO 卡片上的**配置**
3. 点击弹窗底部的**禁用 SSO**
4. 确认操作

## 需要帮助？

<CardGroup cols={2}>
  <Card title="企业支持" icon="headset" href="mailto:support@krea.ai">
    通过 **[support@krea.ai](mailto:support@krea.ai)** 联系我们的企业支持团队
  </Card>

  <Card title="销售团队" icon="envelope" href="mailto:sales@krea.ai">
    对企业计划有疑问？请发送邮件至 **[sales@krea.ai](mailto:sales@krea.ai)**
  </Card>
</CardGroup>