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 提供商：

• 一个 标签 —— 可以是任意内容，它将显示在登录页面上

• 一个 实体 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 的 邀请 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>"] }'