> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份认证设置

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

<Info>
  [专业版](https://mintlify.com/pricing?ref=authentication)包含密码认证。

  [企业版](https://mintlify.com/pricing?ref=authentication)包含所有认证方式。
</Info>

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

<div id="authentication-modes">
  ## 认证模式
</div>

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

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

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

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

<div id="configuring-authentication">
  ## 配置认证
</div>

选择要配置的握手方式。

<Tabs>
  <Tab title="密码">
    <Info>
      密码认证仅用于访问控制，**不**支持内容个性化。
    </Info>

    ### 前提条件

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

    ### 实施

    <Steps>
      <Step title="创建密码">
        1. 在仪表盘中前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
        2. 选择 **Full Authentication** 或 **Partial Authentication**。
        3. 选择 **Password**。
        4. 输入一个安全的密码。
        5. 选择 **Save changes**。
      </Step>

      <Step title="分发访问权限">
        将密码和文档 URL 以安全方式分享给获授权的用户。
      </Step>
    </Steps>

    ## 示例

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

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

  <Tab title="Mintlify 控制台">
    ### 前置条件

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

    ### 实施

    <Steps>
      <Step title="启用 Mintlify 仪表盘身份验证。">
        1. 在仪表盘中，前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
        2. 选择 **Full Authentication** 或 **Partial Authentication**。
        3. 选择 **Mintlify Auth**。
        4. 选择 **Enable Mintlify Auth**。
      </Step>

      <Step title="添加授权用户。">
        1. 在仪表盘中，前往 [Members](https://dashboard.mintlify.com/settings/organization/members)。
        2. 添加每位需要访问你文档的成员。
        3. 根据其编辑权限分配合适的角色。
      </Step>
    </Steps>

    ### 示例

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

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

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

  <Tab title="OAuth 2.0">
    ### 先决条件

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

    ### 实施

    <Steps>
      <Step title="配置你的 OAuth 设置。">
        1. 在控制台进入 [Authentication](https://dashboard.mintlify.com/settings/deployment/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**。
      </Step>

      <Step title="配置你的 OAuth 服务器。">
        1. 从你的[authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication)复制 **Redirect URL**。
        2. 将该 Redirect URL 添加为你的 OAuth 服务器的授权重定向 URL。
      </Step>

      <Step title="创建用户信息端点（可选）。">
        为启用个性化功能，创建一个 API 端点，该端点需：

        * 接受 OAuth 访问令牌进行认证。
        * 以 `User` 格式返回用户数据。参见 [User data format](/zh/authentication-personalization/personalization-setup#user-data-format) 了解更多信息。

        将该端点 URL 填入你的[authentication settings](https://dashboard.mintlify.com/settings/deployment/authentication)中的 **Info API URL** 字段。
      </Step>
    </Steps>

    ### 示例

    你的文档托管在 `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 访问令牌，并返回：

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

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

  <Tab title="JWT">
    ### 先决条件

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

    ### 实施

    <Steps>
      <Step title="生成私钥。">
        1. 在你的控制台前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
        2. 选择 **Full Authentication** 或 **Partial Authentication**。
        3. 选择 **JWT**。
        4. 输入你现有登录流程的 URL，并选择 **Save changes**。
        5. 选择 **Generate new key**。
        6. 将密钥安全存储在后端可访问的位置。
      </Step>

      <Step title="将 Mintlify 认证集成到你的登录流程中。">
        在用户完成认证后，修改你现有的登录流程以包含以下步骤：

        * 生成一个包含已认证用户信息、符合 `User` 格式的 JWT。更多信息参见 [User data format](/zh/authentication-personalization/personalization-setup#user-data-format)。
        * 使用 EdDSA 算法，用你的私钥签署该 JWT。
        * 创建一个返回到文档 `/login/jwt-callback` 路径的重定向 URL，并将 JWT 作为哈希附加。
      </Step>
    </Steps>

    ### 示例

    你的文档托管在 `docs.foo.com`，现有的认证系统在 `foo.com`。你希望扩展登录流程，在保持文档与控制台分离的同时授予对文档的访问权限（或者你没有控制台）。

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

    在验证用户凭证后：

    * 以 Mintlify 的格式生成包含用户数据的 JWT。
    * 签署该 JWT，并重定向到 `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`。

    <CodeGroup>
      ```ts 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}`);
      }
      ```

      ```python Python
      import jwt # pyjwt
      import os

      from datetime import datetime, timedelta
      from fastapi.responses import RedirectResponse

      private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')

      @router.get('/auth')
      async def return_mintlify_auth_status(current_user):
        jwt_token = jwt.encode(
          payload={
            'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()),    # 10 second JWT expiration
            'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
            'groups': ['admin'] if current_user.is_admin else [],
            'content': {
              'firstName': current_user.first_name,
              'lastName': current_user.last_name,
            },
          },
          key=private_key,
          algorithm='EdDSA'
        )

        return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
      ```
    </CodeGroup>

    ### 重定向未认证用户

    当未认证用户尝试访问受保护页面时，其预期访问的目的地会在重定向到你的登录 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. 用户进入其原始目的地。
  </Tab>
</Tabs>

<div id="making-pages-public">
  ## 将页面设为公开
</div>

在使用部分认证时，所有页面默认受保护。你可以在页面或分组级别通过 `public` 属性，使特定页面在无需认证的情况下可见。

<div id="page-level">
  ### 页面级
</div>

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

```mdx 公共页面示例
---
title: "公开页面"
public: true
---
```

<div id="group-level">
  ### 组级别
</div>

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

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