Hugging Face's logo

Hub documentation

Добавление кнопки входа через HF в ваше Space

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Добавление кнопки входа через HF в ваше Space

Вы можете включить встроенный процесс входа в ваш Space, создав и привязав приложение OAuth/OpenID connect, чтобы пользователи могли входить со своим аккаунтом HF.

Это открывает новые сценарии использования для вашего Space. Например, в сочетании с Storage Buckets Space для генеративного ИИ может позволять пользователям входить в систему, чтобы получить доступ к своим предыдущим результатам генерации, доступным только им.

В этом руководстве описан процесс интеграции кнопки Sign-In with HF в любое Space. Если вам нужен быстрый и простой способ реализовать это в Space на базе Gradio, обратите внимание на его встроенную интеграцию.

Вы также можете использовать поток HF OAuth для создания сценария «Вход через HF» на любом сайте или в любом приложении, вне Spaces. Прочитайте нашу общую страницу об OAuth.

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

Вам нужно лишь добавить hf_oauth: true в метаданные вашего Space в файле README.md.

Вот пример метаданных для пространства Gradio:

title: Gradio Oauth Test
emoji: 🏆
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 3.40.0
python_version: 3.10.6
app_file: app.py

hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
# optional, see "Scopes" below. "openid profile" is always included.
hf_oauth_scopes:
 - read-repos
 - gated-repos
 - write-repos
 - manage-repos
 - inference-api
# optional, restrict access to members of specific organizations
hf_oauth_authorized_org: ORG_NAME
hf_oauth_authorized_org:
  - ORG_NAME1
  - ORG_NAME2

Подробнее можно узнать в справочнике по конфигурации.

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

  • OAUTH_CLIENT_ID: идентификатор клиента вашего OAuth-приложения (публичный)
  • OAUTH_CLIENT_SECRET: секрет клиента вашего OAuth-приложения
  • OAUTH_SCOPES: области доступа, доступные вашему OAuth-приложению.
  • OPENID_PROVIDER_URL: URL провайдера OpenID. Метаданные OpenID будут доступны по адресу {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

Как и в случае с любой другой переменной окружения, вы можете использовать их в коде, например, с помощью os.getenv("OAUTH_CLIENT_ID").

URL-адреса перенаправления

Вы можете использовать любой URL перенаправления, если он указывает на ваше Space.

Обратите внимание, что SPACE_HOST доступен в качестве переменной окружения.

Например, в качестве URI перенаправления можно использовать https://{SPACE_HOST}/login/callback.

Области видимости

Следующие области действия всегда включаются для Spaces:

  • openid: Получение ID-токена в дополнение к access-токену.
  • profile: чтение информации из профиля пользователя (имя пользователя, аватар и т. д.)

Эти области действия являются необязательными и могут быть добавлены путём установки hf_oauth_scopes в метаданных вашего Space:

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

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

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

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

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

Добавление кнопки в ваше Space

Теперь у вас есть вся информация, необходимая для добавления кнопки «Вход через HF» в ваше Space. Некоторые библиотеки (Python, NodeJS) могут помочь вам реализовать протокол OpenID/OAuth.

Gradio и huggingface.js также обеспечивают встроенную поддержку, что делает реализацию кнопки Sign-in with HF простой задачей; с соответствующими руководствами можно ознакомиться в документации по gradio и по huggingface.js.

По сути, вам нужно:

  • Перенаправьте пользователя на https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}, где STATE — это случайная строка, которую вам потребуется проверить позже.
  • Обрабатывайте callback по адресу /auth/callback или /login/callback (или по собственному URL callback) и проверяйте параметр state.
  • Используйте параметр запроса code, чтобы получить токен доступа и токен идентификатора с https://huggingface.co/oauth/token (POST-запрос с client_id, code, grant_type=authorization_code и redirect_uri в качестве данных формы, а также с заголовком Authorization: Basic {base64(client_id:client_secret)}).

На кнопке следует использовать target=_blank, чтобы страница входа открывалась в новой вкладке, если только вы не запускаете пространство вне его iframe. В противном случае в некоторых браузерах могут возникать проблемы с cookie.

Примеры:

Пример кода на JS:

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();
}

// You can use oauthResult.accessToken, oauthResult.userInfo among other things
console.log(oauthResult);
Update on GitHub

←Справочник по конфигурации Spaces Рекомендуемые Spaces→