Войти с Hugging Face

Вы можете использовать поток HF OAuth / OpenID connect, чтобы создать поток «Вход через HF» на любом сайте или в любом приложении.

Это позволит пользователям входить на ваш сайт или в приложение с помощью своей учётной записи HF, нажимая на кнопку, похожую на эту:

После нажатия этой кнопки вашим пользователям будет показано модальное окно с запросом разрешений для авторизации вашего приложения:

Создание приложения oauth

Вы можете создать своё приложение в настройках:

OAuth-приложения, принадлежащие организации

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

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

Администраторы организации могут создавать и управлять приложениями, принадлежащими организации, в разделе OAuth Apps настроек организации (https://huggingface.co/organizations/<your-org>/settings/applications). Все администраторы организации могут редактировать приложение, обновлять его client secret или удалять его. В списке приложений отображается, какой член организации создал каждое приложение, а изменения в приложениях фиксируются в audit logs организации.

На той же странице также перечисляется приложение Token Exchange организации, если оно было настроено.

Вы также можете передать существующее OAuth-приложение, которым вы владеете, в организацию, администратором которой вы являетесь, из раздела Передать в организацию на странице настроек приложения. Организация должна быть на тарифном плане Team или Enterprise. После передачи приложением управляют все администраторы организации. Его client ID, client secret, а также существующие авторизации и токены остаются без изменений, поэтому ваш сайт или приложение продолжают работать без каких-либо изменений. Отменить передачу со страницы настроек невозможно.

Публичные OAuth-приложения (без секрета)

Вы можете создавать или использовать OAuth-приложения без клиентского секрета. Это полезно для нативных приложений, CLI или других контекстов, где хранение секрета нецелесообразно.

• При создании приложения: при создании нового OAuth-приложения можно выбрать вариант создания без секрета.
• После создания: для существующего приложения вы можете удалить секрет клиента в настройках приложения. После этого приложение будет работать как публичное.

Публичные приложения аутентифицируются только с помощью client ID (например, в потоках device code или authorization code с PKCE). Приложения, у которых есть secret, по-прежнему могут использовать его при необходимости (например, Authorization: Basic для запросов токена).

URI перенаправления

redirect_uri, отправленный в запросе авторизации, должен точно совпадать с одним из URI перенаправления, зарегистрированных в вашем приложении.

Loopback redirect URIs — единственное исключение: для URI, использующих схему http на loopback-хосте (localhost, 127.0.0.1 или [::1]), при запросе принимается любой порт, при условии, что все остальные компоненты совпадают с зарегистрированным URI. Это соответствует RFC 8252 §7.3 / OAuth 2.1 и позволяет нативным приложениям, CLI и MCP-клиентам регистрировать URI без порта, например http://localhost/callback, а затем слушать на любом эфемерном порте, который назначит операционная система (например, http://localhost:49282/callback).

Обратите внимание на несколько моментов:

• Исключение действует только для схемы http. Для URI перенаправления с использованием https и пользовательских схем (например, myapp://callback) всегда требуется точное совпадение, включая порт.
• Loopback-хосты сопоставляются по отдельности: запрос к http://localhost:49282/callback не соответствует зарегистрированному http://127.0.0.1/callback. Зарегистрируйте оба, если ваше приложение может использовать любой из них.
• Может отличаться только порт. Путь, строка запроса и userinfo должны по-прежнему совпадать точно.

Если вы размещаете в Spaces

Если вы размещаете своё приложение на Spaces, то реализовать этот процесс будет ещё проще (он встроен непосредственно в Gradio); см. наше руководство по OAuth для Spaces.

Автоматическое создание приложения oauth

Hugging Face поддерживает CIMD, также известный как документы метаданных клиента, что позволяет автоматически создавать oauth-приложение для вашего сайта:

• Добавьте на ваш сайт конечную точку /.well-known/oauth-cimd, которая возвращает следующий JSON:

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

• Используйте "[your website url]/.well-known/oauth-cimd" в качестве client ID, а PCKE — в качестве механизма аутентификации

Нативные приложения и MCP-клиенты, которые получают код авторизации на локальном порту, могут указывать в redirect_uris loopback-URI без порта, например ["http://localhost/callback", "http://127.0.0.1/callback"] — см. Redirect URIs.

Это особенно полезно для эфемерных сред или клиентов MCP. Пример реализации — в Hugging Chat.

OAuth с кодом устройства

Поток кода устройства позволяет пользователям авторизовать приложение на одном устройстве (например, в CLI), вводя короткий код на другом устройстве (например, на телефоне или в браузере). URI перенаправления или браузер на устройстве, где запущено приложение, не требуются.

Тестирование с помощью примера скрипта

Вы можете протестировать OAuth-приложение с device-code с помощью следующего скрипта. Замените <Client ID> на идентификатор клиента вашего приложения. Для публичных приложений (без секрета) скрипт работает как есть. Для приложений с секретом добавьте заголовок Authorization: Basic (Base64 от client_id:client_secret) в оба запроса: device и 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"

Для OAuth-приложений, у которых есть секрет клиента, включите заголовок Authorization: Basic (с Base64-кодированным значением client_id:client_secret) как в запросе на код устройства, так и в запросе на токен.

Поддерживаемые области

В настоящее время поддерживаются следующие области:

• openid: Получение ID-токена в дополнение к access-токену.
• profile: чтение информации из профиля пользователя (имя пользователя, аватар и т. д.)
• email: чтение адреса электронной почты пользователя.
• read-billing: позволяет узнать, настроен ли у пользователя способ оплаты.
• read-memberships: чтение списков организаций, в которых состоит пользователь, и его роли в каждой из них. Это не предоставляет доступ к настройкам или ресурсам организаций.
• read-repos: чтение личных репозиториев пользователя.
• gated-repos: чтение содержимого публичных репозиториев с ограниченным доступом, к которым у пользователя есть права. В отличие от read-repos, это не предоставляет доступ к частным репозиториям.
• contribute-repos: создание репозиториев и доступ к тем, которые были созданы этим приложением. Доступ к другим репозиториям невозможен, если не предоставлены дополнительные разрешения.
• write-repos: чтение и запись личных репозиториев пользователя.
• manage-repos: Полное управление личными репозиториями пользователя, включая их создание и удаление.
• read-collections: чтение личных коллекций пользователя.
• write-collections: чтение и запись личных коллекций пользователя, включая их создание и удаление.
• inference-api: Выполнение запросов на инференс к Inference Providers от имени пользователя.
• read-endpoints: Просмотр Inference Endpoints пользователя и выполнение запросов на инференс от его имени.
• write-endpoints: управление Inference Endpoints пользователя, включая их создание и удаление. Включает доступ read-endpoints.
• jobs: Запуск jobs
• webhooks: Управление webhooks
• write-discussions: открытие обсуждений и Pull Requests от имени пользователя, а также взаимодействие с обсуждениями (включая реакции, публикацию/редактирование комментариев, закрытие обсуждений, …). Для открытия Pull Requests в частных репозиториях также требуется запросить область read-repos.

Вся остальная информация доступна в метаданных OpenID.

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

Доступ к ресурсам организации

По умолчанию приложению oauth не требуется доступ к ресурсам организации.

Однако некоторые области, такие как read-repos или read-billing, также применяются к организациям.

Пользователь может выбрать, какие организации предоставить доступ при авторизации приложения. Если вам требуется доступ к конкретной организации, вы можете добавить orgIds=ORG_ID в качестве параметра запроса к URL авторизации OAuth. Идентификатор организации доступен в поле orgs[].sub ответа userinfo.

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

Ответ userinfo (https://huggingface.co/oauth/userinfo) содержит утверждение groups: имена организаций, в которых состоит пользователь, в виде массива строк.

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

Многие OIDC-клиенты (например, Discourse, Grafana, Argo CD, Vault, Kubernetes) могут синхронизировать членство в группах из claim, содержащего массив строк, и часто настраиваются с claim groups. Вы можете использовать его для сопоставления организаций Hugging Face с ролями или группами в вашем приложении. Для получения подробной информации о каждой организации (ID, роль и т. д.) используйте вместо этого поле orgs.

Обратите внимание на несколько моментов:

• Заявление groups возвращается только конечной точкой userinfo, а не в токене ID.
• Он содержит имена организаций, а не их идентификаторы. Если организация переименована, сопоставления, использующие её прежнее имя, перестанут работать.
• Группы ресурсов не включены. Для организаций на платном тарифе группы ресурсов и роли пользователя перечислены в orgs[].resourceGroups.

Брендинг

Вы можете использовать собственный дизайн для кнопки. Ниже представлены полезные SVG-изображения.

Ознакомьтесь с нашими значками и инструкциями по их интеграции в Markdown или HTML.

Обмен токенами для организаций (RFC 8693)

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

Функция Token Exchange позволяет организациям программно выдавать токены доступа для своих участников без необходимости интерактивного подтверждения со стороны пользователя. Это особенно полезно при создании внутренних инструментов, автоматизированных конвейеров и корпоративных интеграций, которым требуется доступ к ресурсам Hugging Face от имени участников организации.

Если вам нужна только аутентификация без ключей из CI/CD-конвейера (GitHub Actions, GitLab CI, CircleCI, …) — без выпуска токенов для каждого участника — см. Trusted Publishers, который также использует /oauth/token, но в качестве subject token принимает OIDC id_token, выпущенный вашим CI-провайдером (не требуется Enterprise-план и учётные данные клиента).

Эта функция реализует RFC 8693 - OAuth 2.0 Token Exchange, стандартный протокол для сценариев обмена токенами.

Сценарии использования

Token Exchange предназначен для сценариев, в которых вашей организации необходимо:

• Создание внутренних платформ: Разрабатывайте дашборды или порталы, которые обращаются к ресурсам Hugging Face от имени членов вашей команды, без необходимости для каждого пользователя выполнять ручную аутентификацию.
• Автоматизация CI/CD-конвейеров: выдавайте токены с ограниченным сроком действия и областью действия для автоматизированных рабочих процессов, которым необходимо отправлять модели или наборы данных в репозитории организации.
• Интеграция с корпоративными системами идентификации: Соедините вашего существующего поставщика идентификации с Hugging Face, выпуская токены на основе вашего внутреннего каталога пользователей.
• Реализуйте собственные средства контроля доступа: создайте промежуточное ПО, которое выпускает токены с определёнными областями действия на основе внутренних политик вашей организации.

Как это работает

1. В вашей организации есть OAuth-приложение, привязанное к организации с привилегией token-exchange.
2. Ваша служба на стороне сервера аутентифицируется с этим приложением OAuth с использованием учётных данных клиента.
3. Ваш сервис запрашивает токен доступа для конкретного участника организации (идентифицированного по электронной почте).
4. Hugging Face проверяет, является ли пользователь членом вашей организации, и выпускает токен с ограниченной областью действия.
5. Выданный токен может получать доступ только к ресурсам в пределах области вашей организации.

Предварительные требования

Для использования Token Exchange вам потребуется OAuth-приложение, привязанное к организации, с привилегией token-exchange. Свяжитесь с поддержкой Hugging Face, чтобы настроить подходящее OAuth-приложение для вашей организации.

После настройки вы получите:

• Идентификатор клиента (Client ID, например, a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Client Secret (храните в секрете!)

Администраторы организации могут управлять приложением OAuth после его создания, включая обновление клиентского секрета и настройку срока действия токена. Приложение отображается в разделе OAuth Apps настроек вашей организации, а все изменения в нём фиксируются в журнале аудита организации.

Аутентификация

Token Exchange использует HTTP Basic Authentication с учётными данными вашего OAuth-приложения. Создайте заголовок авторизации, закодировав в Base64 строку client_id:client_secret:

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

Выпуск токенов по электронной почте

Чтобы выдать токен доступа для участника организации по его адресу электронной почты:

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"

Ответ

Успешный запрос возвращает токен доступа:

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

Поле id_token включается, если запрошена область openid.

Затем вы можете использовать этот токен для выполнения запросов к API от имени пользователя:

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

Контроль области

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

Эффективные разрешения токена ограничены как запрошенным диапазоном (scope), так и ролью пользователя в организации.

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"

Соблюдайте принцип минимальных привилегий: запрашивайте только те области (scopes), которые действительно нужны вашему приложению.

Вопросы безопасности

Токены, выпущенные через Token Exchange, имеют встроенные ограничения безопасности:

• В рамках организации: токены могут получать доступ только к ресурсам внутри вашей организации (модели, наборы данных, Spaces и коллекции, принадлежащие организации). Вне организации доступ только на чтение и ограничен: публичными коллекциями любого пользователя или организации, а также публичными gated-репозиториями, к которым у пользователя есть индивидуально предоставленный доступ.
• Нет доступа к личным ресурсам: токены не могут получать доступ к личным приватным репозиториям пользователя или к приватным репозиториям из других организаций.
• Краткосрочные: по умолчанию токены истекают через 8 часов. Администраторы организации могут настроить срок действия токена (до 30 дней) в настройках OAuth-приложения. Токены обновления не выдаются.
• Аудит: Все обмены токенами фиксируются и отображаются в журнале аудита вашей организации.

Тщательно защищайте учетные данные вашего OAuth-приложения. Любой, у кого есть доступ к вашему client secret, может выдавать токены для любого участника вашей организации.

Ответы с ошибками

Справочник

Тип предоставления:

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

Параметр запроса (subject_token_type):

Поле ответа (issued_token_type):

Связанная документация:

• RFC 8693 — обмен токенами OAuth 2.0
• Журналы аудита