為您的 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 上更新