# OAuth와 FastAPI

OAuth는 액세스 위임을 위한 개방형 표준으로, 사용자의 자격 증명을 노출하지 않고 애플리케이션에 사용자의 정보에 대한 제한된 액세스를 부여하는 데 일반적으로 사용됩니다. FastAPI와 결합하면 Google이나 GitHub와 같은 외부 ID 제공자를 사용하여 로그인할 수 있는 안전한 API를 구축할 수 있습니다. 일반적인 시나리오에서는 다음과 같습니다:
- FastAPI는 API 엔드포인트를 정의하고 HTTP 요청을 처리합니다.
- OAuth는 fastapi.security와 같은 라이브러리 또는 Authlib와 같은 외부 도구를 사용하여 통합됩니다.
- 사용자가 로그인하려고 하면 FastAPI가 사용자를 OAuth 제공자의 로그인 페이지로 리디렉션합니다.
- 로그인이 성공하면 제공자는 토큰과 함께 다시 리디렉션합니다.
- FastAPI는 이 토큰을 검증하여 사용자를 인증하거나 사용자 프로필 데이터를 가져옵니다.

이 접근 방식은 비밀번호를 직접 처리하는 것을 피하고, 신원 관리를 신뢰할 수 있는 제공업체에 위임하는 데 도움이 됩니다.

# FastAPI에서 Hugging Face OAuth 통합

이 모듈은 FastAPI 애플리케이션에 Hugging Face OAuth를 통합하는 도구를 제공합니다. 로컬 개발을 위한 목(mock) 동작과 Spaces를 위한 실제 OAuth 플로우를 포함하여 Hugging Face 플랫폼을 사용한 사용자 인증을 지원합니다.

## OAuth 개요

`attach_huggingface_oauth` 함수는 FastAPI 앱에 로그인, 로그아웃, 콜백 엔드포인트를 추가합니다. Space에서 사용할 경우 Hugging Face OAuth 시스템에 연결됩니다. 로컬에서 사용할 경우 모킹된 사용자가 주입됩니다. [Space에 HF 로그인 옵션을 추가하는 방법](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)에도 관심이 있을 수 있습니다. 보다 포괄적인 구현을 확인하려면, HF OAuth를 대규모 애플리케이션에 구현한 [medoidai/GiveBackGPT](https://huggingface.co/spaces/medoidai/GiveBackGPT) Space를 살펴보세요.

### 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/v2.4.0/src/huggingface_hub/_oauth.py#L124)

FastAPI 앱에 OAuth 엔드포인트를 추가하여 Hugging Face를 통한 OAuth 로그인을 활성화합니다.

사용 방법:
- FastAPI 앱에서 이 메서드를 호출하여 OAuth 엔드포인트를 추가합니다.
- 루트 핸들러에서 `parse_huggingface_oauth(request)`를 호출하여 OAuth 정보를 가져옵니다.
- 사용자가 로그인된 경우, 해당 사용자의 정보가 포함된 [OAuthInfo](/docs/huggingface_hub/v2.4.0/ko/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/v2.4.0/src/huggingface_hub/_oauth.py#L191)

로그인된 사용자의 정보를 [OAuthInfo](/docs/huggingface_hub/v2.4.0/ko/package_reference/oauth#huggingface_hub.OAuthInfo) 객체로 반환합니다.

유연성과 향후 확장성을 위해 이 메서드는 파싱을 매우 느슨하게 처리하며 오류를 발생시키지 않습니다. 누락된 필드는 경고 없이 `None`으로 설정됩니다.

사용자가 로그인되어 있지 않은 경우(세션 쿠키에 정보가 없는 경우) `None`을 반환합니다.

이 메서드를 사용하는 예제는 [attach_huggingface_oauth()](/docs/huggingface_hub/v2.4.0/ko/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/v2.4.0/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/v2.4.0/src/huggingface_hub/_oauth.py#L57)

**매개변수:**

sub (`str`) : 이름이 변경된 경우에도 사용자를 고유하게 식별하는 ID입니다. 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`) : 사용자가 프로 사용자인지 여부. 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/v2.4.0/src/huggingface_hub/_oauth.py#L100)

**매개변수:**

access_token (`str`) : 액세스 토큰.

access_token_expires_at (`datetime.datetime`) : 액세스 토큰의 만료 날짜.

user_info ([OAuthUserInfo](/docs/huggingface_hub/v2.4.0/ko/package_reference/oauth#huggingface_hub.OAuthUserInfo)) : 사용자 정보입니다.

state (`str`, *선택 사항*) : OAuth 제공자에게 원래 요청할 때 전달된 상태.

scope (`str`) : 부여된 범위.

OAuth 로그인에 대한 정보.