认证设置

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

Pro 方案 包含密码认证。

Enterprise 方案 支持所有认证方式。

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

​

认证模式

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

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

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

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

​

配置认证

选择要配置的握手方式。

密码

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

​

前提条件

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

​

实施

1. 创建密码。

   1. 在你的控制台中，前往 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 Password。
   4. 输入一个强密码。
   5. 选择 保存更改。
2. 分发访问权限。

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

​

示例

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

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

Mintlify 控制台

​

先决条件

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

​

实施

1. Enable Mintlify dashboard authentication.

   1. 在控制台中前往 Authentication。
   2. 选择 Full Authentication 或 Partial Authentication。
   3. 选择 Mintlify Auth。
   4. 选择 Enable Mintlify Auth。
2. Add authorized users.

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

​

示例

你的文档托管在 docs.foo.com，团队通过控制台编辑文档。你希望仅限团队成员访问。

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

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

OAuth 2.0

​

先决条件

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

​

实施

1. Configure your OAuth settings.

   1. 在控制台中前往 认证。
   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 或类似参数，请将其指回你的文档 URL。

   4. 选择 Save changes。
2. Configure your OAuth server.

   1. 从认证设置中复制 Redirect URL。
   2. 将该重定向 URL 添加为 OAuth 服务器的授权重定向 URL。
3. Create your user info endpoint (optional).

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

   • 接受 OAuth 访问令牌进行认证。
   • 以 User 格式返回用户数据。详见 User data format。

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

​

示例

你的文档托管在 foo.com/docs，并且你在 auth.foo.com 上已有一个支持 Authorization Code Flow 的 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": ["engineering", "admin"]
}

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

JWT（JSON Web Token）

​

先决条件

• 可生成并签署 JWT（JSON Web Token）的认证系统。
• 可创建重定向 URL 的后端服务。

​

实施

1. 生成私钥。

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

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

   • 按 User 格式创建一个包含已认证用户信息的 JWT。更多信息参见 User data format。
   • 使用 EdDSA 算法与密钥签署该 JWT。
   • 创建一个重定向 URL，返回到文档的 /login/jwt-callback 路径，并将 JWT 作为 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 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，并带上重定向 query 参数：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"
        ]
      }
    ]
  }
}