Токены доступа пользователя

Что такое токены доступа пользователя?

User Access Tokens — предпочтительный способ аутентификации приложения или ноутбука в сервисах Hugging Face. Вы можете управлять своими токенами доступа в настройках.

Доступные токены позволяют приложениям и блокнотам выполнять определённые действия, указанные в области действия ролей, показанных ниже:

• fine-grained: токены с этой ролью можно использовать для предоставления детального доступа к конкретным ресурсам, например к конкретной модели или моделям в определённой организации. Такой тип токена полезен в производственных средах, поскольку позволяет использовать собственный токен, не предоставляя доступ ко всем вашим ресурсам.

• read: токены с этой ролью можно использовать только для предоставления доступа на чтение к репозиториям, к которым у вас есть доступ на чтение. Сюда входят публичные и приватные репозитории, которыми владеете вы или организация, членом которой вы являетесь. Используйте эту роль, если вам нужен только доступ на чтение к содержимому Hugging Face Hub (например, при загрузке приватных моделей или выполнении инференса).

• write: токены с этой ролью дополнительно предоставляют права на запись в репозитории, к которым у вас есть права на запись. Используйте этот токен, если вам нужно создавать или отправлять содержимое в репозиторий (например, при обучении модели или изменении карточки модели).

Если вы являетесь членом организации с ролью read/write/admin, ваши User Access Tokens смогут читать и записывать ресурсы в соответствии с разрешениями токена (read/write) и членством в организации (read/write/admin).

Как управлять токенами доступа пользователя?

Чтобы создать токен доступа, перейдите в свои настройки, затем щёлкните на вкладке Access Tokens. Щёлкните на кнопке New token, чтобы создать новый токен доступа пользователя.

Выберите роль и имя для вашего токена, и вот — вы готовы к работе!

Вы можете удалить и обновить токены доступа пользователя, нажав кнопку Manage.

Как использовать токены доступа пользователя?

Существует множество способов использовать User Access Token для доступа к Hugging Face Hub, что обеспечивает необходимую гибкость для создания впечатляющих приложений на его основе.

Токены доступа пользователя могут быть:

• используется вместо пароля для доступа к Hugging Face Hub с помощью git или базовой аутентификации.
• передаётся в качестве bearer token при вызове Inference Providers.
• используется в библиотеках Hugging Face на Python, таких как transformers или datasets:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

Старайтесь не раскрывать токен! Хотя его всегда можно пересоздать, в промежутке любой сможет читать и записывать данные в ваши приватные репозитории, что 💩 Если токен был скомпрометирован, см. Отозвать скомпрометированный токен.

Лучшие практики

Мы рекомендуем создавать один токен доступа для каждого приложения или способа использования. Например, можно использовать отдельный токен для:

• Локальный компьютер.
• Ноутбук Colab.
• Отличный пользовательский сервер инференса.

Таким образом, вы можете отозвать один токен, не затрагивая другие его использования.

Также мы рекомендуем использовать только токены с узким диапазоном прав для продакшен-среды. В случае утечки последствия будут менее серьёзными, а такие токены можно передавать внутри организации, не затрагивая ваш аккаунт.

Например, если вашему приложению в продакшене нужен доступ на чтение к модели с ограниченным доступом, участник вашей организации может запросить доступ к этой модели, а затем создать токен с детализированными правами, предоставляющий доступ только на чтение к указанной модели. Этот токен можно использовать в вашем приложении в продакшене, не предоставляя ему доступ ко всем вашим приватным моделям.

Для CI/CD-конвейеров

Если вам нужен доступ только из CI/CD-конвейера (GitHub Actions, GitLab CI, CircleCI, …), вы можете полностью избежать хранения токена доступа в качестве CI-секрета. См. Trusted Publishers, который в начале каждого запуска обменивает токен идентичности OpenID Connect (OIDC) вашего CI-провайдера на краткосрочный токен Hub — либо с областью действия репозитория (для публикации моделей, наборов данных, Spaces или ядер, либо для их чтения), либо с областью действия пользователя (для чтения ограниченных репозиториев, к которым у вас есть доступ, и получения лимитов частоты запросов вашей учётной записи).

Для организаций Enterprise

Если вашей организации необходимо программно выдавать токены для участников без необходимости каждому пользователю создавать собственный токен, см. OAuth Token Exchange. Эта функция Enterprise-плана идеально подходит для создания внутренних платформ, CI/CD-конвейеров или собственных интеграций, которым требуется доступ к ресурсам Hugging Face от имени участников организации.

Отзыв скомпрометированного токена

Если один из ваших токенов был скомпрометирован, удалите или обновите его на вкладке Access Tokens в настройках.

Если вы нашли чужой токен доступа Hugging Face, вы можете отозвать его с помощью эндпоинта POST /api/credentials/revoke. Для этого не требуются какие-либо права на аккаунт или организацию, которой принадлежит токен.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

В один вызов можно передать несколько значений токенов в массиве credentials, что удобно для конвейеров сканирования секретов, которые сообщают о результатах партиями.

Каждый отправленный токен, совпадающий с существующим, немедленно аннулируется и перестаёт работать везде — в отличие от отзыва на уровне организации, который лишь ограничивает доступ токена к одной организации. Владелец токена получает уведомление по электронной почте и должен создать новый токен для восстановления доступа.

Эндпоинт всегда отвечает 202 Accepted, независимо от того, существовали ли отправленные вами токены, поэтому его ответ нельзя использовать для проверки валидности токена. Повторная отправка того же токена безвредна: повторные вызовы ничего не делают, а владелец получает уведомление только один раз.

Чтобы избежать утечки значений токенов в историю командной строки или логи, передавайте их через переменные окружения или файлы и не вставляйте необработанные токены непосредственно в командную строку.

Токены в организациях с политиками управления токенами

Организации на планах Team и Enterprise могут применять политики токенов, которые влияют на работу ваших токенов при доступе к ресурсам этой организации.

Когда для вашего токена требуется одобрение (организации Team & Enterprise)

При создании токена с узким уровнем доступа, привязанного к организации, требующей одобрения администратором, токен автоматически переходит в состояние Pending. Он не может получать доступ к ресурсам этой организации, пока администратор не одобрит его. Вы получите уведомление по электронной почте, когда ваш токен будет одобрен или отклонен.

Вы можете проверить статус на странице со списком токенов: у ожидающего токена рядом с бейджем разрешений отображается оранжевая иконка песочных часов, а у отклонённого или отозванного токена — красная иконка восклицательного знака. Если токен был отклонён или отозван, на странице редактирования токена также появится красная панель с ошибкой.

Если вы являетесь администратором организации, то токены с детализированными правами доступа, которые вы создаёте с областью действия, ограниченной этой организацией, одобряются автоматически — этап проверки не требуется.

Когда ваш токен отклонён (организации Team & Enterprise)

Если ваш токен отклонён, вы получите уведомление по электронной почте. Токен остаётся в вашем аккаунте и по-прежнему может использоваться для ресурсов вне организации. Отклонённый токен впоследствии может быть одобрен администратором, что восстановит доступ без необходимости создавать новый токен.

При попытке использовать запрещённый токен для доступа к ресурсам организации вы получите ошибку 403.

Когда ваш токен отозван (организации Enterprise)

Отзыв является необратимым. В отличие от отказа, отозванный токен нельзя восстановить. Если ваш токен был отозван, вы должны удалить его и создать новый. Если организация требует одобрения администратора, новый токен будет создан в состоянии ожидания.

При попытке использовать отозванный токен для доступа к ресурсам организации вы получите ошибку 403 с сообщением: «Ваш токен был отозван администратором организации, вы больше не можете получать доступ к ресурсам организации. Пожалуйста, свяжитесь с ними для получения дополнительной информации.»

Отзыв влияет только на организацию, которая его выполнила. Токен продолжает нормально работать для всех остальных ресурсов, к которым он имеет доступ.

Когда ваша организация разрешает использовать только токены с детализированными правами доступа (организации Team & Enterprise)

Если в вашей организации установлена политика, требующая использования токенов с детализированными правами, токены на чтение/запись будут отклоняться с ошибкой 403 при использовании для доступа к ресурсам этой организации.