Se connecter avec Hugging Face

Vous pouvez utiliser le flux HF OAuth / OpenID connect pour créer un flux « Se connecter avec HF » sur n’importe quel site web ou application.

Cela permettra aux utilisateurs de se connecter à votre site web ou à votre application en utilisant leur compte HF, en cliquant sur un bouton similaire à celui-ci :

Après avoir cliqué sur ce bouton, vos utilisateurs verront apparaître une fenêtre modale de permissions pour autoriser votre application :

Créer une application oauth

Vous pouvez créer votre application dans vos paramètres :

Applications OAuth appartenant à une organisation

Cette fonctionnalité fait partie des plans Team & Enterprise.

Les applications OAuth peuvent également appartenir à une organisation plutôt qu'à un compte individuel. C'est utile pour les applications que votre équipe maintient ensemble, car elles restent associées à l'organisation au lieu de dépendre du compte d'un seul membre.

Les administrateurs d’organisation peuvent créer et gérer les applications appartenant à l’organisation depuis la section OAuth Apps des paramètres de l’organisation (https://huggingface.co/organizations/<your-org>/settings/applications). Tous les administrateurs de l’organisation peuvent modifier l’application, régénérer son secret client ou la supprimer. La liste des applications indique quel membre a créé chaque application, et les modifications apportées aux applications sont consignées dans les journaux d’audit de l’organisation.

La même page répertorie également l'application Token Exchange de l’organisation, si celle-ci a été configurée.

Vous pouvez également transférer une application OAuth existante dont vous êtes propriétaire vers une organisation dont vous êtes administrateur, depuis la section Transférer vers une organisation de la page de paramètres de l’application. L’organisation doit être sur un plan Team ou Enterprise. Après le transfert, l’application est gérée par tous les administrateurs de l’organisation. Son identifiant client, son secret client ainsi que ses autorisations et jetons existants restent inchangés, de sorte que votre site web ou votre application continue de fonctionner sans modification. Le transfert ne peut pas être annulé depuis la page de paramètres.

Applications OAuth publiques (sans secret)

Vous pouvez créer ou utiliser des applications OAuth sans secret client. Cela est utile pour les applications natives, les CLI ou d'autres contextes où la conservation d'un secret est peu pratique.

• À la création de l'application : Lors de la création d'une nouvelle application OAuth, vous pouvez choisir de la créer sans secret.
• Après la création : pour une application existante, vous pouvez supprimer le secret client dans les paramètres de l'application. L'application fonctionnera alors en tant qu'application publique.

Les applications publiques s’authentifient uniquement à l’aide de l’identifiant client (par exemple, dans les flux de code d’appareil ou de code d’autorisation avec PKCE). Les applications disposant d’un secret peuvent toujours utiliser ce secret lorsque nécessaire (par exemple, Authorization: Basic pour les requêtes de jeton).

URI de redirection

Le redirect_uri envoyé dans une demande d'autorisation doit correspondre exactement à l'une des URI de redirection enregistrées sur votre application.

Les URI de redirection en boucle locale constituent l’unique exception : pour les URI utilisant le schéma http sur un hôte en boucle locale (localhost, 127.0.0.1 ou [::1]), tout port est accepté au moment de la demande, à condition que tous les autres composants correspondent à une URI enregistrée. Cela suit RFC 8252 §7.3 / OAuth 2.1 et permet aux applications natives, aux CLI et aux clients MCP d’enregistrer une URI sans port, telle que http://localhost/callback, puis d’écouter sur le port éphémère que le système d’exploitation leur attribue (par exemple http://localhost:49282/callback).

Quelques points à garder à l'esprit :

• L’exception ne s’applique qu’au schéma http. Les URI de redirection https et à schéma personnalisé (par ex. myapp://callback) exigent toujours une correspondance exacte, port inclus.
• Les hôtes loopback sont appariés individuellement : une requête vers http://localhost:49282/callback ne correspond pas à un http://127.0.0.1/callback enregistré. Enregistrez les deux si votre application peut utiliser l'un ou l'autre.
• Seul le port peut différer. Le chemin, la requête et les informations utilisateur doivent toujours correspondre exactement.

Si vous hébergez dans Spaces

Si vous hébergez votre application sur Spaces, le flux sera encore plus simple à mettre en œuvre (et intégré directement à Gradio) ; consultez notre guide OAuth Spaces.

Création automatisée d'une application oauth

Hugging Face prend en charge CIMD, alias Client ID Metadata Documents, ce qui vous permet de créer une application oauth pour votre site web de manière automatisée :

• Ajoutez un point de terminaison à votre site web /.well-known/oauth-cimd qui renvoie le JSON suivant :

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

• Utilisez "[your website url]/.well-known/oauth-cimd" en tant qu'identifiant de client et PCKE comme mécanisme d'authentification

Les applications natives et les clients MCP qui reçoivent le code d'autorisation sur un port local peuvent lister des URI de boucle sans port dans redirect_uris, par exemple ["http://localhost/callback", "http://127.0.0.1/callback"] — voir URI de redirection.

Ceci est particulièrement utile pour les environnements éphémères ou les clients MCP. Consultez un exemple d’implémentation dans Hugging Chat.

OAuth du code d'appareil

Le flux de code d’appareil permet aux utilisateurs d’autoriser une application sur un appareil (par exemple, une CLI) en saisissant un code court sur un autre appareil (par exemple, un téléphone ou un navigateur). Aucune URI de redirection ni navigateur sur l’appareil exécutant l’application n’est requis.

Test avec un script d'exemple

Vous pouvez tester une application OAuth par code d’appareil avec le script suivant. Remplacez <Client ID> par l’identifiant client de votre application. Pour les applications publiques (sans secret), le script fonctionne tel quel. Pour les applications avec un secret, ajoutez un en-tête Authorization: Basic (Base64 de client_id:client_secret) aux requêtes d’appareil et de jeton.

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

Pour les applications OAuth disposant d'un secret client, incluez un en-tête Authorization: Basic (avec client_id:client_secret encodé en Base64) à la fois sur la demande de code d'appareil et sur la demande de jeton.

Portées actuellement prises en charge

Les plages actuellement prises en charge sont :

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

Toutes les autres informations sont disponibles dans les métadonnées OpenID.

N'hésitez pas à nous contacter si vous avez besoin de périmètres supplémentaires.

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. L’identifiant de l’organisation est disponible dans le champ orgs[].sub de la réponse userinfo.

Synchronisation de l’affiliation à l’organisation en tant que groupes

La réponse userinfo (https://huggingface.co/oauth/userinfo) inclut une revendication groups : les noms des organisations auxquelles l'utilisateur appartient, sous forme de tableau de chaînes de caractères.

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

De nombreux clients OIDC (par exemple Discourse, Grafana, Argo CD, Vault, Kubernetes) peuvent synchroniser l’appartenance aux groupes à partir d’une revendication contenant un tableau de chaînes de caractères, et sont souvent configurés avec une revendication groups. Vous pouvez l’utiliser pour associer les organisations Hugging Face à des rôles ou des groupes dans votre application. Pour plus de détails sur chaque organisation (ID, rôle, etc.), utilisez plutôt le champ orgs.

Quelques points à garder à l'esprit :

• La revendication groups n'est renvoyée que par le point de terminaison userinfo, et non dans le jeton d'identification.
• Il contient des noms d'organisation, et non des identifiants. Si une organisation est renommée, les correspondances qui utilisent son ancien nom cesseront de fonctionner.
• Les groupes de ressources ne sont pas inclus. Pour les organisations disposant d’un plan payant, les groupes de ressources et les rôles de l’utilisateur sont répertoriés dans orgs[].resourceGroups.

Image de marque

Vous êtes libre d'utiliser votre propre design pour le bouton. Voici quelques images SVG aimablement fournies.

Découvrez nos badges avec des explications pour les intégrer dans du markdown ou du HTML.

Échange de jetons pour les organisations (RFC 8693)

Cette fonctionnalité fait partie de l'offre Enterprise.

Token Exchange permet aux organisations d’émettre des jetons d’accès pour leurs membres de manière programmatique, sans nécessiter de consentement utilisateur interactif. Cette fonctionnalité est particulièrement utile pour la création d’outils internes, de pipelines d’automatisation et d’intégrations d’entreprise qui doivent accéder aux ressources Hugging Face au nom des membres de l’organisation.

Si vous avez uniquement besoin d’une authentification sans clé depuis un workflow CI/CD (GitHub Actions, GitLab CI, CircleCI, …) — sans émission de jetons par membre — consultez Trusted Publishers, qui utilise également /oauth/token mais prend un id_token OIDC émis par votre fournisseur CI comme jeton de sujet (aucun plan Enterprise requis, aucune information d’identification client).

Cette fonctionnalité implémente RFC 8693 - OAuth 2.0 Token Exchange, un protocole standard pour les scénarios d'échange de jetons.

Cas d'usage

Token Exchange est conçu pour les scénarios où votre organisation a besoin de :

• Construire des plateformes internes : Créez des tableaux de bord ou des portails qui accèdent aux ressources Hugging Face au nom de vos membres d'équipe, sans exiger que chaque utilisateur s'authentifie manuellement.
• Automatiser les pipelines CI/CD : Émettre des jetons à durée de vie courte et à portée restreinte pour les workflows automatisés qui doivent pousser des modèles ou des jeux de données vers les dépôts de l'organisation.
• Intégration avec les systèmes d’identité d’entreprise : Reliez votre fournisseur d’identité existant à Hugging Face en émettant des jetons basés sur votre annuaire d’utilisateurs interne.
• Mettre en œuvre des contrôles d’accès personnalisés : créez un middleware qui émet des jetons avec des plages d’action spécifiques en fonction des politiques internes de votre organisation.

Fonctionnement

1. Votre organisation dispose d'une application OAuth liée à votre organisation avec le privilège token-exchange.
2. Votre service backend s’authentifie auprès de cette application OAuth en utilisant les identifiants du client.
3. Votre service demande un jeton d'accès pour un membre spécifique de l'organisation (identifié par son adresse e-mail).
4. Hugging Face vérifie que l'utilisateur est membre de votre organisation et émet un jeton à portée limitée.
5. Le jeton émis ne peut accéder qu’aux ressources dans le périmètre de votre organisation.

Prérequis

Pour utiliser Token Exchange, vous avez besoin d'une application OAuth liée à une organisation et dotée du privilège token-exchange. Contactez le support Hugging Face pour configurer une application OAuth éligible pour votre organisation.

Une fois configuré, vous recevrez :

• Un Client ID (par exemple, a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• Un Client Secret (gardez-le en sécurité !)

Les administrateurs d’organisation peuvent gérer l’application OAuth après sa création, notamment en renouvelant le secret client et en configurant la durée de validité du jeton. L’application est listée dans la section OAuth Apps des paramètres de votre organisation, et les modifications qui y sont apportées sont consignées dans les journaux d’audit de l’organisation.

Authentification

Token Exchange utilise l’authentification HTTP de base avec les identifiants de votre application OAuth. Créez l’en-tête d’autorisation en encodant en Base64 votre 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)

Émission de jetons par e-mail

Pour émettre un jeton d'accès pour un membre d'une organisation en utilisant son adresse e-mail :

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"

Réponse

Une requête réussie renvoie un jeton d'accès :

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

Le champ id_token est inclus lorsque l'étendue openid est demandée.

Vous pouvez ensuite utiliser ce jeton pour effectuer des requêtes API au nom de l'utilisateur :

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

Contrôle de la portée

Par défaut, les jetons émis héritent de tous les étendues configurées sur l'application OAuth. Vous pouvez demander des étendues spécifiques en ajoutant le paramètre scope. Consultez Étendues actuellement prises en charge pour les valeurs disponibles.

Les permissions effectives du jeton sont limitées à la fois par l’étendue demandée et par le rôle de l’utilisateur au sein de l’organisation.

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"

Suivez le principe du moindre privilège : demandez uniquement les étendues dont votre application a réellement besoin.

Considérations relatives à la sécurité

Les jetons émis via l'échange de jetons comportent des restrictions de sécurité intégrées :

• Portée à l’organisation : les jetons ne peuvent accéder qu’aux ressources au sein de votre organisation (modèles, jeux de données, Spaces et collections appartenant à l’organisation). En dehors de l’organisation, l’accès est en lecture seule et limité aux collections publiques de tout utilisateur ou organisation, ainsi qu’aux dépôts publics à accès restreint pour lesquels l’utilisateur a reçu une autorisation individuelle.
• Aucun accès personnel : les jetons ne peuvent pas accéder aux dépôts privés personnels de l’utilisateur ni aux dépôts privés d’autres organisations.
• À durée de vie courte : Les jetons expirent par défaut après 8 heures. Les administrateurs d’organisation peuvent configurer la durée de validité des jetons (jusqu’à 30 jours) dans les paramètres de l’application OAuth. Aucun jeton de rafraîchissement n’est fourni.
• Auditable : Tous les échanges de jetons sont journalisés et visibles dans les journaux d’audit de votre organisation.

Protégez soigneusement les identifiants de votre application OAuth. Toute personne ayant accès à votre secret client peut émettre des jetons pour n'importe quel membre de votre organisation.

Réponses d'erreur

Référence

Type d’octroi :

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

Paramètre de requête (subject_token_type) :

Champ de réponse (issued_token_type) :

Documentation associée :

• RFC 8693 - Échange de jetons OAuth 2.0
• Journaux d'audit