Quản lý Tokens

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

Quản lý Tokens cho phép quản trị viên tổ chức giám sát các token truy cập trong tổ chức của họ, đảm bảo truy cập an toàn vào các tài nguyên của tổ chức.

Đối với trải nghiệm của thành viên khi các chính sách quản lý token đang có hiệu lực — bao gồm cách kiểm tra trạng thái token, các lỗi có thể gặp phải, và cách việc từ chối hoặc thu hồi ảnh hưởng đến token — hãy xem Tokens trong tổ chức có chính sách quản lý token.

Xem và quản lý token truy cập

Tính năng liệt kê token hiển thị tất cả các token truy cập trong tổ chức của bạn. Quản trị viên có thể:

• Theo dõi mức sử dụng token và xác định hoặc ngăn ngừa các rủi ro bảo mật tiềm ẩn:
  • Truy cập trái phép vào các tài nguyên riêng tư (“rò rỉ”)
  • Phạm vi truy cập quá rộng
  • Vệ sinh token không tối ưu (ví dụ: các token chưa được xoay vòng trong thời gian dài)
• Xác định các token không hoạt động hoặc không được sử dụng

Token chi tiết hiển thị các quyền cụ thể của chúng:

Token đã bị thu hồi sẽ bị ẩn khỏi danh sách theo mặc định. Sử dụng công tắc Hiển thị token đã thu hồi phía trên danh sách để bao gồm chúng trong chế độ xem.

Một huy hiệu trạng thái REVOKED sẽ được hiển thị cho bất kỳ token nào đã bị thu hồi, bất kể chính sách token của tổ chức. Các huy hiệu PENDING, APPROVED và DENIED chỉ xuất hiện trong các tổ chức có bật chính sách “Require administrator approval”, vì các trạng thái đó chỉ được tạo ra bởi luồng phê duyệt.

Chính sách Token

Quản trị viên của tổ chức Team & Enterprise có thể áp dụng các chính sách sau:

Xem xét ủy quyền Token

Khi chính sách token được đặt thành “Require administrator approval”, quản trị viên tổ chức có thể xem xét chi tiết của tất cả các token chi tiết (fine-grained) đang truy cập các tài nguyên thuộc sở hữu của tổ chức và phê duyệt hoặc từ chối quyền truy cập. Khi một token mới chuyển sang trạng thái chờ, tối đa 50 quản trị viên tổ chức có địa chỉ email đã xác nhận sẽ nhận được thông báo kèm liên kết trực tiếp đến trang xem xét token. Không có thông báo nào được gửi khi một token được tự động phê duyệt (ví dụ: vì người tạo là quản trị viên tổ chức).

• Các token Chờ xử lý đang chờ quyết định từ quản trị viên
• Các token Đã được phê duyệt đã được cấp quyền và đang hoạt động
• Các token Denied đã bị chặn truy cập vào tài nguyên của tổ chức

Khi một token được phê duyệt hoặc từ chối, chủ sở hữu token sẽ nhận được thông báo qua email.

Việc từ chối không phải là vĩnh viễn: một token bị từ chối có thể được một quản trị viên phê duyệt lại sau đó, khôi phục quyền truy cập của nó. Tương tự, một token đã được phê duyệt có thể bị từ chối vào bất kỳ lúc nào, điều này sẽ ngay lập tức thu hồi quyền truy cập dựa trên phê duyệt của nó.

Tên token chỉ hiển thị cho quản trị viên khi chính sách “Yêu cầu phê duyệt của quản trị viên” được bật.

Những gì thành viên nhìn thấy khi bị chặn

Các thành viên có token ở trạng thái chờ phê duyệt hoặc bị từ chối sẽ nhận lỗi 403 khi truy cập tài nguyên của tổ chức: “Do chính sách token của tổ chức, token của bạn cần được tổ chức phê duyệt trước khi bạn có thể truy cập tài nguyên này.”

Thông báo lỗi giống nhau cho cả trạng thái chờ và bị từ chối. Để xem trạng thái, các thành viên có thể chuyển đến trang chỉnh sửa của token tương ứng. Trang cài đặt quản lý token của quản trị viên tổ chức hiển thị các huy hiệu trạng thái cho tất cả token của thành viên.

Từ chối vs. Thu hồi

Quản trị viên có hai cách để xóa quyền truy cập của một token vào tổ chức:

Sử dụng deny khi quản lý quyền truy cập trong luồng phê duyệt (token sẽ chuyển sang trạng thái denied và có thể được phê duyệt lại sau đó). Sử dụng revoke khi bạn cần cắt đứt vĩnh viễn quyền truy cập của token vào tổ chức.

Liệt kê Token qua API

Danh sách token hiển thị trong giao diện cài đặt cũng có thể truy cập theo cách lập trình:

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
curl -H "Authorization: Bearer ${ADMIN_HF_TOKEN}" \
  "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens"

Phản hồi là một mảng các token truy cập thành viên. Xem tham chiếu OpenAPI để biết lược đồ đầy đủ: GET /api/organizations/<name>/settings/tokens

Mặc định, các token đã bị thu hồi sẽ bị ẩn; hãy truyền q=status:all để bao gồm chúng, giống như công tắc Hiển thị token đã thu hồi trong giao diện.

Thu hồi Token

Tính năng này thuộc gói Enterprise trở lên.

Quản trị viên tổ chức có thể thu hồi token truy cập của bất kỳ thành viên nào từ trang chi tiết token. Việc thu hồi khả dụng bất kể tổ chức có sử dụng chính sách “Require administrator approval” hay không. Token đã bị thu hồi không còn khả năng truy cập các tài nguyên của tổ chức, nhưng vẫn hoạt động ở những nơi khác. Chủ sở hữu token sẽ nhận được thông báo qua email khi token bị thu hồi.

Token đã bị thu hồi vẫn ở trạng thái bị thu hồi ngay cả khi chính sách token của tổ chức sau đó được thay đổi hoặc tắt. Việc thu hồi là vĩnh viễn ở cấp độ tổ chức — không có thao tác hủy thu hồi. Nếu một thành viên cần khôi phục quyền truy cập, họ phải xóa token đã bị thu hồi và tạo một token mới. Nếu tổ chức sử dụng chính sách “Yêu cầu phê duyệt của quản trị viên”, token mới sẽ bắt đầu ở trạng thái chờ và cần được quản trị viên phê duyệt.

Thành viên có token bị thu hồi sẽ nhận được lỗi 403 với thông báo: “Token của bạn đã bị quản trị viên tổ chức thu hồi, bạn không còn quyền truy cập vào tài nguyên của tổ chức. Vui lòng liên hệ với họ để biết thêm thông tin.” Thông báo này được hiển thị bất kể tổ chức có sử dụng chính sách “Require administrator approval” hay không.

Thu hồi thông qua API

Quản trị viên cũng có thể thu hồi một token một cách tự động bằng cách sử dụng id của token đó. Điều này hữu ích cho các quy trình tự động hóa, nơi một token cần được thu hồi ngay lập tức.

# ORG_NAME should be your organization name and ADMIN_HF_TOKEN an admin's access token
# TOKEN_ID is the 24-character id shown on the org token settings page (or returned by the tokens listing API)
curl -X POST "https://huggingface.co/api/organizations/${ORG_NAME}/settings/tokens/${TOKEN_ID}/revoke" \
  -H "Authorization: Bearer ${ADMIN_HF_TOKEN}"

Quản trị viên không thể thu hồi token của chính mình: yêu cầu có id token khớp với token được sử dụng để xác thực sẽ bị từ chối với lỗi 403.

Endpoint này chỉ thu hồi quyền truy cập của token vào tổ chức của bạn; token vẫn hoạt động cho các tài nguyên khác của chủ sở hữu. Để vô hiệu hóa token bị lộ ở mọi nơi, hãy sử dụng POST /api/credentials/revoke thay thế, phương thức này không yêu cầu xác thực và chấp nhận một lô các giá trị token thô.

Phát hành Token bằng chương trình

Tính năng này thuộc gói Enterprise trở lên.

Đối với các tổ chức cần cấp phát token truy cập một cách tự động cho thành viên của họ (ví dụ: cho các nền tảng nội bộ, pipeline CI/CD, hoặc các tích hợp tùy chỉnh), hãy xem OAuth Token Exchange. Tính năng của gói Enterprise này cho phép các dịch vụ backend của bạn cấp phát các token có phạm vi cho thành viên tổ chức mà không yêu cầu sự đồng ý tương tác từ người dùng.

Tài khoản dịch vụ

Tính năng này thuộc gói Enterprise trở lên.

Đối với quyền truy cập tự động thuộc về tổ chức thay vì một thành viên cá nhân, quản trị viên có thể tạo Service Accounts và phát hành các token chi tiết được giới hạn phạm vi theo tài nguyên của tổ chức bạn.