在您的空间中添加使用 HF 登录按钮

您可以通过无缝创建和关联OAuth/OpenID Connect应用，从而在您的空间中启用内置登录流程，以便用户可以使用其 HF 帐户登录。

这为您的空间启用了新的用例。例如，当与持久存储结合使用时，生成式 AI 空间可以让用户登录以访问其先前的生成，并且只有他们可以访问。

创建 OAuth 应用

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

以下是一个 Gradio 空间的元数据示例

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

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

这会将以下环境变量添加到您的空间

• 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_HOST作为环境变量可用。

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

范围

以下范围始终包含在空间中

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

这些范围是可选的，可以通过在空间的元数据中设置hf_oauth_scopes来添加

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

访问组织资源

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

但某些范围（如read-repos或read-billing）也适用于组织。

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

将按钮添加到您的空间

现在您拥有了将“使用 HF 登录”按钮添加到您的空间所需的所有信息。一些库（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 令牌（使用client_id、code、grant_type=authorization_code 和 redirect_uri 作为表单数据进行 POST 请求，并在标头中使用Authorization: Basic {base64(client_id:client_secret)}）。

示例：

• Gradio 测试应用
• Hugging Chat (NodeJS/SvelteKit)
• 推理小部件 (Auth.js/SvelteKit)，使用inference-api 范围代表用户发出推理请求。
• 静态空间中的客户端 OAuth (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);