# 認証

GitBook のドキュメントで認証が必要な場合（例: OIDC、Auth0、またはカスタムバックエンドによる訪問者認証）、ユーザーの認証トークンが提供されない限り、埋め込みはドキュメントの内容にアクセスできません。

アプローチは 2 つあります:

1. **トークンを直接渡す** （推奨）- 訪問者トークンで埋め込みを初期化する
2. **Cookie ベースの検出を使用する** - 読み込み前に Cookie 内のトークンを確認する

## アプローチ 1: トークンを直接渡す（推奨）

埋め込みを初期化する際に、訪問者トークンを直接渡します:

{% 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" %}
Embed config API は変更されていません。署名付きの訪問者トークンは次のように渡します `visitor.token`.

認証済みサイトでは、GitBook はこのトークンを次のようにサイトへ転送します `jwt_token` iframe/script の URL に。認証済みサイトからスタンドアロンのスクリプトを読み込む場合は、\<script src> URL にこれを含める必要があります。 `jwt_token` を `<script src>` URL。
{% 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] 先にドキュメントへサインインしてください。");
      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 %}

#### 代替案: ユーザーにサインインを促す

トークンがない場合は、ユーザーにサインインを促せます:

```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 %}

## よくある落とし穴

* **サインイン前に埋め込みを読み込む** – スクリプトやコンポーネントを読み込む前に必ずトークンを確認するか、初期化時にトークンを直接渡してください。
* **トークンがドメイン間で保持されない** – ブラウザのセキュリティポリシーにより、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`を返す場合、ユーザーはまだドキュメントにサインインしていません。

## 次のステップ

* [Embed のカスタマイズ](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding/configuration/customizing-docs-embed) – ウェルカムメッセージとアクションを追加する
* [カスタムツールの作成](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding/configuration/creating-custom-tools) – 製品 API と統合する
* [Docs Embed のドキュメント](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding) – 完全な埋め込みガイド