# 设置 Okta

{% hint style="warning" %}
本指南将带你完成为文档设置受保护的登录界面。在阅读本指南之前，请确保你已经先完成了 [启用经过身份验证的访问](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/zhan-dian-fang-wen/authenticated-access/enabling-authenticated-access).
{% endhint %}

要使用 Okta 为你的 GitBook 站点设置经过身份验证的访问，流程如下：

{% stepper %}
{% step %}
**创建一个新的 Okta 应用**

从你的 Okta 仪表板创建一个 Okta 应用。
{% endstep %}

{% step %}
**安装并配置 Okta 集成**

安装 Okta 集成并添加所需配置。
{% endstep %}

{% step %}
**配置 Okta 以支持自适应内容（可选）**

配置 Okta 以便在 GitBook 中与自适应内容配合使用。
{% endstep %}
{% endstepper %}

### 创建一个新的 Okta 应用

首先，登录到 Okta 平台（管理员版本），然后通过点击左侧边栏中的 Applications 按钮来创建一个新的应用集成（或使用现有的一个）。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2F8roQ3QDR5zsyFh2FoQS4%2FScreen%20Shot%202023-10-30%20at%201.32.55%20PM.png?alt=media&#x26;token=dc46f9f6-ec54-456f-ba7b-397477089e1a" alt="An Okta screenshot showing the create app integration screen"><figcaption></figcaption></figure>

点击 Create App Integration，并选择 OIDC - OpenID Connect 作为登录方法。然后选择 Web Application 作为应用类型。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FqgFHYo6HOUGF8dUTFEJM%2FScreen%20Shot%202023-10-30%20at%201.39.15%20PM.png?alt=media&#x26;token=0ac8e337-6082-4a28-b3df-33fa4e33dc0d" alt="An Okta screenshot showing the integration setup"><figcaption></figcaption></figure>

为其取一个合适的名称，并且不要修改该页面上的任何其他设置。对于 assignments，选择相应的复选框。点击 Save。

在下一个界面中，复制 Client ID 和 Client Secret。通过点击右上角的下拉菜单，复制位于你的电子邮件地址正下方的 Okta Domain。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FJQWvrITuUlno737DbQKM%2FScreen%20Shot%202023-10-30%20at%204.52.14%20PM.png?alt=media&#x26;token=82a63cfd-a1e6-4666-b132-30fc98e95c22" alt="An Okta screenshot showing where to copy client credentials"><figcaption></figcaption></figure>

我们将需要这些值来配置 Okta Integration。

### 安装并配置 Okta 集成

在你想要发布的网站中，导航到 Integrations 选项卡并找到 Okta 集成。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FeFArORtsvAcvgwbDZNce%2FScreen%20Shot%202024-12-13%20at%203.21.30%20PM.png?alt=media&#x26;token=199acbf6-3100-49af-886e-d2d09445f978" alt="A GitBook screenshot showing the site settings page"><figcaption></figcaption></figure>

在你的网站上安装该集成。

在网站上安装后，你会看到一个界面，要求你输入 Client ID、Okta Domain 和 Client Secret。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FHrwQ0ASv1tD6kTZPVLMY%2FScreen%20Shot%202024-12-13%20at%203.34.37%20PM.png?alt=media&#x26;token=0844c1db-14b8-415c-8d51-33d4618e900e" alt="A GitBook screenshot showing the Okta credentials modal"><figcaption></figcaption></figure>

对于 Client ID、Okta Domain（移除 `https://`前缀，如有）以及 Client Secret，请粘贴你从 Okta Dashboard 复制的值。

点击 Save。

复制模态框中显示的 URL，并将其作为 Okta 中的登录重定向 URI 输入（如下面的截图所示）。点击 Save。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FpPZlqJlE6koyHrWhSp8i%2FScreen%20Shot%202024-01-14%20at%207.55.08%20PM.png?alt=media&#x26;token=99abc690-c82b-4974-9b5a-7ba6fbd11ed2" alt="An Okta screenshot showing the sign-in redirect URI configuration"><figcaption></figcaption></figure>

现在，在 GitBook 中，关闭集成模态框并点击 Manage site 按钮。导航到 **受众**，选择 **身份验证访问**，并选择 Okta 作为后端。然后，点击 **更新受众**。进入网站页面并点击 **发布**。\
\
该网站现在已发布在由你的 Auth0 应用控制的经过身份验证的访问之后。要试用它，请点击 Visit。系统会要求你使用 Okta 登录，这确认了你的网站已通过 Auth0 以经过身份验证的访问方式发布。

### 配置 Okta 以支持自适应内容（可选）

要在具有经过身份验证的访问的 GitBook 站点中启用 Adaptive Content，你需要配置你的 Okta 应用，将相关用户数据作为声明包含在身份验证令牌中。

声明是嵌入在发送到 GitBook 的令牌中的键值对。这些声明可用于根据用户的角色、计划、位置或任何其他标识属性，动态定制文档内容。

Okta 支持多种类型的声明：

* **标准声明**\
  这些是常见声明（例如 `电子邮件`, `name`，或 `组`），它们可能会默认包含，但通常需要显式添加到你的令牌配置中，以确保持续可用。
* **自定义声明**\
  你可以在 Okta 中使用 [自定义用户属性](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) 或基于表达式的逻辑来定义自定义声明。这些允许你传递高度具体的值——例如套餐等级、账户 ID 或内部团队标记。
* **作为声明的组**\
  你也可以将 Okta 组作为声明传递，这在定义“企业用户”或“测试版用户”之类的受众细分时尤其有用。这些可以在你的授权服务器的声明配置中进行筛选和映射。

要在 Okta 中添加或自定义声明：

1. 打开你的 Okta 管理控制台。
2. 导航到 **Security > API > Authorization Servers**.
3. 编辑你的 GitBook 站点所使用的授权服务器。
4. 在 **Claims** 选项卡下，添加规则以将所需的声明包含在令牌中。
5. 确保你的 GitBook 站点正在正确读取并映射这些声明。

一旦这些声明被传递到 GitBook 中，请按照 [为你的内容添加适配](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/zhan-dian-fang-wen/adaptive-content/adapting-your-content) 中的步骤来定义应向谁显示哪些内容。