使用 Hugging Face 登录

您可以使用 HF OAuth / OpenID connect 流程，在任何网站或 App 中创建 “使用 HF 登录” 流程。

这将允许用户通过点击类似此按钮的按钮，使用其 HF 账户登录您的网站或应用：

点击此按钮后，您的用户将看到一个权限弹窗，用于授权您的应用：

创建 oauth 应用

您可以在设置中创建您的应用程序：

组织拥有的 OAuth 应用

此功能属于 Team & Enterprise 计划的一部分。

OAuth 应用也可以由组织而非个人账户拥有。这对于团队共同维护的应用非常有用，因为应用将归属于组织，而不依赖于单个成员的账户。

组织管理员可以在组织设置中的 OAuth Apps 部分（https://huggingface.co/organizations/<your-org>/settings/applications）创建和管理组织拥有的应用。该组织的所有管理员都可以编辑应用、轮换其 client secret 或删除它。应用列表会显示每个应用是由哪位成员创建的，并且对应用的更改会记录在组织的 audit logs 中。

同一页面还列出了该组织的 Token Exchange 应用（如果已设置）。

您还可以通过应用设置页面中的 转移到组织 部分，将您拥有的现有 OAuth 应用转移至您担任管理员的组织。该组织必须使用 Team 或 Enterprise 套餐。转移完成后，该应用将由组织的所有管理员共同管理。其 client ID、client secret 以及现有的授权和令牌保持不变，因此您的网站或应用无需任何更改即可继续正常运行。此转移操作无法从设置页面撤销。

公共 OAuth 应用（无密钥）

您可以创建或使用无需客户端密钥的 OAuth 应用。这在原生应用、CLI 或其他难以安全保存密钥的场景中非常有用。

• 创建应用时：创建新的 OAuth 应用时，您可以选择不设置密钥。
• 创建后：对于现有应用，您可以在应用设置中删除客户端密钥。之后，该应用将作为公共应用运行。

公共应用仅使用客户端 ID 进行身份验证（例如，在采用 PKCE 的设备代码或授权代码流程中）。拥有密钥的应用在需要时仍可使用该密钥（例如，在令牌请求中使用 Authorization: Basic）。

重定向 URI

授权请求中发送的 redirect_uri 必须与您在应用中注册的某个重定向 URI 完全匹配。

回环重定向 URI 是一个例外：对于使用 http 方案且主机为回环地址（localhost、127.0.0.1 或 [::1]）的 URI，只要其他所有组件都与已注册的 URI 匹配，请求时即可接受任意端口。这遵循 RFC 8252 §7.3 / OAuth 2.1，允许原生应用、CLI 和 MCP 客户端注册一个不带端口的 URI（例如 http://localhost/callback），然后监听操作系统为其分配的任意临时端口（例如 http://localhost:49282/callback）。

有几点需要注意：

• 该例外仅适用于 http 协议。https 和自定义协议（例如 myapp://callback）的重定向 URI 始终要求精确匹配，包括端口。
• 回环主机是单独匹配的：对 http://localhost:49282/callback 的请求不会匹配已注册的 http://127.0.0.1/callback。如果您的应用可能使用其中任意一个，请同时注册两者。
• 只有端口可能不同。路径、查询和 userinfo 仍必须完全匹配。

如果您在 Spaces 中托管

如果您在 Spaces 上托管您的应用，那么实现流程会更加简单（并且 Gradio 已直接内置该功能）；请参阅我们的 Spaces OAuth 指南。

自动创建 OAuth 应用

Hugging Face 支持 CIMD，即 Client ID Metadata Documents，它允许您以自动化的方式为您的网站创建 oauth 应用：

• 在您的网站上添加一个端点 /.well-known/oauth-cimd，使其返回以下 JSON：

{
  client_id:                  "[your website url]/.well-known/oauth-cimd",
  client_name:                "Your Website",
  redirect_uris:              ["[your website url]/oauth/callback/huggingface"],
  token_endpoint_auth_method: "none",
  logo_uri:                  "https://....", // optional
  client_uri:                 "[your website url]", // optional
}

• 使用 "[your website url]/.well-known/oauth-cimd" 作为客户端 ID，并使用 PCKE 作为身份验证机制

在本地端口接收授权代码的原生应用和 MCP 客户端可以在 redirect_uris 中列出无端口的回环 URI，例如 ["http://localhost/callback", "http://127.0.0.1/callback"] — 请参阅 重定向 URI。

这在临时环境或 MCP 客户端中尤为有用。请参阅 Hugging Chat 中的实现示例。

设备代码 OAuth

设备代码流程允许用户通过在一台设备上（例如 CLI）运行应用，然后在另一台设备上（例如手机或浏览器）输入一个简短代码来授权该应用。运行应用的设备上无需重定向 URI 或浏览器。

使用示例脚本进行测试

您可以使用以下脚本测试设备代码 OAuth 应用。请将 <Client ID> 替换为您应用的客户端 ID。对于 公共应用（无密钥），脚本可直接使用。对于 带密钥的应用，请在设备请求和令牌请求中都添加 Authorization: Basic 请求头（即 client_id:client_secret 的 Base64 编码）。

#!/bin/bash
CLIENT_ID="<Client ID>"

# Step 1: Get device code
RESPONSE=$(curl -s -X POST https://huggingface.co/oauth/device \
  -d "client_id=$CLIENT_ID")

DEVICE_CODE=$(echo $RESPONSE | jq -r '.device_code')
USER_CODE=$(echo $RESPONSE | jq -r '.user_code')
VERIFICATION_URI=$(echo $RESPONSE | jq -r '.verification_uri')

echo "Device Code: $DEVICE_CODE"
echo "User Code: $USER_CODE"
echo ""
echo "Open: ${VERIFICATION_URI}"
echo "Enter the user code: $USER_CODE"
echo ""
read -p "Press Enter after authorizing..."

# Step 3: Get token
curl -X POST https://huggingface.co/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=$DEVICE_CODE" \
  -d "client_id=$CLIENT_ID"

对于具有客户端密钥的 OAuth 应用，请在设备代码请求和令牌请求中都包含 Authorization: Basic 请求头（其中包含 Base64 编码的 client_id:client_secret）。

当前支持的 scopes

当前支持的 scope 为：

• openid：除访问令牌外，还会接收一个 ID 令牌。
• profile：读取用户的个人资料信息（用户名、头像等）
• 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 权限范围。

所有其他信息均可在 OpenID 元数据 中获取。

如果您需要额外的权限范围，请联系我们。

访问组织资源

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

但某些作用域，例如 read-repos 或 read-billing，也适用于组织。

用户在授权应用时可以选择授予哪些组织的访问权限。如果您需要访问特定组织，可以将 orgIds=ORG_ID 作为查询参数添加到 OAuth 授权 URL 中。组织 ID 可在 userinfo 响应的 orgs[].sub 字段中获取。

将组织成员身份同步为组

userinfo 响应（https://huggingface.co/oauth/userinfo）包含一个 groups 声明：用户所属组织的名称，以字符串数组形式表示。

{
  "sub": "...",
  "preferred_username": "my-username",
  "groups": ["my-org", "another-org"],
  "orgs": [ ... ]
}

许多 OIDC 客户端（例如 Discourse、Grafana、Argo CD、Vault、Kubernetes）可以从包含字符串数组的声明中同步组成员身份，并且通常配置为使用 groups 声明。您可以利用该声明将 Hugging Face 组织映射到您应用中的角色或组。如需了解每个组织的详细信息（ID、角色等），请改用 orgs 字段。

有几点需要注意：

• groups 声明仅由 userinfo 端点返回，不会包含在 ID token 中。
• 它包含的是组织名称，而非 ID。如果组织被重命名，使用其旧名称的映射将不再匹配。
• 资源组不包含在内。对于付费计划的组织，用户的资源组和角色列在 orgs[].resourceGroups 中。

品牌

您可以自由设计按钮的样式。以下是一些贴心提供的 SVG 图像。

查看我们的徽章，其中包含在 Markdown 或 HTML 中集成它们的说明。

面向组织的令牌交换（RFC 8693）

此功能属于 Enterprise 套餐的一部分。

Token Exchange 允许组织以编程方式为成员签发访问令牌，而无需交互式用户同意。这在构建需要代表组织成员访问 Hugging Face 资源的内部工具、自动化流水线和企业集成时尤为有用。

如果你只需要从 CI/CD 工作流（GitHub Actions、GitLab CI、CircleCI 等）进行无密钥身份验证——而无需为每位成员签发令牌——请参阅 Trusted Publishers。该功能同样使用 /oauth/token，但将你的 CI 提供商签发的 OIDC id_token 作为主体令牌（无需企业版套餐，也无需客户端凭据）。

此功能实现了RFC 8693 - OAuth 2.0 Token Exchange，这是一种用于令牌交换场景的标准协议。

用例

Token Exchange 专为以下场景设计：

• 构建内部平台：创建仪表盘或门户，代表您的团队成员访问 Hugging Face 资源，而无需每位用户手动进行身份验证。
• 自动化 CI/CD 流水线：为需要向组织仓库推送模型或数据集的自动化工作流颁发短期、限定范围的令牌。
• 与企业身份系统集成：通过基于内部用户目录颁发令牌，将现有的身份提供商与 Hugging Face 对接。
• 实现自定义访问控制：构建中间件，根据组织的内部策略颁发具有特定范围的令牌。

工作原理

1. 您的组织拥有一个绑定到该组织且具有 token-exchange 权限的 OAuth 应用程序。
2. 您的后端服务使用客户端凭据与此 OAuth 应用进行身份验证。
3. 您的服务请求针对特定组织成员（通过电子邮件地址标识）的访问令牌。
4. Hugging Face 会验证该用户是否为您组织的成员，并颁发一个具有作用域的令牌。
5. 签发的令牌只能访问您组织范围内的资源。

先决条件

要使用 Token Exchange，你需要一个与组织绑定的 OAuth 应用，并且该应用具有 token-exchange 权限。请联系 Hugging Face 支持团队，为你的组织设置符合条件的 OAuth 应用。

配置完成后，您将收到：

• 客户端 ID（例如 a1b2c3d4-e5f6-7890-abcd-ef1234567890）
• 客户端密钥（请妥善保管！）

组织管理员可以在创建后管理 OAuth 应用，包括刷新客户端密钥和配置令牌有效期。该应用列在组织设置的 OAuth Apps 部分中，对其所做的更改会记录在组织的 audit logs 中。

身份验证

Token Exchange 使用 HTTP 基本身份验证，并采用您的 OAuth 应用凭据。通过 Base64 编码您的 client_id:client_secret 来创建授权头：

# Create the authorization header
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export AUTH_HEADER=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)

通过电子邮件颁发令牌

使用电子邮件地址为组织成员颁发访问令牌：

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email"

响应

成功的请求会返回一个访问令牌：

{
  "access_token": "hf_oauth_...",
  "token_type": "bearer",
  "expires_in": 28800,
  "scope": "openid profile email read-repos",
  "id_token": "eyJhbGciOiJS...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

当请求 openid 作用域时，会包含 id_token 字段。

然后，您可以使用此令牌代表用户发起 API 请求：

curl "https://huggingface.co/api/whoami-v2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

范围控制

默认情况下，签发的令牌会继承 OAuth 应用上配置的所有作用域。您可以通过添加 scope 参数来请求特定的作用域。有关可用值，请参阅 当前支持的作用域。

令牌的有效权限同时受请求的作用域和用户在组织中的角色限制。

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email" \
  -d "scope=openid profile"

遵循最小权限原则：仅请求您的应用实际所需的权限范围。

安全注意事项

通过 Token Exchange 签发的令牌具有内置的安全限制：

• 组织范围：令牌只能访问您组织内的资源（由该组织拥有的模型、数据集、Spaces 和集合）。在组织外部，访问权限为只读，且仅限于：任何用户或组织的公开集合，以及用户已被单独授予访问权限的公开受限仓库。
• 无个人访问权限：令牌无法访问用户的个人私有仓库或其他组织的私有仓库。
• 短期有效：令牌默认在 8 小时后过期。组织管理员可以在 OAuth 应用设置中配置令牌有效期（最长 30 天）。不提供刷新令牌。
• 可审计：所有令牌交换操作均会被记录，并显示在您组织的 审计日志 中。

请妥善保管您的 OAuth 应用凭据。任何能够访问您的客户端密钥的人都可以为您的组织中的任何成员颁发令牌。

错误响应

参考

授权类型：

urn:ietf:params:oauth:grant-type:token-exchange

请求参数（subject_token_type）：

响应字段（issued_token_type）：

相关文档：

• RFC 8693 - OAuth 2.0 令牌交换
• 审计日志