跳转到主要内容
Auth0 是一个兼容 OAuth 2.0 和 OIDC 的身份提供方，因此可以直接接入 Mintlify 内置的 OAuth 2.0 支持。本页将 Auth0 的端点和设置映射到身份验证设置中的字段。完整流程请参考对应的官方设置页面，本页仅提供 Auth0 特定的取值。 OAuth 2.0 身份验证在 Enterprise 方案中可用。
安全免责声明：我们提供本指南以帮助你将 Auth0 集成到 Mintlify，但在实施任何身份验证方案之前，请先咨询你的安全团队。对于你的具体实现可能引发的任何安全问题，Mintlify 不承担责任。

​
前提条件

  • 一个 Auth0 租户。记下你的租户域名，例如 your-tenant.us.auth0.com。
  • 为你的文档站点创建的 Auth0 Regular Web Application。要创建一个，请在 Auth0 控制台中进入 Applications > Applications，点击 Create Application，并选择 Regular Web Applications 作为应用类型。
  • 该应用的 client ID 和 client secret，可在应用设置页面中找到。

​
将 Auth0 映射到 Mintlify 的 OAuth 字段

在 Mintlify 控制台中，进入 Access 设置页面，将站点可见性设置为 Private，然后选择 Custom → OAuth。使用以下 Auth0 的取值填写各字段。将 YOUR_AUTH0_DOMAIN 替换为你的租户域名。 保存设置。Mintlify 会使用新的身份验证配置重新部署你的站点。

​
在 Auth0 中注册重定向 URL

复制 Mintlify 身份验证设置中显示的 Redirect URL，并在 Auth0 应用的 Application URIs → Allowed Callback URLs 中添加该地址。保存 Auth0 应用。若未完成此步骤，Auth0 将拒绝登录流程。 如果你在 Mintlify 中设置了 Logout URL，请把相同的返回地址添加到 Auth0 应用的 Allowed Logout URLs。

​
基于用户组的访问控制

若要将页面限制给特定的 Auth0 用户访问，有两种方式。
  • 令牌声明（推荐）。 使用 Auth0 Action 在 ID 令牌或访问令牌中添加 groups 声明，并配置 Mintlify 读取它。参见使用 OAuth 令牌声明中的用户组。如果你从 ID 令牌中获取用户组，请在 scopes 中保留 openid。
  • Info API URL。 让 Mintlify 指向 https://YOUR_AUTH0_DOMAIN/userinfo 或你自己的端点，该端点需按用户数据格式返回用户数据。端点必须接受 Authorization: Bearer <access_token>，并在响应中返回用户组。
然后在你想限制访问的每个页面的 frontmatter 中添加匹配的 groups 值，这样只有属于该分组的成员才能看到它。

​
疑难解答

  • 回调 URL 不匹配。 Auth0 会阻止登录并显示回调错误。请确认 Auth0 Allowed Callback URLs 中的 redirect URL 与 Mintlify 身份验证设置中显示的地址完全一致，包括协议和结尾路径。
  • 用户能登录但看不到受限内容。 你的 groups 声明没有传到 Mintlify。请确认 Auth0 Action 已添加该声明，Mintlify 中的 source 与你写入声明的令牌（id_token 或 access_token）一致，并且 groupsClaim 与声明名称匹配。
  • 登出后未跳回。 Auth0 要求登出链接中的 returnTo URL 已列入该应用的 Allowed Logout URLs。

相关主题

故障排查Mintlify CLI 命令参考llms.txt