启用认证后,用户需先登录才能访问你的文档。
启用认证后,用户必须先登录才能访问任何内容。你可以将特定页面或分组配置为公开,而将其他页面设为受保护状态。
认证仅适用于托管在自定义域名或 Mintlify 子域名上的站点。例如,docs.example.com 或 example.mintlify.site。使用自定义子路径 的站点不支持 认证。例如,example.com/docs。
使用下方对比表来选择适合你使用场景的认证方式。请参见功能可用性 了解每种方式如何与其他 Mintlify 功能协同工作。
密码
私有认证
OAuth 2.0
JWT(JSON Web Token)
密码认证仅提供访问控制,不 支持用户级功能,例如基于用户组的访问控制或 API 操作台中的预填数据。
密码前提条件 密码设置
创建密码。
在控制台中,前往 Authentication 。
在 Authentication method 部分,将站点可见性设置为 Private 。
点击 Password 。
输入一个安全的密码。
点击 Save changes 。
保存后,你的网站会重新部署。部署完成后,任何访问你站点的用户都必须输入该密码才能访问你的内容。
分发访问权限。
以安全方式将密码和文档 URL 分享给获授权的用户。
密码示例 你将文档托管在 docs.foo.com,只需要基础访问控制,而不需要跟踪单个用户。你希望阻止公众访问,同时保持设置简单。 在控制台中创建一个强密码 ,并将凭证分享 给获授权的用户。 私有认证前提条件
所有需要访问你站点的人都必须是你 Mintlify 组织的成员。
私有认证设置
启用私有认证。
在控制台中,前往 Authentication 。
在 Authentication method 部分,将站点可见性设置为 Private 。
点击 Authenticated 。
点击 Save changes 。
保存后,你的网站会重新部署。部署完成后,任何访问你网站的人都必须登录到你的 Mintlify 组织才能访问你的内容。
添加授权用户。
在控制台中,前往 Members 。
添加所有需要访问你文档的人员。
根据他们的编辑权限分配合适的角色。
私有认证示例 你将文档托管在 docs.foo.com,并且整个团队都能访问你的控制台。你希望仅将访问权限限制在团队成员。 在控制台设置中启用私有认证 。 通过检查所有团队成员在你的组织中是否为激活状态来验证团队访问权限 。 OAuth 2.0 前提条件
支持 Authorization Code Flow (授权码流程) 的 OAuth 或 OIDC 服务器。
对于基于用户组的访问控制,需要一个能在 id_token 或 access_token 中返回 groups 的 OAuth 或 OIDC 服务器,或者能够创建可通过 OAuth 访问令牌访问的 API 端点。
OAuth 2.0 设置
配置你的 OAuth 设置。
在控制台中前往 Authentication 。
在 Authentication method 部分,将站点可见性设置为 Private 。
点击 Custom 。
点击 OAuth 。
配置以下字段:
Authorization URL :你的 OAuth 端点。
Client ID :你的 OAuth 2.0 客户端标识符。
Client Secret :你的 OAuth 2.0 客户端密钥。
Scopes (可选) :要请求的权限。复制 完整的 scope 字符串 (例如,对于 provider.users.docs 这样的 scope,复制完整的 provider.users.docs) 。如果需要不同的访问级别,可以使用多个 scope。
Additional authorization parameters (可选) :要添加到初始授权请求中的其他 query 参数。
Token URL :你的 OAuth 令牌交换端点。
Token claims (可选) :直接从你的 token 端点返回的 JWT 中派生用户组,而无需再单独托管一个用户信息端点。参见从 token claims 派生 groups 。
Info API URL (可选) :你服务器上的一个端点,Mintlify 会调用它来获取用户信息。如果你的提供方不在 id_token 或 access_token 中返回 groups,可将此端点用于基于用户组的访问控制。如果同时省略 Token claims 和 Info API URL ,OAuth 流程只会验证身份。
Logout URL (可选) :你的 OAuth 提供方自带的登出 URL。用户登出时,Mintlify 会将登出重定向与该配置的 URL 进行校验,以确保安全性。只有当重定向地址与配置的 logoutUrl 完全匹配时,重定向才会成功。如果你未配置登出 URL,用户会被重定向到 /login。Mintlify 会使用 GET 请求重定向用户,并且不会追加任何 query 参数,因此请将所有参数 (例如 returnTo) 直接包含在 URL 中。
Redirect URL (可选) :在认证完成后重定向用户的 URL。
点击 Save changes 。
配置完 OAuth 设置后,你的网站会重新部署。部署完成后,任何访问你站点的用户都必须登录到你的 OAuth 提供方才能访问内容。
配置你的 OAuth 服务器。
从你的认证设置 中复制 Redirect URL 。
将该 Redirect URL 添加为 OAuth 服务器中授权的重定向 URL。
创建用户信息端点(可选)。
为启用基于用户组的访问控制,创建一个 API 端点,该端点需满足:
响应 GET 请求。
接受 Authorization: Bearer <access_token> 头部用于认证。
以 User 格式返回用户数据。更多信息参见 User data format 。
Mintlify 使用 OAuth 访问令牌调用此端点以获取用户信息。不会发送额外的 query 参数。 将此端点 URL 填入你认证设置 中的 Info API URL 字段。 从 token claims 派生 groups 如果你的 OAuth 或 OIDC 提供方已经在 id_token 或 access_token 中返回用户组信息,你可以省去托管用户信息端点的步骤,让 Mintlify 直接从你的 token 端点返回的 token 中读取 groups。 当你配置 Token claims 时,Mintlify 会:
从 token 端点响应中解码所配置的 token。
提取所配置的 claim,并将其规范化为一个 groups 列表。
使用这些 groups 来执行基于用户组的访问控制 。
跳过对 Info API URL 的任何 groups 数据请求。
在 Token claims 下配置以下字段:
Source :读取 groups 的目标 token。选择 id_token (默认) 或 access_token。如果使用 id_token,请在你的 OAuth Scopes 中包含 openid。
Groups claim :用于读取 groups 的 claim。你可以使用顶层 claim 名称、带命名空间的 URI claim,或指向嵌套 claim 的点号路径。例如:
groups 表示顶层数组 claim。
https://your-domain.example.com/groups 表示 Auth0 命名空间 claim。
realm_access.roles 表示 Keycloak realm role claim。
Mintlify 接受的 claim 值可以是字符串的 JSON 数组,也可以是单个字符串。 从 token claims 派生 groups 采用 fail-closed 策略。如果在 token 响应中缺少所配置的 token (例如,在未包含 openid scope 的情况下请求 id_token) ,Mintlify 会阻止登录,而不是让用户以无任何 groups 的状态登录。
Token claims 示例 对于返回包含 groups claim 的 access_token 的提供方: 对于在嵌套 claim 中返回 roles 的 Keycloak 提供方: OAuth 2.0 示例 你将文档托管在 docs.foo.com,并且你有一个现有的 OAuth 服务器 auth.foo.com,它支持 Authorization Code Flow。 在控制台中配置你的 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%2Fdocs.foo.com
在 api.foo.com/docs/user-info 上创建一个用户信息端点 ,该端点要求使用带有 provider.users.docs scope 的 OAuth 访问令牌,并返回: 使用用户信息响应中的 expiresAt 字段控制会话时长。该字段为 Unix 时间戳 (自纪元以来的秒数) ,用于指示会话何时过期。更多详情请参阅 用户数据格式 。 将你的 OAuth 服务器配置为允许重定向 到回调 URL。JWT 前提条件
一个可以生成并签名 JWT 的认证系统。
一个可以创建重定向 URL 的后端服务。
JWT 设置
生成私钥。
在控制台中前往 Authentication 。
在 Authentication method 部分,将站点可见性设置为 Private 。
点击 Custom 。
点击 JWT 。
输入你现有登录流程的 URL。
点击 Save changes 。
点击 Generate new key 。
将你的 key 安全存储在后端可以访问的位置。
生成私钥后,你的网站会重新部署。部署完成后,任何访问你网站的人都必须登录到你的 JWT 认证系统才能访问你的内容。
将 Mintlify 认证集成到你的登录流程中。
修改你现有的登录流程,在用户通过认证后增加以下步骤:
按 User 格式创建一个包含已认证用户信息的 JWT。更多信息参见 User data format 。
使用 EdDSA 算法,用你的密钥对 JWT 进行签名。
创建一个返回到文档 /login/jwt-callback 路径的重定向 URL,并将 JWT 放在 URL 片段 (hash) 中。
JWT 示例 你在 docs.foo.com 上托管文档,并在 foo.com 上已有认证系统。你希望扩展登录流程,在保持文档与控制台分离的同时,为文档授予访问权限 (或者如果你没有控制台,则直接为文档授予访问权限) 。 在 https://foo.com/docs-login 创建一个登录端点,用于扩展你现有的认证逻辑。 在验证用户凭据之后:
按 Mintlify 的格式生成包含用户数据的 JWT。
对 JWT 进行签名并重定向到 https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}。
重定向未认证用户 当未认证用户尝试访问受保护页面时,系统在重定向到你的登录 URL 时会保留用户的目标地址。
用户尝试访问受保护页面:https://docs.foo.com/quickstart。
重定向到带有 redirect 查询参数的登录 URL:https://foo.com/docs-login?redirect=%2Fquickstart。
认证完成后,重定向到 https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}。
用户将进入其最初想要访问的页面。
在使用认证时,所有页面默认都需要通过认证才能访问。你可以在页面或分组级别通过 public 属性将特定页面设置为无需认证即可访问。
要将页面设为公开,请在该页面的 frontmatter 中添加 public: true。
要将某个分组中的所有页面设为公开,请在 docs.json 的 navigation 对象中,该分组名称下添加 "public": true。
当你使用 OAuth 或 JWT (JSON Web Token) 进行认证时,可以将特定页面仅限于某些用户组访问。若希望不同用户根据其角色或属性查看不同内容,这将非常有用。
通过在认证过程中传递的用户数据来管理 groups。详见 用户数据格式 。
使用 frontmatter 中的 groups 属性来指定哪些 groups 可以访问特定页面。
Example page restricted to the admin group
用户必须至少属于所列的一个 groups 才能访问该页面。如果用户在不具备所需分组的情况下尝试访问页面,将会收到 404 错误。
默认情况下,所有页面都需要认证。
具有 groups 属性的页面仅对属于这些 groups 的已认证用户可访问。
没有 groups 属性的页面对所有已认证用户可访问。
具有 public: true 且没有 groups 属性的页面对所有人可访问。
当使用 OAuth 或 JWT 认证时,系统会返回用户数据,用于控制会话时长、基于用户组成员关系的访问控制,以及内容个性化 。
JWT 认证时必填。 你的文档站点的主机名。该字符串必须与你部署文档的 domain 完全一致。Mintlify 会验证 JWT 的 host 是否与发起请求的 host 匹配,以防止令牌在不同站点之间被重复使用。
会话过期时间,以自 epoch 起算的秒数表示。当当前时间超过该值时,用户必须重新完成认证。 对于 JWT: 这不同于 JWT 的 exp 声明,后者用于决定 JWT 何时被视为无效。出于安全考虑,应将 JWT 的 exp 声明设置为较短的时长 (10 秒或更少) 。使用 expiresAt 来表示实际会话时长 (从数小时到数周) 。
用户所属用户组的列表。frontmatter 中带有匹配 groups 的页面对该用户可访问。 示例 :具有 groups: ["admin", "engineering"] 的用户可以访问带有 admin 或 engineering 用户组标记的页面。
可在 MDX 页面中通过 user 变量访问的自定义数据,用于个性化内容 。
使用用户特定的值预填 API 操作台中的字段。当用户完成认证后,这些值会填充到 API 操作台中对应的输入字段。用户可以覆盖预填的值,其修改会持久保存在本地存储中。 Mintlify 只会应用与当前端点的安全方案匹配的值。 要预填的 Header 值,以 Header 名称作为 key。
要预填的 Cookie 值,以 Cookie 名称作为 key。
启用认证后,部分功能的行为会有所不同,或可能不可用。