將「使用 HF 登入」按鈕新增至您的 Space

您可以透過順暢地建立並關聯一個 OAuth/OpenID Connect 應用程式，在您的 Space 中啟用內建的登入流程，讓使用者可以使用他們的 HF 帳號進行登入。

這為您的 Space 開啟了新的應用場景。例如，當與 Storage Buckets 結合使用時，生成式 AI Space 可以允許使用者登入以存取他們過往的生成內容，且僅限他們本人存取。

本指南將帶您瞭解將「使用 HF 登入」按鈕整合至任何 Space 的過程。如果您正在尋找一種快速且簡單的方法在 Gradio Space 中實作此功能，請查看其內建整合。

您也可以使用 HF OAuth 流程在 Space 以外的任何網站或應用程式中建立「使用 HF 登入」流程。請閱讀我們一般的 OAuth 頁面。

建立 OAuth 應用程式

您只需要在 README.md 檔案中的 Space 元資料（metadata）內新增 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

您可以查看設定參考文件以取得更多資訊。

這會將以下環境變數新增至您的 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 (Redirect URLs)

只要目標為您的 Space，您可以使用任何您想要的重新導向 URL。

請注意，SPACE_HOST 可作為環境變數使用。

例如，您可以使用 https://{SPACE_HOST}/login/callback 作為重新導向 URI。

權限範圍 (Scopes)

以下權限範圍會自動包含在 Space 中：

• openid：取得 ID 權杖（ID token）以及存取權杖（access token）。
• profile：取得使用者的個人檔案資訊（使用者名稱、頭像等）。

這些權限範圍是選擇性的，可以透過在 Space 的元資料中設定 hf_oauth_scopes 來新增：

• email：取得使用者的電子郵件地址。
• read-billing：確認使用者是否設定了付款方式。
• read-repos：取得使用者個人儲存庫的讀取存取權。
• gated-repos：取得使用者已被授予存取權限的公開受限儲存庫（public gated repos）內容的讀取存取權。與 read-repos 不同，這不會授權存取私人儲存庫。
• contribute-repos：可以建立儲存庫並存取由該應用程式建立的儲存庫。除非授予額外權限，否則無法存取任何其他儲存庫。
• write-repos：取得使用者個人儲存庫的寫入/讀取存取權。
• manage-repos：取得使用者個人儲存庫的完整存取權。同時授權儲存庫的建立與刪除。
• read-collections：取得使用者個人收藏集的讀取存取權。
• write-collections：取得使用者個人收藏集的寫入/讀取存取權。同時授權收藏集的建立與刪除。
• inference-api：取得推論提供者 (Inference Providers) 的存取權，您將能夠代表使用者進行推論請求。
• jobs：執行 jobs。
• webhooks：管理 webhooks。
• write-discussions：代表使用者開啟討論與 Pull Requests，以及與討論進行互動（包括回應、發布/編輯留言、關閉討論等）。若要在私人儲存庫中開啟 Pull Requests，您也需要請求 read-repos 範圍。

存取組織資源

預設情況下，OAuth 應用程式不需要存取組織資源。

但某些權限範圍（如 read-repos 或 read-billing）也適用於組織。

使用者在授權應用程式時，可以選擇要授予存取權的組織。如果您需要存取特定組織，可以在 OAuth 授權 URL 中新增 orgIds=ORG_ID 作為查詢參數。您必須將 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 權杖（使用 client_id、code、grant_type=authorization_code 和 redirect_uri 作為表單資料進行 POST 請求，並在標頭中加入 Authorization: Basic {base64(client_id:client_secret)}）。

除非您在 iframe 之外執行該 Space，否則應在按鈕上使用 target=_blank 以在新分頁中開啟登入頁面。否則，您可能會在某些瀏覽器上遇到 Cookie 相關問題。

範例：

• Gradio 測試應用程式
• HuggingChat (NodeJS/SvelteKit)
• Inference Widgets (Auth.js/SvelteKit)，使用 inference-api 範圍來代表使用者進行推論請求。
• Client-Side in a Static 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);