# 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](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc), permettant ainsi aux utilisateurs de se connecter avec leur compte HF.

Cela permet de nouvelles utilisations pour votre Space. Par exemple, combiné à [Storage Buckets](https://huggingface.co/docs/hub/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.

> [!TIP]
> 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](https://www.gradio.app/guides/sharing-your-app#o-auth-login-via-hugging-face).

> [!TIP]
> 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](./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 :

```yaml
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](./spaces-config-reference) pour plus d'informations.

Cela ajoutera les [variables d’environnement](https://huggingface.co/docs/hub/spaces-overview#built-in-environment-variables) 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`](https://huggingface.co/.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](https://huggingface.co/docs/hub/spaces-overview#built-in-environment-variables) 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](https://huggingface.co/docs/inference-providers/index) au nom de l'utilisateur.
- `read-endpoints` : Consulter les [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) 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](https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs)
- `webhooks` : Gérer les [webhooks](https://huggingface.co/docs/huggingface_hub/main/en/guides/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](https://github.com/lepture/authlib), [NodeJS](https://github.com/panva/node-openid-client)) 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](https://www.gradio.app/guides/sharing-your-app#o-auth-login-via-hugging-face) et à [huggingface.js](https://huggingface.co/docs/huggingface.js/hub/README#oauth-login).

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

> [!WARNING]
> 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 :

- [Application de test Gradio](https://huggingface.co/spaces/Wauplin/gradio-oauth-test)
- [HuggingChat (NodeJS/SvelteKit)](https://huggingface.co/spaces/huggingchat/chat-ui)
- [Widgets d’inférence (Auth.js/SvelteKit)](https://huggingface.co/spaces/huggingfacejs/inference-widgets) utilise l’étendue `inference-api` pour effectuer des requêtes d’inférence au nom de l’utilisateur.
- [Côté client dans un espace statique (huggingface.js)](https://huggingface.co/spaces/huggingfacejs/client-side-oauth) - exemple JavaScript très simple.

Exemple de code JS :

```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);
```