> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证设置

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

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

  [Enterprise 方案](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. 选择 **保存更改**。
      </Step>

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

    ## 示例

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

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

  <Tab title="Mintlify 控制台">
    ### 先决条件

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

    ### 实施

    <Steps>
      <Step title="Enable Mintlify dashboard authentication.">
        1. 在控制台中前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
        2. 选择 **Full Authentication** 或 **Partial Authentication**。
        3. 选择 **Mintlify Auth**。
        4. 选择 **Enable Mintlify Auth**。
      </Step>

      <Step title="Add authorized users.">
        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="Configure your OAuth settings.">
        1. 在控制台中前往 [认证](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` 或类似参数，请将其指回你的文档 URL。

        4. 选择 **Save changes**。
      </Step>

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

      <Step title="Create your user info endpoint (optional).">
        为启用个性化功能，请创建一个 API 端点，该端点需：

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

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

    ### 示例

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

    ```json theme={null}
    {
      "content": {
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "groups": ["engineering", "admin"]
    }
    ```

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

  <Tab title="JWT（JSON Web Token）">
    ### 先决条件

    * 可生成并签署 JWT（JSON Web Token）的认证系统。
    * 可创建重定向 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. 将你的 key 安全存储在后端可访问的位置。
      </Step>

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

        * 按 `User` 格式创建一个包含已认证用户信息的 JWT。更多信息参见 [User data format](/zh/authentication-personalization/personalization-setup#user-data-format)。
        * 使用 EdDSA 算法与密钥签署该 JWT。
        * 创建一个重定向 URL，返回到文档的 `/login/jwt-callback` 路径，并将 JWT 作为 hash 附加在其中。
      </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 theme={null}
      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 theme={null}
      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，并带上重定向 query 参数：`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 Public page example theme={null}
---
title: "公开页面"
public: true
---
```

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

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

```json Public group example theme={null}
{
  "navigation": {
    "groups": [
      {
        "group": "公共组",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "私有组",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}
```