为您的 Space 添加“使用 HF 登录”按钮

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

这为您的 Space 带来了新的用例。例如，当与持久存储结合使用时，一个生成式 AI Space 可以允许用户登录以访问他们以前的生成内容，这些内容只有他们才能访问。

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

您还可以使用 HF OAuth 流程在 Spaces 之外的任何网站或应用程序中创建“使用 HF 登录”流程。阅读我们的通用 OAuth 页面。

创建 OAuth 应用

您只需在 README.md 文件中的 Space 元数据中添加 hf_oauth: true 即可。

以下是 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: 获取推理 API 的访问权限，您将能够代表用户进行推理请求。
write-discussions: 代表用户发起讨论和拉取请求，以及与讨论互动（包括点赞、发布/编辑评论、关闭讨论等）。要在私有仓库上发起拉取请求，您还需要请求 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 上更新