> 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/docs-site/embedding/using-with-authenticated-docs.md).

# 认证

如果你的 GitBook 文档需要身份验证，Docs Embed 需要 GitBook 访客令牌才能访问内容。

有两种方法：

1. **直接传递令牌** （推荐）- 使用 GitBook 访客令牌初始化嵌入。
2. **使用基于 cookie 的检测** - 在加载前检查 GitBook 访客令牌。

## 方法 1：直接传递令牌（推荐）

初始化嵌入时，将 GitBook 访客令牌作为 `visitor.token`.

`visitor.token` 不是来自你的身份提供商的原始访问令牌或 ID 令牌。它是 GitBook 为经过身份验证的文档访问颁发的访客令牌。以下 `your-jwt-token` 这些示例中的值代表该 GitBook 颁发的令牌。

{% tabs %}
{% tab title="独立脚本" %}

```html
<script src="https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token"></script>
<script>
  window.GitBook(
    "init",
    { siteURL: "https://docs.company.com" },
    { visitor: { token: "your-jwt-token" } }
  );
  window.GitBook("show");
</script>
```

{% endtab %}

{% tab title="NPM 包" %}

```javascript
import { createGitBook } from "@gitbook/embed";

const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});

const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: "your-jwt-token",
    unsignedClaims: { userId: "123", plan: "premium" },
  },
});
```

{% endtab %}

{% tab title="React 组件" %}

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    visitor={{
      token: "your-jwt-token",
      unsignedClaims: { userId: "123" },
    }}
  />
</GitBookProvider>
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
嵌入配置 API 没有变化。将 GitBook 颁发的访客令牌作为 `visitor.token`.

对于已认证的网站，GitBook 会将此令牌转发到站点，作为 `jwt_token` 在 iframe/脚本 URL 中。如果你从已认证的网站加载独立脚本，必须在 `jwt_token` 中包含 `<script src>` URL 中。
{% endhint %}

## 基于 OIDC 的站点

Docs Embed 使用 HS256 接受 GitBook 访客令牌流程。你不能更改或配置此算法以接受 RS256 身份提供方令牌。

不要将 OIDC 提供方的访问令牌或 ID 令牌作为 `visitor.token`。使用 RS256 的 Auth0 和 Descope 令牌不兼容，Docs Embed 会因为其签名算法而拒绝它们。不要透传、重新签名或从身份提供方令牌铸造 GitBook 访客令牌。

对于基于 OIDC 的文档站点，请使用以下流程：

1. 将用户发送到你的受保护文档站点 URL，例如 `https://docs.example.com`.
2. 在文档站点上完成正常的交互式 OIDC 登录。
3. 在 GitBook 建立文档站点会话并存储 `gitbook-visitor-token`后，获取该令牌。
4. 在此页面上使用基于 cookie 或直接令牌的方法传递该令牌。

此流程需要先成功登录文档站点。它还需要所需的 cookie 和域可用性。

{% hint style="warning" %}
Docs Embed 无法启动、重定向经过或静默完成文档站点的 OIDC 授权握手。如果首次认证访客需要完全在嵌入中访问，则不存在受支持的集成路径。在加载已认证嵌入之前，请先让他们经过明确的文档站点登录步骤。
{% endhint %}

## 方法 2：基于 cookie 的检测

如果你的文档站点将访客令牌存储在 cookie 中（如 `gitbook-visitor-token`），则可以在加载嵌入前检查它。

用户登录到你的已认证文档站点后，GitBook 会将访客令牌存储在其浏览器 cookie 中，键名为 `gitbook-visitor-token`。嵌入需要此令牌才能从你的文档中获取内容。

**流程如下：**

1. 用户登录你的文档站点。
2. GitBook 将访客令牌存储在浏览器 cookie 中。
3. 你的应用检查该令牌。
4. 如果令牌存在，加载嵌入并传递该令牌。
5. 如果令牌不存在，将用户发送到你的文档站点登录。

{% tabs %}
{% tab title="独立脚本" %}
**复制粘贴代码片段**

仅在用户完成文档站点登录后使用此代码片段：

```html
<script>
  (function () {
    // 检查 cookie 中的访客令牌
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      console.warn("[Docs Embed] 在加载嵌入之前，请先在 https://docs.example.com 登录。");
      return;
    }

    // 令牌存在，加载嵌入
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% hint style="warning" %}
替换 `docs.example.com` 为你的实际文档站点 URL。
{% endhint %}

**另一种方式：提示用户登录**

如果令牌缺失，将用户发送到受保护的文档站点 URL。这将启动受支持的交互式 OIDC 登录流程：

```html
<script>
  (function () {
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      // 重定向到文档或显示消息
      alert("请登录你的文档以获取帮助。");
      window.location.href = "https://docs.example.com";
      return;
    }

    // 使用令牌加载嵌入
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% endtab %}

{% tab title="NPM 包" %}
使用 NPM 包时，在初始化前检查令牌：

```javascript
import { createGitBook } from "@gitbook/embed";

function initializeEmbed() {
  // 检查 cookie 中的令牌
  const getCookie = (name) => {
    const value = `; ${document.cookie}`;
    const parts = value.split(`; ${name}=`);
    if (parts.length === 2) return parts.pop().split(";").shift();
  };

  const token = getCookie("gitbook-visitor-token");

  if (!token) {
    console.warn("[Docs Embed] 在加载嵌入前，请先登录文档站点。");
    return null;
  }

  const gitbook = createGitBook({
    siteURL: "https://docs.example.com",
  });

  const iframe = document.createElement("iframe");
  iframe.src = gitbook.getFrameURL({
    visitor: { token: token },
  });
  const frame = gitbook.createFrame(iframe);

  document.getElementById("embed-container").appendChild(iframe);
  return frame;
}

initializeEmbed();
```

{% endtab %}

{% tab title="React 组件" %}
对于 React 应用，在文档站点登录创建访客令牌后有条件地渲染嵌入：

```jsx
import { useEffect, useState } from "react";
import { GitBookProvider, GitBookFrame } from "@gitbook/embed/react";

function App() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    // 检查 cookie 中的令牌
    const getCookie = (name) => {
      const value = `; ${document.cookie}`;
      const parts = value.split(`; ${name}=`);
      if (parts.length === 2) return parts.pop().split(";").shift();
    };

    const visitorToken = getCookie("gitbook-visitor-token");
    setToken(visitorToken);
  }, []);

  if (!token) {
    return (
      <div>
        <p>请登录以获取帮助。</p>
        <a href="https://docs.example.com">登录</a>
      </div>
    );
  }

  return (
    <GitBookProvider siteURL="https://docs.example.com">
      <YourAppContent />
      <GitBookFrame visitor={{ token: token }} />
    </GitBookProvider>
  );
}
```

{% endtab %}
{% endtabs %}

## 常见问题

* **使用身份提供方令牌** – 不要将 OIDC 访问令牌或 ID 令牌用作 `visitor.token`。在文档站点认证后，请使用 GitBook 颁发的 HS256 访客令牌。
* **在登录前加载嵌入** – 在加载脚本或组件之前，将首次访问者发送到文档站点完成登录。
* **令牌未在跨域之间持久保存** – 由于浏览器安全策略，cookie 不会在不同域之间持久保存。你的应用和文档必须位于同一域或子域，或者直接传递令牌。
* **令牌已过期** – 令牌可能过期。如果嵌入返回身份验证错误，请提示用户重新登录。
* **使用了错误的 cookie 名称** – 令牌存储为 `gitbook-visitor-token`，而不是 `gitbook-token` 或其他变体。
* **未将令牌传递给 init/getFrameURL** – 使用基于 cookie 的方法时，确保将令牌传递给 `GitBook('init', ..., { visitor: { token } })` 或 `getFrameURL({ visitor: { token } })`.

## 调试

要验证令牌是否存在，请打开浏览器控制台并运行：

```javascript
document.cookie.split(";").find((c) => c.includes("gitbook-visitor-token"));
```

如果这返回 `undefined`，则用户尚未登录你的文档。

## 下一步

* [自定义嵌入](/docs/documentation/zh/docs-site/embedding/configuration/customizing-docs-embed.md) – 添加欢迎消息和操作
* [创建自定义工具](/docs/documentation/zh/docs-site/embedding/configuration/creating-custom-tools.md) – 与你的产品 API 集成
* [Docs Embed 文档](/docs/documentation/zh/docs-site/embedding.md) – 完整嵌入指南


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/docs-site/embedding/using-with-authenticated-docs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.