> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# 认证设置
> 通过用户认证来控制对文档的访问。
[Pro 方案](https://mintlify.com/pricing?ref=authentication) 包含密码认证。
[Custom 方案](https://mintlify.com/pricing?ref=authentication) 包含所有认证方式。
启用认证后，用户需先登录才能访问你的文档。
## 认证模式
根据你的访问控制需求，在完整认证和部分认证模式之间进行选择。
**完整认证**：所有页面均受保护。用户必须先登录才能访问任何内容。
**部分认证**：部分页面可公开查看，其他页面需要认证。用户可以自由浏览公开内容，访问受保护页面时再进行认证。
在配置下方任一握手机制时，你需要在控制台设置中选择 **完整认证** 或 **部分认证**。
## 配置认证
选择要配置的握手方式。
密码认证仅提供访问控制，且**不**支持内容个性化。
### 前提条件
* 你的安全策略允许在用户之间共享密码。
### 实施
1. 在你的控制台，前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
2. 选择 **Full Authentication** 或 **Partial Authentication**。
3. 选择 **Password**。
4. 输入一个强密码。
5. 选择 **保存更改**。
将密码和文档站点的 URL 安全地分享给获授权的用户。
### 示例
你的文档托管在 `docs.foo.com`，你需要基本的访问控制，但不跟踪单个用户。你想阻止公众访问，同时保持设置简单。
在控制台中**创建一个强密码**，并将**凭证**分享给获授权的用户。就这样！
### 先决条件
* 所有需要访问你文档的人都必须是你 Mintlify 组织的成员。
### 实施
1. 在控制台中，前往 [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication)。
2. 选择 **Full Authentication** 或 **Partial Authentication**。
3. 选择 **Mintlify Auth**。
4. 选择 **Enable Mintlify Auth**。
1. 在控制台中，前往 [Members](https://dashboard.mintlify.com/settings/organization/members)。
2. 将每位需要访问你文档的人添加为成员。
3. 根据其编辑权限分配合适的角色。
### 示例
你的文档托管在 `docs.foo.com`，且你的整个团队都可访问控制台。你希望仅限团队成员访问。
在控制台设置中**启用 Mintlify 认证**。
通过确认所有团队成员都已添加到你的组织来**验证团队访问权限**。
### 先决条件
* 支持 Authorization Code Flow 的 OAuth 或 OIDC 服务器。
* 具备创建可通过 OAuth 访问令牌访问的 API 端点的能力（可选，用于启用个性化功能）。
### 实施
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`）。如需不同的访问级别，可使用多个 scopes。
* **Token URL**：你的 OAuth 令牌交换端点。
* **Info API URL**（可选）：你服务器上的端点，Mintlify 会调用该端点以获取用于个性化的用户信息。若留空，OAuth 流程仅用于身份验证，用户信息将为空。
* **Logout URL**：你的 OAuth 提供商的原生登出 URL。若提供商支持 `returnTo` 或类似参数，请将其指回你的文档 URL。
4. 选择 **Save changes**。
1. 从你的[认证设置](https://dashboard.mintlify.com/settings/deployment/authentication)中复制 **Redirect URL**。
2. 将该重定向 URL 添加为你的 OAuth 服务器的已授权重定向 URL。
若要启用个性化功能，请创建一个 API 端点，该端点：
* 接受 OAuth 访问令牌进行认证。
* 按 `User` 格式返回用户数据。更多信息参见 [User data format](/zh/deploy/personalization-setup#user-data-format)。
将此端点的 URL 填入你的[认证设置](https://dashboard.mintlify.com/settings/deployment/authentication)中的 **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 访问令牌，并返回：
```json theme={null}
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**将你的 OAuth 服务器配置为允许重定向**到你的回调 URL。
### 先决条件
* 一个可以生成并签署 JWT 的认证系统。
* 一个可以创建重定向 URL 的后端服务。
### 实施
1. 在你的控制台，前往 [认证](https://dashboard.mintlify.com/settings/deployment/authentication)。
2. 选择 **完全认证（Full Authentication）** 或 **部分认证（Partial Authentication）**。
3. 选择 **JWT**。
4. 输入你现有登录流程的 URL，并选择 **保存更改（Save changes）**。
5. 选择 **生成新 key（Generate new key）**。
6. 将你的 key 安全存储在后端可访问的位置。
在用户通过认证后，修改你现有的登录流程以包含以下步骤：
* 创建一个包含已认证用户信息的 JWT，采用 `User` 格式。更多信息参见[用户数据格式](/zh/deploy/personalization-setup#user-data-format)。
* 使用你的私钥并采用 EdDSA 算法对 JWT 进行签名。
* 创建一个返回到文档 `/login/jwt-callback` 路径的重定向 URL，并将 JWT 作为 hash 附加其后。
### 示例
你的文档托管在 `docs.foo.com`，现有的认证系统在 `foo.com`。你希望扩展登录流程，在保持文档与控制台分离的同时授予对文档的访问权限（或你没有控制台）。
在 `https://foo.com/docs-login` 创建一个登录端点，以扩展你现有的认证。
在验证用户凭据后：
* 生成一个符合 Mintlify 格式、包含用户数据的 JWT。
* 对 JWT 进行签名并重定向至 `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`。
```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)
```
### 重定向未认证用户
当未认证用户尝试访问受保护页面时，其预期目的地会在重定向到你的登录 URL 时被保留：
1. 用户尝试访问受保护页面：`https://docs.foo.com/quickstart`。
2. 携带重定向 query 参数重定向到你的登录 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`。
```mdx Public page example theme={null}
---
title: "公开页面"
public: true
---
```
### 页面分组
要将某个分组中的所有页面设为公开，请在 `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"
]
}
]
}
}
```
## 使用 groups 控制访问
当你使用 OAuth 或 JWT（JSON Web Token）进行认证时，可以将特定页面仅限于某些用户组访问。若希望不同用户根据其角色或属性查看不同内容，这将非常有用。
groups 通过在认证过程中传递的用户数据进行管理。
```json Example user info highlight={2} theme={null}
{
"groups": ["admin", "beta-users"],
"content": {
"firstName": "Jane",
"lastName": "Doe"
}
}
```
使用 frontmatter 中的 `groups` 属性来指定哪些 groups 可以访问特定页面。
```mdx Example page restricted to the admin group highlight={3} theme={null}
---
title: "管理员控制台"
groups: ["admin"]
---
```
用户必须至少属于所列的一个 groups 才能访问该页面。如果用户在不具备所需分组的情况下尝试访问页面，将会收到 404 错误。
### 与认证模式的交互
groups 的行为会因认证模式不同而有所差异。
**完整认证（配合 groups）：**
* 所有页面都需要认证。
* 没有 `groups` 属性的页面对所有已认证用户可访问。
* 带有 `groups` 属性的页面仅对属于相应 groups 的已认证用户可访问。
**部分认证（配合 groups）：**
* 页面默认需要认证，除非你将其设为公开。
* 设置了 `public: true` 且没有 `groups` 的页面对所有人可访问。
* 带有 `groups` 的页面（无论是否设置 `public: true`）仅对属于相应 groups 的已认证用户可访问。
```mdx Anyone can view this page theme={null}
---
title: "公开指南"
public: true
---
```
````mdx Only authenticated users can view this page theme={null}
---
title: "API 参考"
---
```mdx 只有 pro 或 enterprise 组中的已认证用户可以查看此页面
---
title: "高级配置"
groups: ["pro", "enterprise"]
---
````