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

您可以在您的 Space 中启用内置的登录流程，通过无缝创建并关联一个 OAuth/OpenID connect 应用，让用户使用其 HF 账户登录。

这为您的 Space 开启了新的使用场景。例如，结合 Storage Buckets，生成式 AI Space 可以允许用户登录以访问其之前的生成内容，且这些内容仅对该用户可见。

本指南将引导您了解如何在任意 Space 中集成 Sign-In with HF 按钮。如果您希望在 Gradio Space 中快速且简单地实现此功能，请查看其 内置集成。

您还可以使用 HF OAuth 流程在任何网站或 App 中创建“使用 HF 登录”流程，而不仅限于 Spaces。阅读我们的通用 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
 - gated-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

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

这将为您的空间添加以下环境变量：

• 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-memberships：读取用户所属的组织及其在每个组织中的角色。此权限不会授予访问组织设置或资源的权限。
• read-repos：读取用户的个人仓库。
• gated-repos：读取用户已获得访问权限的公开受限仓库的内容。与 read-repos 不同，此权限不会授予对私有仓库的访问权限。
• contribute-repos：创建仓库并访问由该应用创建的仓库。除非授予额外权限，否则无法访问任何其他仓库。
• write-repos：读取和写入用户的个人仓库。
• manage-repos：完全管理用户的个人仓库，包括创建和删除仓库。
• read-collections：读取用户的个人收藏。
• write-collections：读取和写入用户的个人收藏，包括创建和删除收藏。
• inference-api：代表用户向 Inference Providers 发起推理请求。
• read-endpoints：查看用户的Inference Endpoints，并代表用户向它们发起推理请求。
• write-endpoints：管理用户的 Inference Endpoints，包括创建和删除。包含 read-endpoints 访问权限。
• jobs：运行 jobs
• webhooks：管理 webhooks
• 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

现在，您已具备在您的 Space 中添加“Sign-in with HF”按钮所需的全部信息。一些库（Python、NodeJS）可以帮助您实现 OpenID/OAuth 协议。

Gradio 和 huggingface.js 也提供了内置支持，让实现 Sign-in with 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)}）。

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

示例：

• Gradio 测试应用
• HuggingChat (NodeJS/SvelteKit)
• 推理小部件（Auth.js/SvelteKit）使用 inference-api 作用域代表用户发起推理请求。
• 静态空间中的客户端（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);