#### 使用 GitBook 的登录端点
如果你想在已发布的网站上放置一个登录链接，请链接到 `/~gitbook/auth/login`.
此端点会将访客重定向到为该站点配置的身份验证后端。它还会添加一个 `location` 与他们开始访问的页面相匹配的查询参数。
这对于页眉链接和其他入口点很有用，你希望在登录后将访客送回同一页面。
在重定向到登录 URL 时，GitBook 会包含一个 `location` 传递给登录 URL 的查询参数，你可以在处理程序中利用它将用户重定向回其原始位置：
```javascript
const gitbookVisitorJWT = await new jose.SignJWT({})
.setProtectedHeader({ alg: 'HS256' })
.setIssuedAt()
.setExpirationTime('2h') // 任意的 2 小时过期时间
.sign(new TextEncoder().encode(GITBOOK_VISITOR_SIGNING_KEY));
// 重定向到原始的 GitBook 文档 URL，并将 JWT 作为 jwt_token 查询参数包含在内
// 如果提供了 location，用户将被重定向回其原始目标位置
const redirectURL = `${GITBOOK_DOCS_URL}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
```
{% hint style="warning" %}
因为 GitBook 依赖于 `location` search 参数——所以你不能在登录 URL 中使用它。例如， `https://auth.gitbook.com/?location=something` 不是一个有效的登录 URL。
{% endhint %}
#### 重定向 MCP 授权请求
当访客连接到 [MCP 服务器](/docs/documentation/zh/ai-for-your-readers/mcp-servers-for-published-docs.md) 你的已发布文档时，GitBook 会将他们重定向到你的身份验证后端。该重定向包含一个 `location` 参数，其中包含 MCP 授权端点的路径，该路径携带一个 `gb_oauth_state` 值，如下所示：
```
~gitbook/oauth2/v1//authorize?gb_oauth_state=
```
你的后端应使用此路径构建最终重定向回 GitBook 站点的 URL。
GitBook 会根据你站点的配置，从以下两个端点之一启动此流程：
* `~gitbook/mcp/auth` 用于启用了自适应内容的部分认证站点。
* `~gitbook/mcp` 用于使用身份验证访问的站点。
一旦你的后端对访客完成身份验证，就通过追加以下内容来构建返回 URL： `location` 将该路径添加到你的 GitBook 站点基础 URL。保留 `gb_oauth_state` 查询参数不变，并添加一个 `jwt_token=` 参数，其中包含你后端生成的已签名 JWT。
你的后端重定向访客所到达的最终 URL 应如下所示：
```
https:///~gitbook/oauth2/v1//authorize?gb_oauth_state=&jwt_token=
```
#### 使用 GitBook 的登出端点
如果你想在已发布的网站上放置一个登出链接，请链接到 `/~gitbook/auth/logout`.
此端点会将访客从其 GitBook 会话中登出。
### 4. 设置多租户身份验证访问（可选）
如果你将 GitBook 用作向不同客户提供内容的平台，那么你可能需要设置多租户身份验证访问。你的身份验证后端需要负责处理跨多个不同站点的身份验证。在 GitBook 中，只需对你的自定义身份验证后端代码做一些小调整即可实现。
#### 将所有租户添加到你的身份验证服务器
你的身份验证后端需要知道 JWT 签名密钥以及它需要处理的所有 GitBook 站点的 URL。如果你的组织中有两个站点分别对应 Customer A 和 Customer B，你可以想象你的身份验证代码这样存储映射：
```typescript
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：
然后你的身份验证后端可以检查此信息，并据此处理重定向到正确的站点：
```javascript
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));
// 重定向到原始的 GitBook 文档 URL，并将 JWT 作为 jwt_token 查询参数包含在内
// 如果提供了 location，用户将被重定向回其原始目标位置
const redirectURL = `${customerInfo.url}/${req.query.location || ''}?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
```
### 5. 为自适应内容配置你的后端（可选）
要在身份验证访问设置中利用自适应内容功能，你可以在自定义后端生成的 JWT 负载中包含额外的用户属性（claims），并在将用户重定向到站点时将其包含在 URL 中。
当这些 claims 包含在 JWT 中时，GitBook 会用它们来 [自适应内容](/docs/documentation/zh/publish/adaptive-content/adapting-your-content.md) 为你的站点访客动态调整内容。
将以上内容整合起来，下面的代码示例展示了你如何在 JWT 中包含这些 claims，随后 GitBook 可使用它们为你的访客调整内容：
{% code title="index.ts" %}
```typescript
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，并将用户属性作为 claims 包含在内
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));
// 将用户重定向到 GitBook，并在 URL 中包含 JWT 令牌
const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
}
```
{% endcode %}
在设置并配置好要发送给 GitBook 的正确 claims 后，前往“[调整你的内容](/docs/documentation/zh/publish/adaptive-content/adapting-your-content.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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-a-custom-backend.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
