为你的 Space 添加 “Sign-In with HF” 按钮

你可以在 Space 中启用内置的登录流程：通过创建并关联一个 OAuth/OpenID Connect 应用，让用户使用自己的 HF 账号登录你的 Space。

这样可以为你的 Space 解锁更多用例。例如，结合 Persistent Storage，一个生成式 AI 的 Space 就可以让用户登录后访问自己以前的生成记录，而且这些记录仅对该用户可见。

[!TIP] 本指南会带你逐步在任意 Space 中集成 Sign-In with HF 登录按钮。如果你只是在 Gradio Space 中需要一个快速简单的方案，可以直接参考 Gradio 的内置集成。

[!TIP] 你也可以在 Spaces 之外，使用 HF OAuth 流程，在任意网站或 App 上实现 “Sign in with HF” 登录。详见通用 OAuth 页面。

创建 OAuth 应用

你只需要在 Space 仓库的 README.md 元数据中加上 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

You can check out the configuration reference docs for more information.

这会为你的 Space 添加以下环境变量：

OAUTH_CLIENT_ID：OAuth 应用的 client ID（公开）
OAUTH_CLIENT_SECRET：OAuth 应用的 client secret
OAUTH_SCOPES：OAuth 应用可以访问的作用域（scope）
OPENID_PROVIDER_URL：OpenID 提供方的 URL。OpenID 元数据会暴露在 {OPENID_PROVIDER_URL}/.well-known/openid-configuration。

和其它环境变量一样，你可以在代码中通过 os.getenv("OAUTH_CLIENT_ID") 等方式访问这些值。

Redirect URLs

只要重定向地址最终指向你的 Space，你可以选择任意 redirect URL。

注意，SPACE_HOST 也会作为辅助环境变量提供。

例如，你可以将 https://{SPACE_HOST}/login/callback 用作 redirect URI。

Scopes

对于启用 OAuth 的 Space，以下 scopes 会始终被默认包含：

openid：在 access token 之外再获取 ID token。
profile：获取用户的基本资料（用户名、头像等）。

下面这些 scopes 是可选的，你可以通过在 Space 的元数据中设置 hf_oauth_scopes 来添加：

email：获取用户的邮箱地址。
read-billing：了解用户是否已配置付款方式。
read-repos：对用户个人仓库的只读访问权限。
contribute-repos：可以创建仓库并访问由该应用创建的仓库。除非获得额外权限，否则无法访问其它仓库。
write-repos：对用户个人仓库的读写访问权限。
manage-repos：对用户个人仓库的完全访问权限，包括创建和删除仓库。
inference-api：访问 Inference Providers，代表用户发起推理请求。
jobs：运行 jobs。
webhooks：管理 webhooks。
write-discussions：代表用户创建讨论和 Pull Request，并与讨论交互（点赞、评论/编辑、关闭讨论等）。如果需要在私有仓库中开启 Pull Request，还需要额外申请 read-repos scope。

Accessing organization resources

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

但诸如 read-repos 或 read-billing 之类的 scope 同样适用于组织。

用户在授权应用时，可以选择授予哪些组织的访问权限。如果你需要访问某个特定组织，可以在 OAuth 授权 URL 上添加 orgIds=ORG_ID 查询参数。这里的 ORG_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 参数。
使用回调 URL 中的 code 参数，从 https://huggingface.co/oauth/token 获取 access token 和 id token（向该地址发送 POST 请求，表单数据中包含 client_id、code、grant_type=authorization_code 和 redirect_uri，同时在 Header 中加入 Authorization: Basic {base64(client_id:client_secret)}）。

[!WARNING] 除非你的 Space 不在 iframe 中运行，否则建议在登录按钮上使用 target=_blank，将登录页在新标签页中打开，否则在部分浏览器上可能遇到 cookie 相关问题。

Examples:

Gradio test app
Hugging Chat (NodeJS/SvelteKit)
Inference Widgets (Auth.js/SvelteKit)：使用 inference-api scope 代表用户发起推理请求。
Client-Side in a Static Space (huggingface.js)：一个非常简洁的纯 JavaScript 示例。

JS Code example:

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);

创建 OAuth 应用​

Redirect URLs​

Scopes​

Accessing organization resources​

为 Space 添加登录按钮​

Examples:​