> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/zhang-hu-yu-ji-fei/sso-and-saml.md).

# SSO 和 SAML

了解如何通过 SSO 和 SAML 分享你的 GitBook 内容

使用电子邮件域名或 SAML 单点登录 (SSO) 管理组织访问权限。在组织的 **设置** → **访问权限**.

## 通过电子邮件域实现单点登录

添加电子邮件域，以便具有匹配且已验证电子邮件地址的人在登录时加入你的组织。

要配置电子邮件域：

1. 在组织菜单中，点击 **设置**.
2. 在 **组织**下，选择 **访问权限**.
3. 在 **允许的电子邮件域名**下，添加要允许的每个域名，例如 `mycompany.com`.
4. 在 **新成员**下，选择自动加入的人员所使用的 **默认角色** 。

仅接受工作电子邮件域名。不能添加个人电子邮件域名，例如 `gmail.com`。

<figure><img src="broken://files/4edf0b9b93b0f4af2af7430960374f60cd46dae6" alt="The Access management settings showing allowed email domains, the default role for new members, and the option to register a SAML identity provider"><figcaption><p>为你的组织设置 SSO。</p></figcaption></figure>

{% hint style="info" %}
默认角色也适用于通过身份提供商加入的成员。你可以随时在 **组织 → 成员**.
{% endhint %}

## SAML 单点登录

SAML SSO 允许成员通过你的身份提供商（IdP）访问。

GitBook 使用你的 IdP 进行成员身份验证。组织管理员仍然可以使用其他方式登录。这可以防止在 SSO 配置错误后被锁定。

### 前置条件 <a href="#prerequisites-for-sso-with-gitbook" id="prerequisites-for-sso-with-gitbook"></a>

SAML SSO 仅适用于 Enterprise 套餐。

* 你公司的身份提供商 (IdP) 必须支持 **SAML 2.0** 标准。
* 你必须在 IdP 上具有管理权限。
* 你必须是 GitBook 组织的管理员。

### 在 GitBook 中设置 SAML <a href="#setup-on-gitbook" id="setup-on-gitbook"></a>

你必须是 [组织管理员](https://gitbook.com/docs/documentation/zh/collaborate/member-management/roles.md#admin) 才能配置 SAML。

要配置 SAML：

1. 在组织菜单中，点击 **设置**.
2. 在 **组织**下，选择 **访问权限**.
3. 在 **SAML**下，点击 **注册身份提供商** ，然后输入 IdP 提供的详细信息。
4. 保存配置后，将 SSO 登录 URL 分享给你的成员。

保存配置后，GitBook 不会发送公告邮件。

{% hint style="info" %}
即使启用了 **强制使用 SSO** ，组织管理员仍可使用非 SSO 方式登录。你可能仍会看到 Google、GitHub 或电子邮件选项。

这可以防止因错误的 SSO 设置而无法进入你的组织。管理员始终可以登录并移除或修复 SSO 设置。
{% endhint %}

你需要从 IdP 获取以下信息：

* **标签** — 显示在登录页面上。
* **实体 ID**.
* **单点登录 URL**.
* **X.509 证书** — 请提供完整证书。

### 设置 IdP <a href="#setup-on-the-idp" id="setup-on-the-idp"></a>

大多数符合 SAML 2.0 标准的 IdP 都需要服务提供商详细信息。在 GitBook 中，打开 **设置 → 组织 → 访问权限** ，然后在 **SAML**.

将这些值复制到你的 IdP 中，即可完成 SAML 配置。

下找到组织对应的值。GitBook 需要 **NameID** 包含成员的电子邮件地址。NameID 格式请使用 `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` 。许多 IdP 会将此格式称为 **电子邮件**.

### 自定义属性

GitBook 在创建账户时会从 SAML 断言中读取这些自定义属性。

| 字段           | 说明                                                      |
| ------------ | ------------------------------------------------------- |
| `first_name` | `first_name` 和 `last_name` 字段将组合起来，作为用户在 GitBook 中的显示名称 |
| `last_name`  | `first_name` 和 `last_name` 字段将组合起来，作为用户在 GitBook 中的显示名称 |

## ​创建终端用户账户 <a href="#creating-end-user-account" id="creating-end-user-account"></a>

要添加成员，请在你的 IdP 中为他们创建账户。新成员首次通过 IdP 登录 GitBook 时，系统会通过自动 IdP 预配为他们创建一个 GitBook 账户。该用户将作为组织成员访问组织资源。

{% hint style="danger" %}
设置要求使用小写电子邮件地址。请勿使用大小写混合的电子邮件地址。‌
{% endhint %}

## ​移除账户 <a href="#removing-end-user-accounts" id="removing-end-user-accounts"></a>

从 IdP 中移除成员后，该用户将无法登录对应的 GitBook 账户， **但不会从 GitBook 中删除该账户**。我们还建议从 GitBook 组织中移除该账户。

## 控制访问

一旦你设置了 SAML SSO，谁可以访问你的 GitBook 账户就由 IdP 来负责控制。

## ​安全提示 <a href="#security-notice" id="security-notice"></a>

GitBook 绝不会代表管理员将现有账户关联到你的身份提供商。只有账户所有者才能通过你的 IdP 登录来进行关联。

如果某人已经拥有与你的 IdP 发送的邮箱地址对应的 GitBook 账户，使用 SAML 登录不会自动将其添加到你的组织。要授予其访问权限：

1. 邀请他们加入你的组织。
   * 如果 **强制使用 SSO** 未启用，请从 **成员** 页面邀请他们加入组织。
   * 如果 **强制使用 SSO** 已启用，请使用 `invites` API 端点，并设置 `"sso": true`:

     ```bash
     curl --request POST \
       --url "https://api.gitbook.com/v1/orgs/<org_id>/invites" \
       --header "Authorization: Bearer <your_access_token>" \
       --header "Content-Type: application/json" \
       --data-raw '{ "sso": true, "role": "<role>", "emails": ["<email>"] }'
     ```
2. 请他们使用现有账户登录 GitBook 并打开你的组织。GitBook 提示时，他们通过你的 IdP 登录，这会将他们的账户与你的 SSO 关联。

邀请会立即将现有账户添加为成员。API 响应会在 `failedSSOEmails`中列出该账户，因为它尚未关联到你的 IdP。通过邀请创建的账户会立即完成关联。

{% hint style="info" %}
一个 GitBook 账户一次只能关联到一个组织的 SSO。如果该账户已关联到另一个组织，其所有者就无法打开启用了 **强制使用 SSO** 的组织中的内容。
{% endhint %}

或者，此人可以删除其现有的 GitBook 账户，然后使用 SAML 登录到你的组织。GitBook 会创建一个新账户并将其添加到你的组织。删除账户会移除其对所有其他组织的访问权限。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/zhang-hu-yu-ji-fei/sso-and-saml.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
