SSO 与 SAML

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

此功能适用于 企业版计划.

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

通过邮箱域进行单点登录

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

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

为你的组织设置 SSO。

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

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

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

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

使用 GitBook 进行 SSO 的前提条件

• 你公司的身份提供商（IdP）必须支持 SAML 2.0 标准。

• 你必须在该 IdP 上拥有管理员权限。

• 你必须是要为其设置 SAML 的 GitBook 组织的管理员。

在 GitBook 上设置

你必须是 组织管理员 才能为你的 GitBook 组织启用 SSO。

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

组织管理员仍然可以使用非 SSO 方式登录，因此你可能仍会看到 Google、GitHub 或电子邮件按钮。即使启用了 强制 SSO ，这也是正常的。

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

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

• 一项 label ——这可以是任意内容，它会显示在登录页面上

• 一个 实体 ID

• 一项 单点登录 URL

• 一个 X.509 证书 ——请务必复制并粘贴完整的证书！

在 IdP 上设置

大多数符合 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 中的显示名称

创建最终用户账户

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

设置要求使用小写电子邮件地址。不要使用大小写混合的电子邮件地址。

移除账户

从 IdP 中移除成员将阻止该用户登录对应的 GitBook 账户， 但不会从 GitBook 中删除该账户。我们建议同时从 GitBook 组织中移除该账户。

控制访问

一旦你设置了 SAML SSO，控制谁可以访问你的 GitBook 账户的责任就落在 IdP 上。

安全提示

如果你已经有一个与我们从身份提供商获取到的邮箱地址相同的 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>"] }'