# OAuth et FastAPI

OAuth est un standard ouvert pour la délégation d'accès, couramment utilisé pour accorder aux applications un accès limité aux informations d'un utilisateur sans exposer ses identifiants. Combiné à FastAPI, il permet de créer des API sécurisées qui autorisent les utilisateurs à se connecter à l'aide de fournisseurs d'identité externes tels que Google ou GitHub. Dans un scénario habituel :
- FastAPI définit les points de terminaison de l'API et gère les requêtes HTTP.
- OAuth est intégré à l'aide de bibliothèques telles que fastapi.security ou d'outils externes tels que Authlib.
- Lorsqu’un utilisateur souhaite se connecter, FastAPI le redirige vers la page de connexion du fournisseur OAuth.
- Après une connexion réussie, le fournisseur redirige avec un jeton.
- FastAPI vérifie ce jeton et l’utilise pour autoriser l’utilisateur ou récupérer les données de son profil.

Cette approche permet d'éviter de manipuler directement les mots de passe et de confier la gestion des identités à des fournisseurs de confiance.

# Intégration OAuth de Hugging Face dans FastAPI

Ce module fournit des outils pour intégrer l’OAuth de Hugging Face dans une application FastAPI. Il permet l’authentification des utilisateurs via la plateforme Hugging Face, incluant un comportement simulé pour le développement local et le flux OAuth réel pour les Spaces.

## Vue d'ensemble d'OAuth

La fonction `attach_huggingface_oauth` ajoute des points de terminaison de connexion, de déconnexion et de rappel à votre application FastAPI. Utilisée dans un Space, elle se connecte au système OAuth de Hugging Face. Utilisée localement, elle injecte un utilisateur simulé. Cliquez ici pour en savoir plus sur [l’ajout d’une option de connexion avec HF à votre Space](https://huggingface.co/docs/hub/en/spaces-oauth)

### Comment l'utiliser ?

```python
from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth
from fastapi import FastAPI, Request

app = FastAPI()
attach_huggingface_oauth(app)

@app.get("/")
def greet_json(request: Request):
    oauth_info = parse_huggingface_oauth(request)
    if oauth_info is None:
        return {"msg": "Not logged in!"}
    return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"}
```

> [!TIP]
> Vous pourriez également être intéressé par [un exemple pratique illustrant OAuth en action](https://huggingface.co/spaces/Wauplin/fastapi-oauth/blob/main/app.py). Pour une implémentation plus complète, consultez l'Espace [medoidai/GiveBackGPT](https://huggingface.co/spaces/medoidai/GiveBackGPT) qui met en œuvre l'OAuth de HF dans une application à grande échelle.

### attach_huggingface_oauth[[huggingface_hub.attach_huggingface_oauth]]

#### huggingface_hub.attach_huggingface_oauth[[huggingface_hub.attach_huggingface_oauth]]

```python
huggingface_hub.attach_huggingface_oauth(app: fastapi.FastAPI, route_prefix: str = '/')
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_oauth.py#L124)

Ajoutez des points de terminaison OAuth à une application FastAPI pour permettre la connexion OAuth avec Hugging Face.

Comment l'utiliser :
- Appelez cette méthode sur votre application FastAPI pour ajouter les points de terminaison OAuth.
- Dans vos gestionnaires de route, appelez `parse_huggingface_oauth(request)` pour récupérer les informations OAuth.
- Si l'utilisateur est connecté, un objet [OAuthInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/oauth#huggingface_hub.OAuthInfo) contenant les informations de l'utilisateur est renvoyé. Sinon, `None` est renvoyé.
- Dans votre application, assurez-vous d'ajouter des liens vers `/oauth/huggingface/login` et `/oauth/huggingface/logout` pour que l'utilisateur puisse se connecter et se déconnecter.

Exemple :
```py
from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth

# Create a FastAPI app
app = FastAPI()

# Add OAuth endpoints to the FastAPI app
attach_huggingface_oauth(app)

# Add a route that greets the user if they are logged in
@app.get("/")
def greet_json(request: Request):
    # Retrieve the OAuth info from the request
    oauth_info = parse_huggingface_oauth(request)  # e.g. OAuthInfo dataclass
    if oauth_info is None:
        return {"msg": "Not logged in!"}
    return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"}
```

### parse_huggingface_oauth[[huggingface_hub.parse_huggingface_oauth]]

#### huggingface_hub.parse_huggingface_oauth[[huggingface_hub.parse_huggingface_oauth]]

```python
huggingface_hub.parse_huggingface_oauth(request: fastapi.Request)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_oauth.py#L191)

Retourne les informations d'un utilisateur connecté sous forme d'objet [OAuthInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/oauth#huggingface_hub.OAuthInfo).

Pour la flexibilité et la pérennité, cette méthode est très tolérante dans son analyse et ne lève pas d’erreurs. Les champs manquants sont définis sur `None` sans avertissement.

Retourne `None` si l'utilisateur n'est pas connecté (aucune information dans le cookie de session).

Voir [attach_huggingface_oauth()](/docs/huggingface_hub/v2.4.0/fr/package_reference/oauth#huggingface_hub.attach_huggingface_oauth) pour un exemple d’utilisation de cette méthode.

### OAuthOrgInfo[[huggingface_hub.OAuthOrgInfo]]

#### huggingface_hub.OAuthOrgInfo[[huggingface_hub.OAuthOrgInfo]]

```python
huggingface_hub.OAuthOrgInfo(sub: str, name: str, preferred_username: str, picture: str, plan: str | None = None, can_pay: bool | None = None, role_in_org: str | None = None, security_restrictions: list[typing.Literal['ip', 'token-policy', 'mfa', 'sso']] | None = None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_oauth.py#L23)

**Paramètres :**

sub (`str`) : Identifiant unique de l'organisation. Champ OpenID Connect.

name (`str`) : Nom complet de l'organisation. Champ OpenID Connect.

preferred_username (`str`) : Nom d'utilisateur de l'organisation. Champ OpenID Connect.

picture (`str`) : URL de la photo de profil de l'organisation. Champ OpenID Connect.

plan (`str`, *facultatif*) : Le plan de l'organisation (par exemple, "enterprise", "team"). Champ Hugging Face.

can_pay (`Optional[bool]`, *facultatif*) : Indique si l'organisation a une méthode de paiement configurée. Champ Hugging Face.

role_in_org (`Optional[str]`, *facultatif*) : Le rôle de l'utilisateur au sein de l'organisation. Champ Hugging Face.

security_restrictions (`Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]]`, *facultatif*) : Tableau des restrictions de sécurité que l'utilisateur n'a pas encore complétées pour cette organisation. Valeurs possibles : "ip", "token-policy", "mfa", "sso". Champ Hugging Face.

Informations sur une organisation liée à un utilisateur connecté via OAuth.

### OAuthUserInfo[[huggingface_hub.OAuthUserInfo]]

#### huggingface_hub.OAuthUserInfo[[huggingface_hub.OAuthUserInfo]]

```python
huggingface_hub.OAuthUserInfo(sub: str, name: str, preferred_username: str, email_verified: bool | None, email: str | None, picture: str, profile: str, website: str | None, is_pro: bool, can_pay: bool | None, orgs: list[huggingface_hub._oauth.OAuthOrgInfo] | None)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_oauth.py#L57)

**Paramètres :**

sub (`str`) : Identifiant unique de l'utilisateur, même en cas de renommage. Champ OpenID Connect.

name (`str`) : Le nom complet de l'utilisateur. Champ OpenID Connect.

preferred_username (`str`) : Le nom d'utilisateur de l'utilisateur. Champ OpenID Connect.

email_verified (`Optional[bool]`, *facultatif*) : Indique si l'e-mail de l'utilisateur est vérifié. Champ OpenID Connect.

email (`Optional[str]`, *facultatif*) : L'adresse e-mail de l'utilisateur. Champ OpenID Connect.

picture (`str`) : URL de la photo de profil de l'utilisateur. Champ OpenID Connect.

profile (`str`) : L'URL du profil de l'utilisateur. Champ OpenID Connect.

website (`Optional[str]`, *facultatif*) : L'URL du site web de l'utilisateur. Champ OpenID Connect.

is_pro (`bool`) : Indique si l'utilisateur est un utilisateur pro. Champ Hugging Face.

can_pay (`Optional[bool]`, *facultatif*) : Indique si l'utilisateur a configuré un moyen de paiement. Champ Hugging Face.

orgs (`Optional[list[OrgInfo]]`, *facultatif*) : Liste des organisations dont l'utilisateur est membre. Champ Hugging Face.

Informations sur un utilisateur connecté via OAuth.

### OAuthInfo[[huggingface_hub.OAuthInfo]]

#### huggingface_hub.OAuthInfo[[huggingface_hub.OAuthInfo]]

```python
huggingface_hub.OAuthInfo(access_token: str, access_token_expires_at: datetime, user_info: OAuthUserInfo, state: str | None, scope: str)
```

[Source](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_oauth.py#L100)

**Paramètres :**

access_token (`str`) : Le jeton d'accès.

access_token_expires_at (`datetime.datetime`) : Date d'expiration du jeton d'accès.

user_info ([OAuthUserInfo](/docs/huggingface_hub/v2.4.0/fr/package_reference/oauth#huggingface_hub.OAuthUserInfo)) : Les informations de l'utilisateur.

state (`str`, *facultatif*) : État transmis au fournisseur OAuth dans la requête initiale adressée au fournisseur OAuth.

scope (`str`) : Portée accordée.

Informations sur la connexion OAuth.