身份认证设置

通过用户认证来控制文档的隐私

专业版包含密码认证。

企业版包含所有认证方式。

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

​

认证模式

根据你的访问控制需求，在完整认证和部分认证两种模式中进行选择。

完整认证：所有页面均受保护。用户必须先登录才能访问任何内容。

部分认证：部分页面对公众可见，其他页面需要认证。用户可自由浏览公开内容，访问受保护页面时再进行认证。

在配置下方任一握手方式时，你需要在控制台设置中选择 完整认证 或 部分认证。

​

配置认证

选择要配置的握手方式。

密码

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

​

前提条件

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

​

实施

1. 创建密码

   1. 在仪表盘中前往 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 Password。
   4. 输入一个安全的密码。
   5. 选择 Save changes。
2. 分发访问权限

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

​

示例

你的文档托管在 docs.foo.com，你需要基础访问控制，但不追踪单个用户。你想阻止公开访问，同时保持设置简单。

在仪表盘中创建强密码，并将凭据分享给获授权的用户。就是这么简单！

Mintlify 控制台

​

前置条件

• 你的文档读者同时也是你的文档编辑者。

​

实施

1. 启用 Mintlify 仪表盘身份验证。

   1. 在仪表盘中，前往 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 Mintlify Auth。
   4. 选择 Enable Mintlify Auth。
2. 添加授权用户。

   1. 在仪表盘中，前往 Members。
   2. 添加每位需要访问你文档的成员。
   3. 根据其编辑权限分配合适的角色。

​

示例

你的文档托管在 docs.foo.com，团队使用仪表盘来编辑文档。你希望仅向团队成员开放访问。

在仪表盘设置中启用 Mintlify 身份验证。

通过检查所有团队成员是否已添加到你的组织来验证团队访问权限。

OAuth 2.0

​

先决条件

• 支持授权码流程（Authorization Code Flow）的 OAuth 或 OIDC 服务器。
• 能创建可由 OAuth 访问令牌访问的 API 端点（可选，用于启用个性化功能）。

​

实施

1. 配置你的 OAuth 设置。

   1. 在控制台进入 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 OAuth 并配置以下字段：

   • Authorization URL：你的 OAuth 授权端点。
   • Client ID：你的 OAuth 2.0 客户端标识符。
   • Client Secret：你的 OAuth 2.0 客户端密钥。
   • Scopes：请求的权限。请复制 scope 的“完整”字符串（例如，对于 provider.users.docs 这样的 scope，请复制完整的 provider.users.docs）。如需不同的访问级别，可使用多个 scope。
   • Token URL：你的 OAuth 令牌交换端点。
   • Info API URL（可选）：用于检索用户信息以实现个性化的端点。如果留空，OAuth 流程仅用于验证身份，用户信息将为空。
   • Logout URL：你的 OAuth 提供商的原生登出 URL。如果你的提供商有 returnTo 或类似参数，请将其指回你的文档地址。

   4. 选择 Save changes。
2. 配置你的 OAuth 服务器。

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

   为启用个性化功能，创建一个 API 端点，该端点需：

   • 接受 OAuth 访问令牌进行认证。
   • 以 User 格式返回用户数据。参见 User data format 了解更多信息。

   将该端点 URL 填入你的authentication settings中的 Info API URL 字段。

​

示例

你的文档托管在 foo.com/docs，并且在 auth.foo.com 上有一个现有的 OAuth 服务器，支持授权码流程。

在控制台中配置你的 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 访问令牌，并返回：

{
  "content": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "groups": ["工程团队", "管理员"]
}

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

JWT

​

先决条件

• 能生成并签署 JWT 的身份认证系统。
• 能创建重定向 URL 的后端服务。

​

实施

1. 生成私钥。

   1. 在你的控制台前往 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 JWT。
   4. 输入你现有登录流程的 URL，并选择 Save changes。
   5. 选择 Generate new key。
   6. 将密钥安全存储在后端可访问的位置。
2. 将 Mintlify 认证集成到你的登录流程中。

   在用户完成认证后，修改你现有的登录流程以包含以下步骤：

   • 生成一个包含已认证用户信息、符合 User 格式的 JWT。更多信息参见 User data format。
   • 使用 EdDSA 算法，用你的私钥签署该 JWT。
   • 创建一个返回到文档 /login/jwt-callback 路径的重定向 URL，并将 JWT 作为哈希附加。

​

示例

你的文档托管在 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 week session expiration
    groups: res.locals.user.groups,
    content: {
      firstName: res.locals.user.firstName,
      lastName: res.locals.user.lastName,
    },
  };

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

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

​

重定向未认证用户

当未认证用户尝试访问受保护页面时，其预期访问的目的地会在重定向到你的登录 URL 时被保留：

1. 用户尝试访问受保护页面：https://docs.foo.com/quickstart。
2. 重定向到你的登录 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。

公共页面示例

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

​

组级别

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

公共分组示例

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