# OAuth и FastAPI

OAuth — это открытый стандарт делегирования доступа, который обычно используется для предоставления приложениям ограниченного доступа к информации пользователя без раскрытия его учётных данных. В сочетании с FastAPI он позволяет создавать защищённые API, в которых пользователи могут входить с помощью внешних провайдеров идентификации, таких как Google или GitHub. В типичном сценарии:
- FastAPI определяет конечные точки API и обрабатывает HTTP-запросы.
- OAuth интегрируется с использованием библиотек, таких как fastapi.security, или внешних инструментов, таких как Authlib.
- Когда пользователь хочет войти в систему, FastAPI перенаправляет его на страницу входа провайдера OAuth.
- После успешного входа провайдер перенаправляет обратно с токеном.
- FastAPI проверяет этот токен и использует его для авторизации пользователя или получения данных профиля пользователя.

Этот подход помогает избежать прямого управления паролями и перекладывает управление идентификацией на доверенных провайдеров.

# Интеграция OAuth Hugging Face в FastAPI

Этот модуль предоставляет инструменты для интеграции Hugging Face OAuth в приложение FastAPI. Он позволяет аутентифицировать пользователей с использованием платформы Hugging Face, включая имитацию поведения для локальной разработки и реальный OAuth-поток для Spaces.

## Обзор OAuth

Функция `attach_huggingface_oauth` добавляет в ваше приложение FastAPI эндпоинты для входа, выхода и обратного вызова. При использовании в Space она подключается к системе OAuth Hugging Face. При локальном использовании она подставляет тестового пользователя. Нажмите здесь, чтобы узнать больше о [добавлении опции Sign-In with HF в ваш Space](https://huggingface.co/docs/hub/en/spaces-oauth)

### Как им пользоваться?

```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]
> Вам также может быть интересен [практический пример, демонстрирующий работу OAuth](https://huggingface.co/spaces/Wauplin/fastapi-oauth/blob/main/app.py). Для более комплексной реализации посмотрите Space [medoidai/GiveBackGPT](https://huggingface.co/spaces/medoidai/GiveBackGPT), в котором HF OAuth реализован в полномасштабном приложении.

### 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 = '/')
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py#L124)

Добавьте OAuth-эндпоинты в приложение FastAPI, чтобы обеспечить вход через OAuth с Hugging Face.

Как использовать:
- Вызовите этот метод в вашем приложении FastAPI, чтобы добавить конечные точки OAuth.
- В обработчиках маршрутов вызывайте `parse_huggingface_oauth(request)`, чтобы получить информацию об OAuth.
- Если пользователь вошёл в систему, возвращается объект [OAuthInfo](/docs/huggingface_hub/main/ru/package_reference/oauth#huggingface_hub.OAuthInfo) с информацией о пользователе. В противном случае возвращается `None`.
- В вашем приложении убедитесь, что вы добавили ссылки на `/oauth/huggingface/login` и `/oauth/huggingface/logout`, чтобы пользователь мог войти и выйти.

Пример:
```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)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py#L191)

Возвращает информацию о вошедшем пользователе в виде объекта [OAuthInfo](/docs/huggingface_hub/main/ru/package_reference/oauth#huggingface_hub.OAuthInfo).

Для обеспечения гибкости и совместимости с будущими версиями этот метод очень лоялен к анализу входных данных и не вызывает ошибок. Отсутствующие поля устанавливаются в `None` без предупреждения.

Возвращает `None`, если пользователь не вошёл в систему (нет информации в сессионной cookie).

См. [attach_huggingface_oauth()](/docs/huggingface_hub/main/ru/package_reference/oauth#huggingface_hub.attach_huggingface_oauth) для примера использования этого метода.

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

[Источник](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py#L23)

**Параметры:**

sub (`str`) : Уникальный идентификатор организации. Поле OpenID Connect.

name (`str`) : Полное название организации. Поле OpenID Connect.

preferred_username (`str`) : Имя пользователя организации. Поле OpenID Connect.

picture (`str`) : URL изображения профиля организации. Поле OpenID Connect.

plan (`str`, *необязательный*) : план организации (например, "enterprise", "team"). Поле Hugging Face.

can_pay (`Optional[bool]`, *необязательный*) : Указывает, настроен ли способ оплаты для организации. Поле Hugging Face.

role_in_org (`Optional[str]`, *необязательный*) : Роль пользователя в организации. Поле Hugging Face.

security_restrictions (`Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]]`, *необязательный*) : Массив ограничений безопасности, которые пользователь не выполнил для этой организации. Возможные значения: "ip", "token-policy", "mfa", "sso". Поле Hugging Face.

Информация об организации, связанной с пользователем, вошедшим в систему с помощью 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)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py#L57)

**Параметры:**

sub (`str`) : Уникальный идентификатор пользователя, сохраняющийся даже при смене имени. Поле OpenID Connect.

name (`str`) : Полное имя пользователя. Поле OpenID Connect.

preferred_username (`str`) : Имя пользователя. Поле OpenID Connect.

email_verified (`Optional[bool]`, *необязательный*) : Указывает, подтверждён ли адрес электронной почты пользователя. Поле OpenID Connect.

email (`Optional[str]`, *необязательный*) : адрес электронной почты пользователя. Поле OpenID Connect.

picture (`str`) : URL изображения профиля пользователя. Поле OpenID Connect.

profile (`str`) : URL профиля пользователя. Поле OpenID Connect.

website (`Optional[str]`, *необязательный*) : URL веб-сайта пользователя. Поле OpenID Connect.

is_pro (`bool`) : Является ли пользователь pro-пользователем. Поле Hugging Face.

can_pay (`Optional[bool]`, *необязательный*) : Указывает, настроен ли у пользователя способ оплаты. Поле Hugging Face.

orgs (`Optional[list[OrgInfo]]`, *необязательный*) : Список организаций, участником которых является пользователь. Поле Hugging Face.

Информация о пользователе, вошедшем в систему с помощью 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)
```

[Источник](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/_oauth.py#L100)

**Параметры:**

access_token (`str`) : Токен доступа.

access_token_expires_at (`datetime.datetime`) : Дата истечения срока действия токена доступа.

user_info ([OAuthUserInfo](/docs/huggingface_hub/main/ru/package_reference/oauth#huggingface_hub.OAuthUserInfo)) : Информация о пользователе.

state (`str`, *необязательный*) : Состояние, переданное поставщику OAuth в исходном запросе к поставщику OAuth.

scope (`str`) : Предоставленная область действия.

Информация о входе через OAuth.