认证设置

• 你的安全策略允许在多个用户之间共享密码。

你将文档托管在 docs.foo.com，只需要基础访问控制，而不需要跟踪单个用户。你希望阻止公众访问，同时保持设置简单。

在控制台中创建一个强密码，并将凭证分享给获授权的用户。

• 所有需要访问你站点的人都必须是你 Mintlify 组织的成员。

你将文档托管在 docs.foo.com，并且整个团队都能访问你的控制台。你希望仅将访问权限限制在团队成员。

在控制台设置中启用私有认证。

通过检查所有团队成员在你的组织中是否为激活状态来验证团队访问权限。

• 支持 Authorization Code Flow (授权码流程) 的 OAuth 或 OIDC 服务器。
• 能够创建可通过 OAuth 访问令牌访问的 API 端点 (可选，用于启用基于用户组的访问控制) 。

如果你的身份提供方在 ID 令牌或访问令牌中包含用户组信息，你可以使用这些声明来代替 Info API URL。此选项适用于使用客户端密钥的 OAuth 配置。

为部署配置 OAuth 令牌声明时，可以使用以下值：

{
  "source": "id_token",
  "groupsClaim": "groups",
  "groupsDelimiter": ","
}

• source：选择 id_token 或 access_token。如果选择 id_token，请在 OAuth scopes 中包含 openid。
• groupsClaim：指定包含用户组的令牌声明。默认值为 groups。
• groupsDelimiter：可选的分隔符，长度为 1 至 4 个字符。Mintlify 仅使用它来拆分字符串类型的声明值。

例如，当 "groups": "general,clienta_eur" 且 groupsDelimiter 设置为 "," 时，Mintlify 会将 general 和 clienta_eur 作为两个独立的用户组。Mintlify 会删除每个用户组两侧的空格，并忽略空片段。

不设置 groupsDelimiter 时，整个字符串会被视为一个用户组。数组类型的声明始终将每个字符串元素视为一个用户组，不会进行拆分。

当分隔符可能出现在用户组名称中时，请不要设置 groupsDelimiter。

你将文档托管在 docs.foo.com，并且你有一个现有的 OAuth 服务器 auth.foo.com，它支持 Authorization Code Flow。

在控制台中配置你的 OAuth 服务器详细信息：

• Authorization URL：https://auth.foo.com/authorization
• Client ID：ydybo4SD8PR73vzWWd6S0ObH
• Scopes：['provider.users.docs']
• Token URL：https://auth.foo.com/exchange
• Info API URL：https://api.foo.com/docs/user-info
• Logout URL：https://auth.foo.com/logout?returnTo=https%3A%2F%2Fdocs.foo.com

在 api.foo.com/docs/user-info 上创建一个用户信息端点，该端点要求使用带有 provider.users.docs scope 的 OAuth 访问令牌，并返回：

{
  "groups": ["engineering", "admin"],
  "expiresAt": 1893456000,
  "apiPlaygroundInputs": {
    "header": {
      "Authorization": "Bearer user_abc123"
    }
  }
}

将你的 OAuth 服务器配置为允许重定向到回调 URL。

• 一个可以生成并签名 JWT 的认证系统。
• 一个可以创建重定向 URL 的后端服务。

当 JWT 认证只配置一个登录 URL 时，未认证的访客会自动重定向到该 URL。如果配置了两个或更多命名的登录 URL，访客会先看到一个选择页面，然后再进入所选的登录流程。Mintlify 会转发经过校验的 redirect 参数，使访客能够返回到他们最初请求的文档页面。

你在 docs.foo.com 上托管文档，并在 foo.com 上已有认证系统。你希望扩展登录流程，在保持文档与控制台分离的同时，为文档授予访问权限 (或者如果你没有控制台，则直接为文档授予访问权限) 。

在 https://foo.com/docs-login 创建一个登录端点，用于扩展你现有的认证逻辑。

在验证用户凭据之后：

• 按 Mintlify 的格式生成包含用户数据的 JWT。
• 对 JWT 进行签名并重定向到 https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}。

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

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const DOCS_HOST = 'docs.example.com';

const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');

export async function handleRequest(req: Request, res: Response) {
  const user = {
    host: DOCS_HOST, // 必须与你的文档 URL 匹配
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 周会话过期时间
    groups: res.locals.user.groups,
    apiPlaygroundInputs: {
      header: {
        "Authorization": `Bearer ${res.locals.user.apiKey}`,
      },
    },
  };

  const jwt = await new jose.SignJWT(user)
    .setProtectedHeader({ alg: 'EdDSA' })
    .setExpirationTime('10 s') // JWT 10 秒后过期
    .sign(signingKey);

  return res.redirect(`https://${DOCS_HOST}/login/jwt-callback#${jwt}`);
}

当未认证用户尝试访问受保护页面时，系统在重定向到你的登录 URL 时会保留用户的目标地址。

1. 用户尝试访问受保护页面：https://docs.foo.com/quickstart。
2. 重定向到带有 redirect 查询参数的登录 URL：https://foo.com/docs-login?redirect=%2Fquickstart。
3. 认证完成后，重定向到 https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}。
4. 用户将进入其最初想要访问的页面。