JWT 身份验证

如果您的产品已有自己的登录系统，JWT 身份验证可以让您使用该系统保护文档，而不必分发共享密码短语。登录用户点击进入文档时，您的后端会签发一个短期令牌。Jamdesk 验证令牌一次，创建会话，此后访客即可正常浏览。访客无需 Jamdesk 账户或共享密码。

这与密码保护有何不同

密码保护为每位访客提供相同的共享密码短语，适用于内部文档、暂存预览或单个合作伙伴群体。JWT 身份验证则按用户区分：每位访客的身份、会话时长和页面访问权限，都来自由您的后端签发的令牌。文档访问权限可以遵循现有的客户账户、套餐或角色，而不是使用一个共享密钥。

这两种模式互斥：auth.password 和 auth.jwt 不能同时启用。如果要从一种模式切换到另一种，请参阅下方的从密码保护迁移。

设置步骤

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Docs",
  "theme": "jam",
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*"]
    }
  }
}

git add docs.json
git commit -m "Turn on JWT authentication"
git push

集成登录流程

登录用户点击进入文档时，您的后端会签发 JWT，并将浏览器重定向到文档站点的回调 URL，同时将令牌放在 URL 片段中（# 后面）。片段永远不会出现在服务器日志或任何反向代理中，因为浏览器不会在请求中发送片段。

令牌必须使用 EdDSA 签名（Ed25519，与您在仪表板中生成的密钥匹配），其 exp 声明应设置为未来不超过约 10 秒的时间。这是握手窗口，而不是会话时长。实际会话时长由负载中的 expiresAt 字段单独控制（请参阅下方的负载参考）。

import { SignJWT, importPKCS8 } from "jose";

// Store this in your secret manager. It's the private key Jamdesk showed
// you once when you generated it in Project Settings.
const privateKey = await importPKCS8(process.env.JAMDESK_JWT_PRIVATE_KEY!, "EdDSA");

async function signDocsToken(user: { groups: string[] }) {
  return new SignJWT({
    host: "acme.jamdesk.app", // or your custom domain, e.g. "docs.example.com"
    expiresAt: Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 7, // 7-day session
    groups: user.groups,
    apiPlaygroundInputs: {
      header: { Authorization: `Bearer ${user.apiToken}` },
    },
  })
    .setProtectedHeader({ alg: "EdDSA" })
    .setExpirationTime("10s") // handshake window, not session length
    .sign(privateKey);
}

// In your "open docs" route/button handler:
app.get("/docs-login", requireAuth, async (req, res) => {
  const token = await signDocsToken(req.user);
  const redirect = req.query.redirect ?? "/";
  res.redirect(
    `https://acme.jamdesk.app/_jd/auth/callback?redirect=${encodeURIComponent(
      String(redirect)
    )}#${token}`
  );
});

import time
import jwt  # PyJWT >= 2.4, with the cryptography extra installed

with open("jamdesk_jwt_private_key.pem", "rb") as f:
    PRIVATE_KEY = f.read()

def sign_docs_token(user):
    payload = {
        "host": "acme.jamdesk.app",  # or your custom domain
        "exp": int(time.time()) + 10,  # handshake window, not session length
        "expiresAt": int(time.time()) + 60 * 60 * 24 * 7,  # 7-day session
        "groups": user.groups,
        "apiPlaygroundInputs": {
            "header": {"Authorization": f"Bearer {user.api_token}"},
        },
    }
    return jwt.encode(payload, PRIVATE_KEY, algorithm="EdDSA")

@app.route("/docs-login")
def docs_login():
    token = sign_docs_token(current_user)
    redirect_path = request.args.get("redirect", "/")
    return redirect(
        f"https://acme.jamdesk.app/_jd/auth/callback"
        f"?redirect={quote(redirect_path)}#{token}"
    )

重定向流程

1. 访客在没有有效会话的情况下请求受保护页面（例如 /quickstart）。Jamdesk 会将其重定向到 {loginUrl}?redirect=%2Fquickstart。
2. 您的登录流程对访客进行身份验证（使用您通常采用的方式），签发 JWT，并将其重定向到 https://<your-docs-host>/_jd/auth/callback?redirect=%2Fquickstart#<jwt>。
3. 回调页面在客户端从片段中读取令牌，并将其发送到 Jamdesk 的令牌交换端点。Jamdesk 验证签名和声明，成功后设置签名会话 Cookie。
4. 浏览器将访客重定向到原始目标 /quickstart，此时已拥有有效会话。redirect 值会在整个流程中保留，因此访客会准确返回最初访问的位置。

如果您的后端无法确定 redirect 值（例如有人直接将登录页面加入书签），请省略该值，Jamdesk 会回退到 /。

公开页面

某些页面应保持无需登录即可访问，例如状态页面或公开的更新日志。有三种方式可以将页面标记为公开，最终都会合并到一个允许列表中：

Frontmatter，一次设置一个页面：

---
title: Changelog
public: true
---

导航群组，设置整个分区：

{
  "navigation": {
    "groups": [
      { "group": "Changelog", "public": true, "pages": ["changelog"] }
    ]
  }
}

显式 glob，位于 auth.jwt.public[] 下：

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/*", "/status"]
    }
  }
}

基于群组的访问

某些页面可能只应对特定的已认证用户可见，例如管理员操作手册或仅供企业用户使用的参考文档。请将 groups 添加到页面的 frontmatter 中：

---
title: Admin API Keys
groups: ["admin"]
---

访客的会话会携带后端放入 JWT 负载中的 groups 数组。如果页面声明了 groups，而访客会话中的群组与该列表没有交集，访客会收到 404，而不是 401 或解锁屏幕。这是有意设计的：受群组限制的页面不会向群组外用户透露其存在。

以下细节会影响您对 groups 的使用：

• 群组页面会从站点地图、搜索、AI 聊天和 MCP 中排除，即使用户属于该群组也是如此。这些发现入口的排除是构建时决定的，而不是针对单个访客的决定。admin 群组成员仍可直接打开 /admin/api-keys（通过 URL 或内部链接），但该页面不会出现在搜索结果、聊天回答或 llms.txt 中。如果您需要让受限页面可被其目标用户发现，请从该用户已经能够访问的其他页面链接到它。
• 空的 groups: [] 表示完全不限制，而不是“无人可见”。要移除页面的群组限制，请完全删除 groups 字段，而不是将其设置为空数组。
• 如果要限制任何人访问某个页面，请取消发布该页面。没有任何 groups 值表示“无人可见”：群组成员资格是累加的，只要存在交集即可授予访问权限。
• 本地化副本会自动继承基础页面的 groups，除非翻译页面在其 frontmatter 中声明了自己的 groups。翻译受限页面不会意外变为公开页面。
• 请保持群组名称简短。群组会存储在会话 Cookie 中：每个会话最多 32 个群组，每个群组最多 64 个字符。超过任一限制时，Jamdesk 不会截断列表，而是以 401 拒绝整个令牌，不授予会话。

API 调试器预填充

如果您的文档包含 API 调试器，可以为已登录访客预填充内容，使其无需粘贴自己的 API 密钥。在 JWT 负载中加入 apiPlaygroundInputs：

{
  "host": "acme.jamdesk.app",
  "apiPlaygroundInputs": {
    "header": { "Authorization": "Bearer sk_live_user_specific_token" },
    "query": { "org_id": "acme-corp" },
    "path": { "workspace_id": "ws_123" }
  }
}

• header.Authorization 会预填充调试器的身份验证字段。如果存在 Bearer 前缀，系统会自动将其移除。
• query 和 path 会预填充当前端点中名称匹配的参数。
• 不支持 server 和 cookie 部分。系统只会应用 header、query 和 path。
• 预填充绝不会覆盖访客已经在调试器中输入的值。

负载参考

登出

已登录访客会在文档页眉中看到 Log out 链接。该链接会将其发送到 /_jd/auth/logout，清除会话 Cookie，并重定向到您的 loginUrl。如果您希望在自己的应用其他位置提供“退出文档”链接，也可以直接链接到该地址。这是一个不需要请求正文或请求标头的普通 GET 请求。

身份验证下的功能行为

故障排除

安全提示

apiPlaygroundInputs（包括您放入其中的任何 Authorization 值）可由文档站点上运行的 JavaScript 读取，读取入口是为调试器预填充提供支持的会话信息端点。预填充很方便，但不适合存放高权限密钥。

请发送权限最小化且仅限于该访客允许执行操作的用户凭据，绝不要发送组织范围的管理员密钥。请将放入 apiPlaygroundInputs 的任何内容视为对浏览文档的用户可见，因为它确实可见。

从密码保护迁移

从共享密码切换到 JWT 身份验证无需停机，网站会始终保持受保护状态。请按以下顺序操作：

{
  "auth": {
    "password": { "enabled": false },
    "jwt": { "enabled": true, "loginUrl": "https://app.example.com/docs-login" }
  }
}

接下来做什么？