Hugging Face's logo

Hub documentation

Ajouter un bouton « Se connecter avec HF » à votre Space

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ajouter un bouton « Se connecter avec HF » à votre Space

Vous pouvez activer un flux de connexion intégré dans votre Space en créant et en associant de manière transparente une application OAuth/OpenID connect, permettant ainsi aux utilisateurs de se connecter avec leur compte HF.

Cela permet de nouvelles utilisations pour votre Space. Par exemple, combiné à Storage Buckets, un Space d’IA générative pourrait permettre aux utilisateurs de se connecter pour accéder à leurs générations précédentes, accessibles uniquement à eux.

Ce guide vous guide à travers le processus d’intégration d’un bouton Sign-In with HF dans n’importe quel Space. Si vous recherchez une méthode rapide et simple pour l’implémenter dans un Space Gradio, consultez son intégration intégrée.

Vous pouvez également utiliser le flux OAuth de HF pour créer un flux « Se connecter avec HF » sur n’importe quel site web ou application, en dehors de Spaces. Lisez notre page générale sur OAuth.

Créer une application OAuth

Il vous suffit d’ajouter hf_oauth: true aux métadonnées de votre Space dans votre fichier README.md.

Voici un exemple de métadonnées pour un Space 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

Vous pouvez consulter la documentation de référence de la configuration pour plus d'informations.

Cela ajoutera les variables d’environnement suivantes à votre espace :

  • OAUTH_CLIENT_ID : l'identifiant client de votre application OAuth (public)
  • OAUTH_CLIENT_SECRET : le secret client de votre application OAuth
  • OAUTH_SCOPES : plages d'accès accessibles par votre application OAuth.
  • OPENID_PROVIDER_URL : l’URL du fournisseur OpenID. Les métadonnées OpenID seront disponibles à l’adresse {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

Comme pour toute autre variable d’environnement, vous pouvez les utiliser dans votre code à l’aide de os.getenv("OAUTH_CLIENT_ID"), par exemple.

URL de redirection

Vous pouvez utiliser n'importe quelle URL de redirection, à condition qu'elle cible votre Space.

Notez que SPACE_HOST est disponible en tant que variable d'environnement.

Par exemple, vous pouvez utiliser https://{SPACE_HOST}/login/callback comme URI de redirection.

Portées

Les plages suivantes sont toujours incluses pour Spaces :

  • openid : Reçoit un jeton d'identification en plus du jeton d'accès.
  • profile : Lit les informations du profil de l'utilisateur (nom d'utilisateur, avatar, etc.)

Ces étendues sont facultatives et peuvent être ajoutées en définissant hf_oauth_scopes dans les métadonnées de votre Space :

  • email : Lit l’adresse e-mail de l’utilisateur.
  • read-billing : savoir si l'utilisateur a configuré un moyen de paiement.
  • read-memberships : Lit les organisations auxquelles l'utilisateur appartient et son rôle dans chacune d'entre elles. Cela n'accorde pas l'accès aux paramètres ou aux ressources des organisations.
  • read-repos : Lit les dépôts personnels de l’utilisateur.
  • gated-repos : Lit le contenu des dépôts publics à accès restreint auxquels l’utilisateur a été autorisé. Contrairement à read-repos, cela n’accorde pas l’accès aux dépôts privés.
  • contribute-repos : crée des dépôts et accède à ceux créés par cette application. Ne peut pas accéder à d'autres dépôts à moins que des autorisations supplémentaires ne soient accordées.
  • write-repos : Lecture et écriture des dépôts personnels de l’utilisateur.
  • manage-repos : Gérer entièrement les dépôts personnels de l’utilisateur, y compris leur création et leur suppression.
  • read-collections : Lit les collections personnelles de l’utilisateur.
  • write-collections : Lit et écrit les collections personnelles de l’utilisateur, y compris leur création et leur suppression.
  • inference-api : effectuer des requêtes d'inférence auprès des fournisseurs d'inférence au nom de l'utilisateur.
  • read-endpoints : Consulter les Inference Endpoints de l’utilisateur et effectuer des requêtes d’inférence sur ceux-ci en son nom.
  • write-endpoints : Gère les Inference Endpoints de l’utilisateur, y compris leur création et leur suppression. Inclut l’accès read-endpoints.
  • jobs : Exécuter des jobs
  • webhooks : Gérer les webhooks
  • write-discussions : ouvre des discussions et des Pull Requests au nom de l’utilisateur et interagit avec les discussions (y compris les réactions, la publication/édition de commentaires, la fermeture de discussions, …). Pour ouvrir des Pull Requests sur des dépôts privés, vous devez également demander l’étendue read-repos.

Accéder aux ressources de l'organisation

Par défaut, l'application oauth n'a pas besoin d'accéder aux ressources de l'organisation.

Mais certaines plages comme read-repos ou read-billing s'appliquent également aux organisations.

L’utilisateur peut sélectionner les organisations auxquelles accorder l’accès lors de l’autorisation de l’application. Si vous avez besoin d’accéder à une organisation spécifique, vous pouvez ajouter orgIds=ORG_ID en tant que paramètre de requête à l’URL d’autorisation OAuth. Vous devez remplacer ORG_ID par l’identifiant de l’organisation, disponible dans le champ organizations.sub de la réponse userinfo.

Ajout du bouton à votre Space

Vous disposez désormais de toutes les informations nécessaires pour ajouter un bouton « Sign-in with HF » à votre Space. Certaines bibliothèques (Python, NodeJS) peuvent vous aider à implémenter le protocole OpenID/OAuth.

Gradio et huggingface.js offrent également un support intégré, ce qui rend la mise en œuvre du bouton Sign-in with HF très simple ; vous pouvez consulter les guides associés à gradio et à huggingface.js.

Concrètement, vous devez :

  • Redirigez l'utilisateur vers https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}, où STATE est une chaîne aléatoire que vous devrez vérifier ultérieurement.
  • Gérez le rappel sur /auth/callback ou /login/callback (ou votre propre URL de rappel personnalisée) et vérifiez le paramètre state.
  • Utilisez le paramètre de requête code pour obtenir un jeton d'accès et un jeton d'identification depuis https://huggingface.co/oauth/token (requête POST avec client_id, code, grant_type=authorization_code et redirect_uri en tant que données de formulaire, et avec Authorization: Basic {base64(client_id:client_secret)} en tant qu'en-tête).

Vous devez utiliser target=_blank sur le bouton pour ouvrir la page de connexion dans un nouvel onglet, sauf si vous exécutez l’espace en dehors de son iframe. Sinon, vous pourriez rencontrer des problèmes liés aux cookies sur certains navigateurs.

Exemples :

Exemple de code 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

←Référence de configuration des Spaces Espaces en vedette→