#### 使用 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 %}
#### 使用 GitBook 的登出端点
如果你想在已发布的站点上提供一个登出链接，请链接到 `/~gitbook/auth/logout`.
此端点会将访客从其 GitBook 会话中注销。
### 4. 设置多租户已认证访问（可选）
如果你将 GitBook 作为一个平台向不同客户提供内容，那么你很可能需要设置多租户已认证访问。你的认证后端需要负责处理跨多个不同站点的认证。通过对自定义认证后端代码进行一些小调整，这在 GitBook 中是可行的。
#### 将所有租户添加到你的认证服务器
你的认证后端需要知道它预计要处理的所有 GitBook 站点的 JWT 签名密钥和 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 负载中包含额外的用户属性（声明），并在将用户重定向到站点时将其包含在 URL 中。
当这些声明包含在 JWT 中时，GitBook 会使用它们来 [自适应内容](/docs/documentation/zh/fa-bu/adaptive-content/adapting-your-content.md) 为你的站点访客动态调整。
综合起来，下面的代码示例演示了你可以如何在 JWT 中包含这些声明，之后 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，并将用户属性作为声明包含其中
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));
// 使用 URL 中的 JWT 令牌将用户重定向到 GitBook
const redirectURL = `${GITBOOK_DOCS_URL}/?jwt_token=${gitbookVisitorJWT}`;
res.redirect(redirectURL);
}
```
{% endcode %}
在完成设置并配置要发送给 GitBook 的正确声明后，前往“[自适应你的内容](/docs/documentation/zh/fa-bu/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 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/fa-bu/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 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.
