认证设置

通过用户认证来控制对文档的访问。

Pro 方案 包含密码认证。

Custom 方案 包含所有认证方式。

启用认证后，用户需先登录才能访问你的文档。

启用认证后，用户必须先登录才能访问任何内容。你可以将特定页面或分组配置为公开，而将其他页面设为受保护状态。

​

配置认证

选择要配置的握手方式。

密码

密码认证仅提供访问控制，不支持内容个性化。

​

前提条件

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

​

设置

1. 创建密码。

   1. 在控制台中，前往 Authentication。
   2. 启用认证。
   3. 在 Password Protection 部分输入一个安全的密码。

   输入密码后，你的网站会重新部署。部署完成后，任何访问你站点的用户都必须输入该密码才能访问你的内容。

2. 分发访问权限。

   以安全方式将密码和文档 URL 分享给获授权的用户。

​

示例

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

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

Mintlify 控制台

​

前提条件

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

​

设置

1. 在 Mintlify 控制台中启用认证。

   1. 在控制台中，前往 Authentication。
   2. 启用认证。
   3. 在 Custom Authentication 部分，点击 Mintlify Auth。
   4. 点击 Enable Mintlify Auth。

   启用 Mintlify 认证后，你的网站会重新部署。部署完成后，任何访问你网站的人都必须登录到你的 Mintlify 组织才能访问你的内容。

2. 添加授权用户。

   1. 在控制台中，前往 Members。
   2. 添加所有需要访问你文档的人员。
   3. 根据他们的编辑权限分配合适的角色。

​

示例

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

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

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

OAuth 2.0

​

前提条件

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

​

设置

1. 配置你的 OAuth 设置。

   1. 在控制台中前往 Authentication。
   2. 启用认证。
   3. 在 Custom Authentication 部分，点击 OAuth。
   4. 配置以下字段：

   • Authorization URL：你的 OAuth 端点。
   • Client ID：你的 OAuth 2.0 客户端标识符。
   • Client Secret：你的 OAuth 2.0 客户端密钥。
   • Scopes（可选）：要请求的权限。复制 完整的 scope 字符串（例如，对于 provider.users.docs 这样的 scope，复制完整的 provider.users.docs）。如果需要不同的访问级别，可以使用多个 scope。
   • Additional authorization parameters（可选）：要添加到初始授权请求中的其他 query 参数。
   • Token URL：你的 OAuth 令牌交换端点。
   • Info API URL（可选）：你服务器上的一个端点，Mintlify 会调用它来获取用户信息。对于基于用户组的访问控制是必填项。如果省略，OAuth 流程只会验证身份。
   • Logout URL（可选）：你的 OAuth 提供方自带的登出 URL。用户登出时，Mintlify 会使用 GET 请求将用户重定向到该 URL。Mintlify 不会追加 query 参数，因此请将任何参数（例如 returnTo）直接包含在 URL 中。配置一个页面，用于在成功登出后重定向用户。
   • Redirect URL（可选）：在认证完成后重定向用户的 URL。

   5. 点击 保存更改。

   配置完 OAuth 设置后，你的网站会重新部署。部署完成后，任何访问你站点的用户都必须登录到你的 OAuth 提供方才能访问内容。

2. 配置你的 OAuth 服务器。

   1. 从你的认证设置中复制 Redirect URL。
   2. 将该 Redirect URL 添加为 OAuth 服务器中授权的重定向 URL。
3. 创建用户信息端点（可选）。

   为启用基于用户组的访问控制，创建一个 API 端点，该端点需满足：

   • 响应 GET 请求。
   • 接受 Authorization: Bearer <access_token> 头部用于认证。
   • 以 User 格式返回用户数据。更多信息参见 User data format。

   Mintlify 使用 OAuth 访问令牌调用此端点以获取用户信息。不会发送额外的 query 参数。

   将此端点 URL 填入你认证设置中的 Info API URL 字段。

​

示例

你将文档托管在 foo.com/docs，并且你有一个现有的 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%2Ffoo.com%2Fdocs

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

{
  "groups": ["engineering", "admin"],
  "expiresAt": 1735689600
}

使用用户信息响应中的 expiresAt 字段控制会话时长。该字段为 Unix 时间戳（自纪元以来的秒数），用于指示会话何时过期。更多详情请参阅 用户数据格式。

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

JWT（JSON Web Token）

​

前置条件

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

​

设置

1. 生成私钥。

   1. 在控制台中前往 Authentication。
   2. 启用认证。
   3. 在 Custom Authentication 部分，点击 JWT。
   4. 输入你现有登录流程的 URL。
   5. 点击 Save changes（保存更改）。
   6. 点击 Generate new key（生成新密钥）。
   7. 将你的 key 安全存储在后端可以访问的位置。

   生成私钥后，你的网站会重新部署。部署完成后，任何访问你网站的人都必须登录到你的 JWT 认证系统才能访问你的内容。

2. 将 Mintlify 认证集成到你的登录流程中。

   修改你现有的登录流程，在用户通过认证后增加以下步骤：

   • 按 User 格式创建一个包含已认证用户信息的 JWT。更多信息参见 User data format。
   • 使用 EdDSA 算法，用你的密钥对 JWT 进行签名。
   • 创建一个返回到文档 /login/jwt-callback 路径的重定向 URL，并将 JWT 放在 URL 片段（hash）中。

​

示例

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

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

在验证用户凭据之后：

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

TypeScript

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

const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;

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

export async function handleRequest(req: Request, res: Response) {
  const user = {
    expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // 2 周会话过期时间
    groups: res.locals.user.groups,
  };

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

  return res.redirect(`https://docs.foo.com/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. 用户将进入其最初想要访问的页面。

​

公开页面

在使用认证时，所有页面默认都需要通过认证才能访问。你可以在页面或分组级别通过 public 属性将特定页面设置为无需认证即可访问。

​

单个页面

要将页面设为公开，请在该页面的 frontmatter 中添加 public: true。

Public page example

---
title: "公开页面"
public: true
---

​

页面分组

要将某个分组中的所有页面设为公开，请在 docs.json 的 navigation 对象中，该分组名称下添加 "public": true。

Public group example

{
  "navigation": {
    "groups": [
      {
        "group": "公开组",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "私有组",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}

​

使用 groups 控制访问

当你使用 OAuth 或 JWT（JSON Web Token）进行认证时，可以将特定页面仅限于某些用户组访问。若希望不同用户根据其角色或属性查看不同内容，这将非常有用。

通过在认证过程中传递的用户数据来管理 groups。详见 用户数据格式。

Example user info

{
  "groups": ["admin", "beta-users"],
  "expiresAt": 1735689600
}

使用 frontmatter 中的 groups 属性来指定哪些 groups 可以访问特定页面。

Example page restricted to the admin group

---
title: "管理员控制台"
groups: ["admin"]
---

用户必须至少属于所列的一个 groups 才能访问该页面。如果用户在不具备所需分组的情况下尝试访问页面，将会收到 404 错误。

​

groups 如何与公共页面配合使用

• 默认情况下，所有页面都需要认证。
• 具有 groups 属性的页面仅对属于这些 groups 的已认证用户可访问。
• 没有 groups 属性的页面对所有已认证用户可访问。
• 具有 public: true 且没有 groups 属性的页面对所有人可访问。

Public page

---
title: "Public guide"
public: true
---

​

用户数据格式

当使用 OAuth 或 JWT 认证时，系统会返回用户数据，用于控制会话时长以及基于用户组成员关系的访问控制。

Format

type User = {
  expiresAt?: number;
  groups?: string[];
};

expiresAt · number

会话过期时间，以自 epoch 起算的秒数表示。当当前时间超过该值时，用户必须重新完成认证。

对于 JWT： 这不同于 JWT 的 exp 声明，后者用于决定 JWT 何时被视为无效。出于安全考虑，应将 JWT 的 exp 声明设置为较短的时长（10 秒或更少）。使用 expiresAt 来表示实际会话时长（从数小时到数周）。

groups · string[]

用户所属用户组的列表。frontmatter 中带有匹配 groups 的页面对该用户可访问。

示例：具有 groups: ["admin", "engineering"] 的用户可以访问带有 admin 或 engineering 用户组标记的页面。