向你的 Space 添加 HF 登录按钮

你可以通过无缝创建和关联 OAuth/OpenID 连接应用，在你的 Space 中启用内置的登录流程，以便用户可以使用他们的 HF 帐户登录。

这为你的 Space 启用了新的用例。例如，当与持久存储结合使用时，生成式 AI Space 可以允许用户登录以访问他们之前的生成内容，这些内容仅对他们可见。

本指南将带你完成将“HF 登录”按钮集成到任何 Space 的过程。如果你正在寻找一种快速简便的方法在 Gradio Space 中实现此功能，请查看其内置集成。

你还可以使用 HF OAuth 流程在任何网站或 App 中创建“使用 HF 登录”流程，而不仅仅是在 Spaces 中。阅读我们的通用 OAuth 页面。

创建 OAuth 应用

你只需将 hf_oauth: true 添加到你的 Space 的 README.md 文件中的元数据中。

这是一个 Gradio Space 的元数据示例

title: Gradio Oauth Test
emoji: 🏆
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 3.40.0
python_version: 3.10.6
app_file: app.py

hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
# optional, see "Scopes" below. "openid profile" is always included.
hf_oauth_scopes:
 - read-repos
 - write-repos
 - manage-repos
 - inference-api
# optional, restrict access to members of specific organizations
hf_oauth_authorized_org: ORG_NAME
hf_oauth_authorized_org:
  - ORG_NAME1
  - ORG_NAME2

你可以查看配置参考文档以获取更多信息。

这将向你的 Space 添加以下环境变量

OAUTH_CLIENT_ID：你的 OAuth 应用的客户端 ID (公开)
OAUTH_CLIENT_SECRET：你的 OAuth 应用的客户端密钥
OAUTH_SCOPES：你的 OAuth 应用可访问的作用域。
OPENID_PROVIDER_URL：OpenID 提供商的 URL。OpenID 元数据将在 {OPENID_PROVIDER_URL}/.well-known/openid-configuration 中提供。

与任何其他环境变量一样，你可以在代码中使用它们，例如使用 os.getenv("OAUTH_CLIENT_ID")。

重定向 URL

你可以使用任何你想要的重定向 URL，只要它指向你的 Space 即可。

请注意，SPACE_HOST 可以作为环境变量使用。

例如，你可以使用 https://{SPACE_HOST}/login/callback 作为重定向 URI。

作用域

以下作用域始终包含在 Spaces 中

openid：除了访问令牌外，还获取 ID 令牌。
profile：获取用户的个人资料信息（用户名、头像等）。

这些作用域是可选的，可以通过在你的 Space 的元数据中设置 hf_oauth_scopes 来添加

email：获取用户的电子邮件地址。
read-billing：了解用户是否设置了付款方式。
read-repos：获取对用户个人仓库的读取权限。
write-repos：获取对用户个人仓库的写入/读取权限。
manage-repos：获取对用户个人仓库的完全访问权限。还授予仓库创建和删除权限。
inference-api：获取对 Inference API 的访问权限，你将能够代表用户发出推理请求。
write-discussions：代表用户发起讨论和 Pull Request，以及与讨论互动（包括反应、发布/编辑评论、关闭讨论等）。要在私有仓库上打开 Pull Request，你还需要请求 read-repos 作用域。

访问组织资源

默认情况下，oauth 应用不需要访问组织资源。

但是某些作用域（如 read-repos 或 read-billing）也适用于组织。

用户可以在授权应用时选择授予访问权限的组织。如果你需要访问特定组织，你可以将 orgIds=ORG_ID 作为查询参数添加到 OAuth 授权 URL。你必须将 ORG_ID 替换为组织 ID，该 ID 在 userinfo 响应的 organizations.sub 字段中可用。

将按钮添加到你的 Space

现在你拥有了将“使用 HF 登录”按钮添加到你的 Space 的所有信息。一些库 (Python, NodeJS) 可以帮助你实现 OpenID/OAuth 协议。

Gradio 和 huggingface.js 也提供了内置支持，使实现“使用 HF 登录”按钮变得轻而易举；你可以查看与 gradio 和 huggingface.js 相关的指南。

基本上，你需要：

将用户重定向到 https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}，其中 STATE 是一个随机字符串，你需要稍后验证。
在 /auth/callback 或 /login/callback (或你自己的自定义回调 URL) 上处理回调，并验证 state 参数。
使用 code 查询参数从 https://huggingface.co/oauth/token 获取访问令牌和 ID 令牌（POST 请求，表单数据包含 client_id、code、grant_type=authorization_code 和 redirect_uri，标头包含 Authorization: Basic {base64(client_id:client_secret)}）。

你应该在按钮上使用 target=_blank 以在新标签页中打开登录页面，除非你在 iframe 之外运行 space。否则，你可能会在某些浏览器上遇到 cookie 问题。

示例：

Gradio 测试应用
Hugging Chat (NodeJS/SvelteKit)
推理小部件 (Auth.js/SvelteKit)，使用 inference-api 作用域代表用户发出推理请求。
静态 Space 中的客户端 (huggingface.js) - 非常简单的 JavaScript 示例。

JS 代码示例

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();
}

// You can use oauthResult.accessToken, oauthResult.userInfo among other things
console.log(oauthResult);

< > 在 GitHub 上更新