Управление токенами

Эта функция входит в планы Team & Enterprise.

Функция «Управление токенами» позволяет администраторам организации контролировать токены доступа в рамках своей организации, обеспечивая безопасный доступ к ресурсам организации.

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

Просмотр и управление токенами доступа

Функция списка токенов отображает все токены доступа в вашей организации. Администраторы могут:

• Мониторинг использования токенов и выявление или предотвращение потенциальных рисков безопасности:
  • Неавторизованный доступ к закрытым ресурсам («утечки»)
  • Чрезмерно широкие области доступа
  • Неоптимальная гигиена токенов (например, токены, которые не обновлялись долгое время)
• Определение неактивных или неиспользуемых токенов

Токены с детализированными правами отображают свои конкретные разрешения:

Отозванные токены по умолчанию скрыты из списка. Используйте переключатель Показать отозванные токены над списком, чтобы включить их в отображение.

Значок статуса REVOKED отображается для любого отозванного токена независимо от политики токенов организации. Значки PENDING, APPROVED и DENIED появляются только в организациях, где включена политика «Требуется одобрение администратора», поскольку эти состояния создаются только в процессе одобрения.

Политика токенов

Администраторы организаций Team & Enterprise могут принудительно применять следующие политики:

Проверка авторизации токена

Когда политика токенов установлена в значение «Требуется одобрение администратора», администраторы организации могут просматривать сведения обо всех токенах с ограниченным доступом, обращающихся к ресурсам, принадлежащим организации, и одобрять или отклонять доступ. Когда новый токен переходит в состояние ожидания, до 50 администраторов организации с подтвержденными адресами электронной почты получают уведомление с прямой ссылкой на страницу проверки токена. Уведомление не отправляется, если токен одобрен автоматически (например, если создатель является администратором организации).

• Токены Ожидают решения администратора
• Токены Approved были авторизованы и активны
• Токены Denied были заблокированы от доступа к ресурсам организации

Когда токен одобрен или отклонён, его владелец получает уведомление по электронной почте.

Отказ не является постоянным: ранее отклонённый токен может быть одобрен администратором, что восстановит его доступ. Аналогично, уже одобренный токен может быть отклонён в любой момент, что немедленно отменит его доступ, основанный на одобрении.

Имена токенов видны только администраторам, если включена политика «Требуется одобрение администратора».

Что видят участники при блокировке

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

Сообщение об ошибке одинаково для состояний «в ожидании» и «отклонено». Чтобы узнать статус, участники могут перейти на страницу редактирования конкретного токена. На странице настроек управления токенами администратора организации отображаются значки статуса для всех токенов участников.

Отказ vs. Отзыв

Администраторы могут отозвать доступ токена к организации двумя способами:

Используйте deny при управлении доступом в рамках рабочего процесса согласования (токен переходит в состояние denied и может быть одобрен повторно). Используйте revoke, если необходимо навсегда отрезать доступ токена к организации.

Получение списка токенов через API

Список токенов, отображаемый в интерфейсе настроек, также доступен программно:

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

Ответ представляет собой массив токенов доступа участников. Полную схему см. в справочнике OpenAPI: GET /api/organizations/<name>/settings/tokens

По умолчанию отозванные токены скрыты; передайте q=status:all, чтобы включить их, как переключатель Показать отозванные токены в интерфейсе.

Отзыв токенов

Эта функция входит в план Enterprise и выше.

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

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

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

Отозвать через API

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

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

Администратор не может отозвать собственный токен: запрос, в котором идентификатор токена совпадает с токеном, используемым для аутентификации, отклоняется с ошибкой 403.

Этот эндпоинт отзывает только доступ токена к вашей организации; токен продолжает работать для других ресурсов его владельца. Чтобы отозвать скомпрометированный токен во всех местах, используйте вместо этого POST /api/credentials/revoke, который не требует аутентификации и принимает пакет значений сырых токенов.

Программная выдача токенов

Эта функция входит в план Enterprise и выше.

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

Служебные учётные записи

Эта функция входит в план Enterprise и выше.

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