# SSO 与 SAML

虽然对于小团队或希望拥有大量控制权的人来说，手动管理组织成员也没问题，但有时你只需要以更自动化的方式开放访问。GitBook 允许你通过两种方式进行配置：基础的邮箱域 SSO，以及更复杂的 SAML 集成。

## 通过邮箱域进行单点登录

当你创建或管理组织时，你可以添加一个允许访问你的 GitBook 组织的邮箱域列表。这意味着，任何拥有与你配置的 SSO 域匹配的已验证邮箱地址的人，都将被允许加入你的组织。

你可以在组织的 **SSO** 部分中启用邮箱域 SSO； **设置**输入一个用逗号分隔的邮箱域列表，指定你希望允许 SSO 访问的域，就可以了。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FF860Y1oqJmnsPKOjZ1n2%2Faccount-settings-sso.svg?alt=media&#x26;token=c63d515a-a261-4f6e-b3aa-c39f3d03f0b4" alt="A GitBook screenshot showing how to configure SSO"><figcaption><p>为你的组织设置 SSO。</p></figcaption></figure>

{% hint style="info" %}
任何通过 SSO 邮箱域加入的人，默认都会获得访客权限；你可以随时在组织设置的成员部分更改他们的角色。
{% endhint %}

**基于 SAML 的单点登录** （SSO）使成员能够通过你选择的身份提供商（IdP）访问 GitBook。

GitBook 可以轻松集成你现有的身份提供商（IdP），因此你可以使用与其他服务提供商相同的凭据和登录体验，为员工提供 GitBook 的单点登录。

通过使用 SSO，你的员工将能够使用熟悉的身份提供商界面登录 GitBook，而不是 GitBook 登录页面。随后，员工的浏览器会将他们转发到 GitBook。在启用 SSO 且 GitBook 自身的登录机制被停用时，IdP 会授予对 GitBook 的访问权限。这样，身份验证安全性就转移到你的 IdP，并与你的其他服务提供商协同管理。

## 使用 GitBook 进行 SSO 的前提条件 <a href="#prerequisites-for-sso-with-gitbook" id="prerequisites-for-sso-with-gitbook"></a>

* 你公司的身份提供商（IdP）必须支持 **SAML 2.0** 标准。
* 你必须在该 IdP 上拥有管理员权限。
* 你必须是要为其设置 SAML 的 GitBook 组织的管理员。

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

你必须是 [组织管理员](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/zh/member-management/roles#admin) 才能为你的 GitBook 组织启用 SSO。

在你的 IdP 上完成 SSO 配置后，你将能够输入元数据。配置成功后，管理员会看到确认对话框，并且会显示供最终用户使用的 SSO 登录 URL。 **GitBook 在设置完成时不会发送公告邮件**。管理员有责任通知公司员工（并将登录 URL 告知他们），以便他们能够通过 SSO 访问 GitBook。

{% hint style="info" %}
组织管理员仍然可以使用非 SSO 方式登录，因此你可能仍会看到 Google、GitHub 或电子邮件按钮。即使启用了 **强制 SSO** ，这也是正常的。&#x20;

这可以防止在 SSO 设置错误后被组织锁定在外。管理员始终可以登录并移除或修复 SSO 设置。
{% endhint %}

你需要从 IdP 元数据中获取以下内容，以注册 SAML 提供商：

* 一项 **label** ——这可以是任意内容，它会显示在登录页面上
* 一个 **实体 ID**
* 一项 **单点登录 URL**
* 一个 **X.509 证书** ——请务必复制并粘贴完整的证书！

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

大多数符合 SAML 2.0 标准的身份提供商在设置时都需要关于服务提供商（在此处即 GitBook）的相同信息。这些值是你 GitBook 组织特有的，可在你希望启用 SSO 的 GitBook 组织的 **设置 -> SSO** 选项卡中找到。

这些值中的大多数可以直接复制到你的 IdP 中，以完成 SAML 配置。

GitBook 要求 **NameID** 包含用户的电子邮件地址。具体来说，我们需要： `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` 作为 Name-ID 格式——许多提供商（如 Google）会允许你设置如下格式： **EMAIL**.

### 自定义属性

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 账户，并且你不是你试图登录的组织成员，出于安全原因，我们将无法通过 SAML 配置自动将你添加到该组织。你有两个选择：

1. 删除你现有的 GitBook 账户，然后使用 SAML 登录你想加入的组织。GitBook 将为你创建一个新账户，并把你加入该组织
2. 或者，请你的管理员邀请你加入该组织：

如果你的组织没有启用“强制 SSO”，组织管理员可以通过组织设置中的成员页面邀请用户。

如果你的组织已启用“强制 SSO”，管理员必须使用 GitBook 的 `invites` API 端点邀请用户加入组织。对此 API 的调用如下所示：

```
curl --request POST --header "Authorization: Bearer <your_access_token>" --url "https://api.gitbook.com/v1/orgs/<org_id>/invites" --header 'Content-Type: application/json' --data-raw '{ "sso": true, "role": "<role>", "emails":["<email>"] }'
```