カスタムバックエンドの設定

訪問者向けにカスタムのログイン画面を設定する

このガイドでは、ドキュメント用の保護されたサインイン画面の設定方法を説明します。このガイドを進める前に、まず最初に次のプロセスを実施していることを確認してください： 認証されたアクセスを有効化する.

このガイドは、独自の認証バックエンドを使用して GitBook ドキュメンテーションサイトの保護されたサインイン画面を設定する手順を案内します。 カスタム 認証バックエンド。

サポートされている認証プロバイダーのいずれかを使用している、または OpenID Connect （OIDC）準拠のバックエンドをお持ちの場合は、より簡潔なセットアップのために統合ガイドを参照してください： Auth0 | Azure AD | Okta | AWS Cognito | OIDC

概要

GitBook サイトのカスタム認証システムを設定するには、次の主要な手順に従ってください：

1

ユーザーを認証するカスタムバックエンドを作成する

ユーザーにログインを促し、認証を行うバックエンドを実装します。

2

JWT トークンに署名して GitBook に渡す

JWT トークンを作成し、サイトの秘密鍵で署名します。

3

フォールバック URL を設定する

認証されていない訪問者がサイトにアクセスしたときに使用される URL を設定します。

4

マルチテナント認証アクセスを設定する（オプション）

複数の GitBook サイトにまたがる認証を処理するようにバックエンドを設定します。

5

適応型コンテンツ用にバックエンドを設定する（オプション）

GitBook の適応型コンテンツと連携するようバックエンドを設定します。

1. ユーザーを認証するカスタムバックエンドを作成する

ドキュメントにアクセスする前にユーザーを認証するには、ログインとユーザー認証を処理できるサーバーを設定する必要があります。

バックエンドは次のことを行うべきです：

• 選択した認証方法を使ってユーザーにログインを促す。

• ユーザーの資格情報を検証し、認証する。

• 生成して署名する JSON Web Token（JWT） 認証が成功した際に。

• JWT を含めてユーザーを GitBook にリダイレクトする。

2. JWT トークンに署名して GitBook に渡す

バックエンドがユーザーを認証したら、 JWT を生成し および それを GitBook に渡す 際に リダイレクトして ください。トークンはサイトのオーディエンス設定に表示される 秘密鍵 を使用して署名する必要があります。 認証されたアクセスを有効化する.

次の例は、カスタムバックエンドのログインリクエストハンドラがどのように見えるかを示すはずです：

index.ts

import { Request, Response } from 'express';
import * as jose from 'jose';

import { getUserInfo } from '../services/user-info-service';
import { getFeatureFlags } from '../services/feature-flags-service';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';

export async function handleAppLoginRequest(req: Request, res: Response) {
    // ログインリクエストを処理するビジネスロジック
    // 例えば、資格情報の確認とユーザーの認証など
    //
    // 例：
    // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
    
    // 署名済み JWT を生成する
    const gitbookVisitorJWT = await new jose.SignJWT({})
        .setProtectedHeader({ alg: 'HS256' })
        .setIssuedAt()
        .setExpirationTime('2h') // 任意の 2 時間の有効期限
        .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
    // JWT トークンを URL に含めてユーザーを GitBook にリダイレクトする
    const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
    res.redirect(redirectURL);
}

3. フォールバック URL を設定する

フォールバック URL は、認証されていない訪問者が保護されたサイトにアクセスしようとしたときに使用されます。GitBook はその訪問者をこの URL にリダイレクトします。

この URL はカスタムバックエンド内のハンドラを指すべきで、そこでログインを促し、認証を行い、JWT を URL に含めて再びサイトにリダイレクトできます。

たとえば、ログイン画面が次の場所にある場合： https://example.com/login、この値をフォールバック URL として含めるべきです。

このフォールバック URL は、サイトのオーディエンス設定の「Authenticated access」タブ内で設定できます。

フォールバック URL を設定する

フォールバック URL にリダイレクトする際、GitBook は location というクエリパラメータをフォールバック URL に含めます。これをハンドラで利用してユーザーを元の場所にリダイレクトできます：

const gitbookVisitorJWT = await new jose.SignJWT({})
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h') // 任意の 2 時間の有効期限
    .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
// JWT を jwt_token クエリパラメータとして含めて元の GitBook ドキュメント URL にリダイレクトする
// location が提供されている場合、ユーザーは元の目的地にリダイレクトされます
const redirectURL = `${GITBOOK_DOCS_URL}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);

GitBook は location search パラメータに依存しているため、フォールバック URL でそれを使用することはできません。たとえば、 https://auth.gitbook.com/?location=something は有効なフォールバック URL ではありません。

4. マルチテナント認証アクセスを設定する（オプション）

GitBook をプラットフォームとして使用し、異なる顧客にコンテンツを提供している場合、マルチテナント認証アクセスを設定する必要があるでしょう。認証バックエンドは複数の異なるサイトにまたがる認証を処理する責任を負う必要があります。これはカスタム認証バックエンドのコードにいくつかの小さな変更を加えることで GitBook で可能です。

認証サーバーにすべてのテナントを追加すること

認証バックエンドは、処理する予定のすべての GitBook サイトの JWT 署名鍵と URL を知っている必要があります。組織に Customer A と Customer B の 2 つのサイトがある場合、認証コードはそのようなマッピングを保存することが考えられます：

const CUSTOMER_A = {
  jwtSigningKey: 'aaa-aaa-aaa-aaa',
  url: 'https://mycompany.gitbook.io/customer-a'
};

const CUSTOMER_B = {
  jwtSigningKey: 'bbb-bbb-bbb-bbb',
  url: 'https://mycompany.gitbook.io/customer-b'
};

認証サーバーに追加のコンテキストを提供すること

GitBook がユーザーのリクエストを認証できない場合、ユーザーをフォールバック URL にリダイレクトします。この URL は認証バックエンドを指し、そこでユーザーを認証して要求されたコンテンツに戻すリダイレクトを行う責任があります。

複数のテナントをサポートするには、認証バックエンドがユーザーがアクセスすべき GitBook サイトを知る必要があります。この情報はフォールバック URL に含めて渡すことができます。

例えば、各サイトのフォールバック URL を次のように設定できます：

GitBook サイト	フォールバック URL
Customer A サイト	https://auth-backend.acme.org/login?site=customer-a
Customer B サイト	https://auth-backend.acme.org/login?site=customer-b

認証バックエンドはこの情報をチェックし、それに応じて適切なサイトへのリダイレクトを処理できます：

const customerInfo = req.query.site === 'customer-a' ? CUSTOMER_A : CUSTOMER_B;
  
const gitbookVisitorJWT = await new jose.SignJWT({})
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('2h') // 任意の 2 時間の有効期限
    .sign(new TextEncoder().encode(customerInfo.jwtSigningKey));
    
// JWT を jwt_token クエリパラメータとして含めて元の GitBook ドキュメント URL にリダイレクトする
// location が提供されている場合、ユーザーは元の目的地にリダイレクトされます
const redirectURL = `${customerInfo.url}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);

5. 適応型コンテンツのためにバックエンドを設定する（オプション）

認証されたアクセス設定で Adaptive Content 機能を活用するには、カスタムバックエンドが生成する JWT のペイロードに追加のユーザー属性（クレーム）を含め、ユーザーをサイトにリダイレクトする際に URL に含めることができます。

これらのクレームは JWT に含められると、GitBook によって コンテンツを適応させる ために動的に使用されます。

まとめると、次のコード例はこれらのクレームを JWT に含め、それを GitBook が訪問者のためにコンテンツを適応させるために使用できる方法を示しています：

index.ts

import { Request, Response } from 'express';
import * as jose from 'jose';

import { getUserInfo } from '../services/user-info-service';
import { getFeatureFlags } from '../services/feature-flags-service';

const GITBOOK_VISITOR_SIGNING_KEY = process.env.GITBOOK_VISITOR_SIGNING_KEY!;
const GITBOOK_DOCS_URL = 'https://mycompany.gitbook.io/myspace';

export async function handleAppLoginRequest(req: Request, res: Response) {
    // ログインリクエストを処理するビジネスロジック
    // 例えば、資格情報の確認とユーザーの認証など
    //
    // 例：
    // const loggedInUser = await authenticateUser(req.body.username, req.body.password);
    
    // この例では、ログイン済みのユーザーオブジェクトを想定します
    const loggedInUser = { id: '12345' }; // 実際の認証ロジックに置き換えてください

    // GitBook に渡すためのユーザー情報を取得する
    const userInfo = await getUserInfo(loggedInUser.id);
    
    // 署名済み JWT を生成し、ユーザー属性をクレームとして含める
    const gitbookVisitorClaims = {
        firstName: userInfo.firstName,
        lastName: userInfo.lastName,
        isBetaUser: userInfo.isBetaUser,
        products: userInfo.products.map((product) => product.name),
        featureFlags: await getFeatureFlags({ userId: loggedInUser.id })
    };
    
    const gitbookVisitorJWT = await new jose.SignJWT(gitbookVisitorClaims)
        .setProtectedHeader({ alg: 'HS256' })
        .setIssuedAt()
        .setExpirationTime('2h') // 任意の 2 時間の有効期限
        .sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
    
    // JWT トークンを URL に含めてユーザーを GitBook にリダイレクトする
    const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
    res.redirect(redirectURL);
}

GitBook に送信するための適切なクレームを設定および構成したら、次に進むには「コンテンツの適応」に移動してサイトの設定を続けてください。