Hugging Face's logo

Hub documentation

Thêm nút Đăng nhập bằng HF vào Space của bạn

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Thêm nút Đăng nhập bằng HF vào Space của bạn

Bạn có thể bật luồng đăng nhập tích hợp trong Space của mình bằng cách tạo và liên kết một ứng dụng OAuth/OpenID connect một cách liền mạch để người dùng có thể đăng nhập bằng tài khoản HF của họ.

Điều này mở ra các trường hợp sử dụng mới cho Space của bạn. Ví dụ, khi kết hợp với Storage Buckets, một Space AI tạo sinh có thể cho phép người dùng đăng nhập để truy cập các kết quả tạo trước đó của họ, chỉ họ mới có quyền truy cập.

Hướng dẫn này sẽ đưa bạn qua quy trình tích hợp nút Đăng nhập bằng HF vào bất kỳ Space nào. Nếu bạn đang tìm kiếm một phương pháp nhanh chóng và đơn giản để triển khai điều này trong một Space Gradio, hãy xem tích hợp có sẵn của nó.

Bạn cũng có thể sử dụng luồng HF OAuth để tạo luồng “Đăng nhập bằng HF” trên bất kỳ trang web hoặc App nào, bên ngoài Spaces. Đọc trang OAuth chung của chúng tôi.

Tạo ứng dụng OAuth

Bạn chỉ cần thêm hf_oauth: true vào metadata của Space trong tệp README.md của bạn.

Dưới đây là một ví dụ về metadata cho một 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

Bạn có thể xem tài liệu tham khảo cấu hình để biết thêm thông tin.

Điều này sẽ thêm các biến môi trường sau vào space của bạn:

  • OAUTH_CLIENT_ID: ID của ứng dụng OAuth của bạn (công khai)
  • OAUTH_CLIENT_SECRET: bí mật client của ứng dụng OAuth của bạn
  • OAUTH_SCOPES: các phạm vi (scopes) mà ứng dụng OAuth của bạn có thể truy cập.
  • OPENID_PROVIDER_URL: URL của nhà cung cấp OpenID. Metadata OpenID sẽ có sẵn tại {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

Tương tự như mọi biến môi trường khác, bạn có thể sử dụng chúng trong mã của mình bằng cách dùng os.getenv("OAUTH_CLIENT_ID"), chẳng hạn.

URL chuyển hướng

Bạn có thể sử dụng bất kỳ URL chuyển hướng nào bạn muốn, miễn là nó trỏ đến Space của bạn.

Lưu ý rằng SPACE_HOST khả dụng dưới dạng biến môi trường.

Ví dụ, bạn có thể sử dụng https://{SPACE_HOST}/login/callback làm URI chuyển hướng.

Phạm vi

Các phạm vi sau luôn được bao gồm cho Spaces:

  • openid: Nhận một ID token bên cạnh access token.
  • profile: Đọc thông tin hồ sơ của người dùng (tên người dùng, ảnh đại diện, v.v.)

Các phạm vi đó là tùy chọn và có thể được thêm vào bằng cách đặt hf_oauth_scopes trong metadata của Space của bạn:

  • email: Đọc địa chỉ email của người dùng.
  • read-billing: Biết người dùng đã thiết lập phương thức thanh toán hay chưa.
  • read-memberships: Đọc các tổ chức mà người dùng thuộc về và vai trò của họ trong từng tổ chức. Quyền này không cấp quyền truy cập vào cài đặt hoặc tài nguyên của các tổ chức.
  • read-repos: Đọc các kho cá nhân của người dùng.
  • gated-repos: Đọc nội dung của các kho gated công khai mà người dùng đã được cấp quyền truy cập. Khác với read-repos, quyền này không cấp quyền truy cập vào các kho riêng tư.
  • contribute-repos: Tạo các kho lưu trữ và truy cập các kho lưu trữ được tạo bởi ứng dụng này. Không thể truy cập bất kỳ kho lưu trữ nào khác trừ khi được cấp thêm quyền.
  • write-repos: Đọc và ghi các kho cá nhân của người dùng.
  • manage-repos: Quản lý hoàn toàn các kho cá nhân của người dùng, bao gồm việc tạo và xóa chúng.
  • read-collections: Đọc các bộ sưu tập cá nhân của người dùng.
  • write-collections: Đọc và ghi các bộ sưu tập cá nhân của người dùng, bao gồm việc tạo và xóa chúng.
  • inference-api: Gửi yêu cầu suy luận đến Inference Providers thay mặt cho người dùng.
  • read-endpoints: Xem Inference Endpoints của người dùng và thực hiện các yêu cầu suy luận thay mặt cho người dùng.
  • write-endpoints: Quản lý Inference Endpoints của người dùng, bao gồm việc tạo và xóa chúng. Bao gồm quyền truy cập read-endpoints.
  • jobs: Chạy jobs
  • webhooks: Quản lý webhooks
  • write-discussions: Mở các cuộc thảo luận và Pull Requests thay mặt người dùng cũng như tương tác với các cuộc thảo luận (bao gồm phản hồi, đăng/sửa bình luận, đóng cuộc thảo luận, …). Để mở Pull Requests trên các kho riêng tư, bạn cần yêu cầu phạm vi read-repos thêm.

Truy cập tài nguyên của tổ chức

Mặc định, ứng dụng oauth không cần truy cập các tài nguyên của tổ chức.

Nhưng một số phạm vi như read-repos hoặc read-billing cũng áp dụng cho các tổ chức.

Người dùng có thể chọn các tổ chức nào được cấp quyền truy cập khi xác thực ứng dụng. Nếu bạn yêu cầu quyền truy cập vào một tổ chức cụ thể, bạn có thể thêm orgIds=ORG_ID làm tham số truy vấn vào URL xác thực OAuth. Bạn phải thay thế ORG_ID bằng ID của tổ chức, có sẵn trong trường organizations.sub của phản hồi userinfo.

Thêm nút vào Space của bạn

Bạn đã có đủ thông tin để thêm nút “Đăng nhập bằng HF” vào Space của mình. Một số thư viện (Python, NodeJS) có thể giúp bạn triển khai giao thức OpenID/OAuth.

Gradio và huggingface.js cũng cung cấp hỗ trợ tích hợp sẵn, giúp việc triển khai nút Sign-in with HF trở nên dễ dàng; bạn có thể xem các hướng dẫn liên quan với gradio và với huggingface.js.

Về cơ bản, bạn cần:

  • Định tuyến người dùng đến https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}, trong đó STATE là một chuỗi ngẫu nhiên mà bạn sẽ cần xác minh sau đó.
  • Xử lý callback tại /auth/callback hoặc /login/callback (hoặc URL callback tùy chỉnh của bạn) và xác minh tham số state.
  • Sử dụng tham số truy vấn code để lấy access token và id token từ https://huggingface.co/oauth/token (yêu cầu POST với client_id, code, grant_type=authorization_code và redirect_uri dưới dạng dữ liệu biểu mẫu, và với Authorization: Basic {base64(client_id:client_secret)} dưới dạng header).

Bạn nên sử dụng target=_blank trên nút để mở trang đăng nhập trong một tab mới, trừ khi bạn chạy space bên ngoài iframe của nó. Nếu không, bạn có thể gặp sự cố liên quan đến cookie trên một số trình duyệt.

Ví dụ:

Ví dụ mã 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);
Update on GitHub

←Tham khảo cấu hình Spaces Các Space nổi bật→