Đăng nhập bằng Hugging Face

Bạn có thể sử dụng luồng HF OAuth / OpenID connect để tạo luồng “Đăng nhập bằng HF” trên bất kỳ trang web hoặc ứng dụng nào.

Điều này sẽ cho phép người dùng đăng nhập vào trang web hoặc ứng dụng của bạn bằng tài khoản HF của họ, bằng cách nhấp vào một nút tương tự như nút này:

Sau khi nhấp vào nút này, người dùng của bạn sẽ được hiển thị một hộp thoại cấp quyền để cấp quyền cho ứng dụng của bạn:

Tạo ứng dụng oauth

Bạn có thể tạo ứng dụng của mình trong cài đặt:

Ứng dụng OAuth thuộc sở hữu của tổ chức

Tính năng này là một phần của các gói Team & Enterprise.

Ứng dụng OAuth cũng có thể thuộc về một tổ chức thay vì một tài khoản cá nhân. Điều này hữu ích cho các ứng dụng do nhóm của bạn cùng duy trì, vì chúng sẽ gắn liền với tổ chức thay vì phụ thuộc vào tài khoản của một thành viên duy nhất.

Quản trị viên tổ chức có thể tạo và quản lý các ứng dụng thuộc sở hữu của tổ chức từ phần OAuth Apps trong cài đặt của tổ chức (https://huggingface.co/organizations/<your-org>/settings/applications). Tất cả quản trị viên của tổ chức đều có thể chỉnh sửa ứng dụng, xoay client secret của nó hoặc xóa nó. Danh sách ứng dụng hiển thị thành viên nào đã tạo mỗi ứng dụng, và các thay đổi đối với các ứng dụng được ghi lại trong audit logs của tổ chức.

Trang đó cũng liệt kê Ứng dụng Token Exchange của tổ chức, nếu đã được thiết lập.

Bạn cũng có thể chuyển một ứng dụng OAuth hiện có mà bạn sở hữu sang một tổ chức mà bạn là quản trị viên, từ phần Chuyển sang một tổ chức trong trang cài đặt của ứng dụng. Tổ chức phải đang sử dụng gói Team hoặc Enterprise. Sau khi chuyển, ứng dụng sẽ được quản lý bởi tất cả các quản trị viên của tổ chức. Client ID, client secret, cũng như các ủy quyền và token hiện có sẽ không thay đổi, do đó trang web hoặc ứng dụng của bạn sẽ tiếp tục hoạt động mà không cần chỉnh sửa. Việc chuyển này không thể hoàn tác từ trang cài đặt.

Ứng dụng OAuth công khai (không có bí mật)

Bạn có thể tạo hoặc sử dụng ứng dụng OAuth mà không cần client secret. Điều này hữu ích cho các ứng dụng native, CLI hoặc các ngữ cảnh khác mà việc giữ bí mật là không thực tế.

• Khi tạo ứng dụng: Khi tạo một ứng dụng OAuth mới, bạn có thể chọn tạo mà không có bí mật.
• Sau khi tạo: Đối với ứng dụng hiện có, bạn có thể xóa bí mật client trong cài đặt ứng dụng. Ứng dụng sau đó sẽ hoạt động như một ứng dụng công khai.

Ứng dụng công khai xác thực chỉ bằng client ID (ví dụ: trong các luồng mã thiết bị hoặc luồng mã ủy quyền với PKCE). Các ứng dụng có secret vẫn có thể sử dụng secret khi cần (ví dụ: Authorization: Basic cho các yêu cầu token).

URI chuyển hướng

redirect_uri được gửi trong yêu cầu ủy quyền phải khớp chính xác với một trong các URI chuyển hướng đã đăng ký trên ứng dụng của bạn.

Loopback redirect URIs là ngoại lệ duy nhất: đối với các URI sử dụng scheme http trên một host loopback (localhost, 127.0.0.1 hoặc [::1]), bất kỳ cổng nào cũng được chấp nhận tại thời điểm yêu cầu, miễn là mọi thành phần khác khớp với một URI đã đăng ký. Điều này tuân theo RFC 8252 §7.3 / OAuth 2.1, và cho phép các ứng dụng native, CLI và client MCP đăng ký một URI không có cổng như http://localhost/callback và sau đó lắng nghe trên bất kỳ cổng tạm thời nào do hệ điều hành gán cho chúng (ví dụ: http://localhost:49282/callback).

Một vài điều cần lưu ý:

• Ngoại lệ chỉ áp dụng cho scheme http. Các URI chuyển hướng sử dụng https và scheme tùy chỉnh (ví dụ: myapp://callback) luôn yêu cầu khớp chính xác, bao gồm cả cổng.
• Các host loopback được khớp riêng lẻ: một yêu cầu đến http://localhost:49282/callback sẽ không khớp với http://127.0.0.1/callback đã được đăng ký. Hãy đăng ký cả hai nếu ứng dụng của bạn có thể sử dụng bất kỳ cái nào.
• Chỉ có cổng (port) có thể khác. Đường dẫn (path), truy vấn (query) và thông tin người dùng (userinfo) vẫn phải khớp chính xác.

Nếu bạn đang triển khai trên Spaces

Nếu bạn triển khai ứng dụng trên Spaces, quy trình sẽ càng dễ triển khai hơn (và được tích hợp sẵn trong Gradio); Xem hướng dẫn OAuth cho Spaces của chúng tôi.

Tạo ứng dụng oauth tự động

Hugging Face hỗ trợ CIMD hay Client ID Metadata Documents, cho phép bạn tạo ứng dụng oauth cho trang web của mình một cách tự động:

• Thêm một endpoint vào trang web của bạn tại /.well-known/oauth-cimd để trả về JSON sau:

{
  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
}

• Sử dụng "[your website url]/.well-known/oauth-cimd" làm client ID, và PCKE làm cơ chế xác thực

Ứng dụng native và các client MCP nhận mã ủy quyền trên một cổng cục bộ có thể liệt kê các URI loopback không có cổng trong redirect_uris, ví dụ ["http://localhost/callback", "http://127.0.0.1/callback"] — xem Redirect URIs.

Điều này đặc biệt hữu ích cho các môi trường tạm thời hoặc các client MCP. Xem một ví dụ triển khai trong Hugging Chat.

OAuth mã thiết bị

Device code flow cho phép người dùng cấp quyền cho một ứng dụng trên một thiết bị (ví dụ: CLI) bằng cách nhập một mã ngắn trên một thiết bị khác (ví dụ: điện thoại hoặc trình duyệt). Không yêu cầu redirect URI hay trình duyệt trên thiết bị đang chạy ứng dụng.

Kiểm thử bằng một kịch bản mẫu

Bạn có thể kiểm tra ứng dụng OAuth mã thiết bị bằng script sau. Thay <Client ID> bằng client ID của ứng dụng. Đối với ứng dụng công khai (không có secret), script hoạt động ngay. Đối với ứng dụng có secret, thêm header Authorization: Basic (Base64 của client_id:client_secret) vào cả yêu cầu thiết bị và token.

#!/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"

Đối với các ứng dụng OAuth có client secret, hãy bao gồm header Authorization: Basic (với client_id:client_secret được mã hóa Base64) trong cả yêu cầu device code và yêu cầu token.

Phạm vi hiện được hỗ trợ

Các phạm vi được hỗ trợ hiện tại là:

• 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.)
• 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.

Tất cả các thông tin khác có sẵn trong metadata OpenID.

Vui lòng liên hệ với chúng tôi nếu bạn cần thêm các phạm vi khác.

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. ID của tổ chức có sẵn trong trường orgs[].sub của phản hồi userinfo.

Đồng bộ thành viên tổ chức dưới dạng nhóm

Phản hồi userinfo (https://huggingface.co/oauth/userinfo) bao gồm một claim groups: tên của các tổ chức mà người dùng thuộc về, dưới dạng một mảng các chuỗi.

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

Nhiều client OIDC (ví dụ: Discourse, Grafana, Argo CD, Vault, Kubernetes) có thể đồng bộ thành viên nhóm từ một claim chứa mảng các chuỗi, và thường được cấu hình với claim groups. Bạn có thể sử dụng nó để ánh xạ các tổ chức Hugging Face sang vai trò hoặc nhóm trong ứng dụng của bạn. Để biết thêm chi tiết về từng tổ chức (ID, vai trò, v.v.), hãy sử dụng trường orgs thay thế.

Một vài điều cần lưu ý:

• Claim groups chỉ được trả về bởi endpoint userinfo, không có trong ID token.
• Nó chứa tên tổ chức, không phải ID. Nếu một tổ chức được đổi tên, các ánh xạ sử dụng tên cũ của nó sẽ không còn khớp nữa.
• Các nhóm tài nguyên không được bao gồm. Đối với các tổ chức sử dụng gói trả phí, các nhóm tài nguyên và vai trò của người dùng được liệt kê trong orgs[].resourceGroups.

Thương hiệu

Bạn có thể tự do sử dụng thiết kế riêng cho nút. Dưới đây là một số hình ảnh SVG được cung cấp một cách hữu ích.

Xem các huy hiệu của chúng tôi kèm theo hướng dẫn để tích hợp chúng vào markdown hoặc HTML.

Trao đổi Token cho Tổ chức (RFC 8693)

Tính năng này là một phần của gói Enterprise.

Token Exchange cho phép các tổ chức cấp phát access token cho thành viên của họ một cách tự động mà không cần sự đồng ý tương tác từ người dùng. Tính năng này đặc biệt hữu ích khi xây dựng các công cụ nội bộ, pipeline tự động hóa và các tích hợp doanh nghiệp cần truy cập tài nguyên của Hugging Face thay mặt cho thành viên tổ chức.

Nếu bạn chỉ cần xác thực không cần khóa từ workflow CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — mà không cần phát hành token cho từng thành viên — hãy xem Trusted Publishers, cũng sử dụng /oauth/token nhưng lấy id_token OIDC do nhà cung cấp CI của bạn tạo làm subject token (không yêu cầu gói Enterprise, không cần thông tin xác thực client).

Tính năng này triển khai RFC 8693 - OAuth 2.0 Token Exchange, một giao thức chuẩn cho các kịch bản trao đổi token.

Các trường hợp sử dụng

Token Exchange được thiết kế cho các kịch bản mà tổ chức của bạn cần:

• Xây dựng các nền tảng nội bộ: Tạo các bảng điều khiển hoặc cổng truy cập các tài nguyên của Hugging Face thay mặt cho các thành viên trong nhóm của bạn, mà không yêu cầu mỗi người dùng phải xác thực thủ công.
• Tự động hóa các pipeline CI/CD: Phát hành các token có thời hạn ngắn và phạm vi hạn chế cho các quy trình tự động cần đẩy mô hình hoặc bộ dữ liệu lên các kho của tổ chức.
• Tích hợp với hệ thống danh tính doanh nghiệp: Kết nối nhà cung cấp danh tính hiện có của bạn với Hugging Face bằng cách phát hành token dựa trên danh mục người dùng nội bộ.
• Thực hiện kiểm soát truy cập tùy chỉnh: Xây dựng middleware phát hành token với các phạm vi cụ thể dựa trên chính sách nội bộ của tổ chức bạn.

Cách hoạt động

1. Tổ chức của bạn có một ứng dụng OAuth được liên kết với tổ chức của bạn và có đặc quyền token-exchange.
2. Dịch vụ backend của bạn xác thực với ứng dụng OAuth này bằng thông tin xác thực của client.
3. Dịch vụ của bạn yêu cầu một access token cho một thành viên tổ chức cụ thể (được xác định bằng email).
4. Hugging Face xác minh người dùng là thành viên của tổ chức của bạn và phát hành một token có phạm vi.
5. Token được phát hành chỉ có thể truy cập các tài nguyên trong phạm vi của tổ chức bạn.

Yêu cầu tiên quyết

Để sử dụng Token Exchange, bạn cần một ứng dụng OAuth gắn với tổ chức có đặc quyền token-exchange. Hãy liên hệ với bộ phận hỗ trợ của Hugging Face để thiết lập một ứng dụng OAuth đủ điều kiện cho tổ chức của bạn.

Sau khi cấu hình, bạn sẽ nhận được:

• Một Client ID (ví dụ: a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Một Client Secret (hãy giữ bí mật này an toàn!)

Quản trị viên tổ chức có thể quản lý ứng dụng OAuth sau khi tạo, bao gồm việc làm mới client secret và cấu hình thời hạn token. Ứng dụng được liệt kê trong phần OAuth Apps của cài đặt tổ chức của bạn, và các thay đổi đối với ứng dụng sẽ được ghi lại trong audit logs của tổ chức.

Xác thực

Token Exchange sử dụng HTTP Basic Authentication với thông tin xác thực ứng dụng OAuth của bạn. Tạo tiêu đề ủy quyền bằng cách mã hóa Base64 chuỗi client_id:client_secret của bạn:

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

Phát hành token qua email

Để cấp một token truy cập cho một thành viên tổ chức bằng cách sử dụng địa chỉ email của họ:

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"

Phản hồi

Yêu cầu thành công sẽ trả về một token truy cập:

{
  "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"
}

Trường id_token được bao gồm khi phạm vi openid được yêu cầu.

Sau đó, bạn có thể sử dụng token này để thực hiện các yêu cầu API thay mặt cho người dùng:

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

Kiểm soát phạm vi

Mặc định, token được phát hành sẽ kế thừa tất cả các phạm vi (scopes) đã cấu hình trên ứng dụng OAuth. Bạn có thể yêu cầu các phạm vi cụ thể bằng cách thêm tham số scope. Xem Các phạm vi được hỗ trợ hiện tại để biết các giá trị khả dụng.

Quyền hiệu lực của token bị giới hạn bởi cả phạm vi được yêu cầu lẫn vai trò của người dùng trong tổ chức.

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"

Tuân theo nguyên tắc đặc quyền tối thiểu: chỉ yêu cầu các phạm vi mà ứng dụng của bạn thực sự cần.

Các cân nhắc về bảo mật

Các token được phát hành thông qua Token Exchange có các hạn chế bảo mật tích hợp sẵn:

• Phạm vi tổ chức: Token chỉ có thể truy cập các tài nguyên trong tổ chức của bạn (các model, datasets, Spaces và collections do tổ chức sở hữu). Bên ngoài tổ chức, quyền truy cập chỉ ở chế độ đọc và bị giới hạn ở: các collections công khai từ bất kỳ người dùng hoặc tổ chức nào, và các repos gated công khai mà người dùng đã được cấp quyền truy cập riêng.
• Không có quyền truy cập cá nhân: Token không thể truy cập các kho riêng tư cá nhân của người dùng hoặc các kho riêng tư từ các tổ chức khác.
• Thời hạn ngắn: Token hết hạn sau 8 giờ theo mặc định. Quản trị viên tổ chức có thể cấu hình thời hạn token (tối đa 30 ngày) trong cài đặt ứng dụng OAuth. Không cung cấp token làm mới.
• Được kiểm toán: Tất cả các lần trao đổi token đều được ghi log và hiển thị trong nhật ký kiểm toán của tổ chức bạn.

Hãy bảo vệ cẩn thận thông tin xác thực ứng dụng OAuth của bạn. Bất kỳ ai có quyền truy cập vào bí mật client của bạn đều có thể phát hành token cho bất kỳ thành viên nào trong tổ chức của bạn.

Phản hồi lỗi

Tham khảo

Loại cấp quyền:

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

Tham số yêu cầu (subject_token_type):

Trường phản hồi (issued_token_type):

Tài liệu liên quan:

• RFC 8693 - OAuth 2.0 Token Exchange
• Nhật ký kiểm toán