Hub Python Library documentation
OAuthとFastAPI
OAuthとFastAPI
OAuthはアクセス委譲のためのオープン標準であり、ユーザーの認証情報を公開せずにアプリケーションにユーザー情報の限られたアクセス権を付与するために一般的に使用されます。FastAPIと組み合わせることで、GoogleやGitHubなどの外部アイデンティティプロバイダーを使用してユーザーがログインできる安全なAPIを構築できます。 通常のシナリオでは:
- FastAPI は API エンドポイントを定義し、HTTP リクエストを処理します。
- OAuthは、fastapi.securityのようなライブラリや、Authlibのような外部ツールを使用して統合されます。
- ユーザーがログインを希望すると、FastAPIはユーザーをOAuthプロバイダーのログインページにリダイレクトします。
- ログインが正常に完了すると、プロバイダーはトークン付きでリダイレクトされます。
- FastAPIはこのトークンを検証し、ユーザーの認証またはユーザープロファイルデータの取得に使用します。
このアプローチにより、パスワードを直接処理することを回避し、アイデンティティ管理を信頼できるプロバイダーにオフロードできます。
FastAPI における Hugging Face OAuth 統合
このモジュールは、FastAPI アプリケーションに Hugging Face OAuth を統合するためのツールを提供します。Hugging Face プラットフォームを使用したユーザー認証を可能にし、ローカル開発用のモック動作と Spaces 用の実際の OAuth フローをサポートします。
OAuth概要
attach_huggingface_oauth 関数は、FastAPI アプリケーションにログイン、ログアウト、およびコールバックのエンドポイントを追加します。Space で使用する場合、Hugging Face の OAuth システムに接続します。ローカルで使用する場合、モックされたユーザーが注入されます。Space に Sign-In with HF オプションを追加する方法の詳細については、こちらをクリックしてください。
どのように使用しますか？
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}!"}OAuthの動作を実演する実践的な例もご興味があるかもしれません。 より包括的な実装については、HF OAuthをフルスケールのアプリケーションで実装しているmedoidai/GiveBackGPT Spaceをご覧ください。
attach_huggingface_oauth
FastAPI アプリケーションに OAuth エンドポイントを追加して、Hugging Face による OAuth ログインを有効にします。
使用方法:
- このメソッドを FastAPI アプリに呼び出して、OAuth エンドポイントを追加します。
- ルートハンドラー内で
parse_huggingface_oauth(request)を呼び出し、OAuth情報を取得します。 - ユーザーがログインしている場合、ユーザー情報が含まれたOAuthInfoオブジェクトが返されます。ログインしていない場合は、
Noneが返されます。 - アプリでは、ユーザーがログインおよびログアウトできるように、
/oauth/huggingface/loginと/oauth/huggingface/logoutへのリンクを追加してください。
例:
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
ログイン済みユーザーの情報をOAuthInfoオブジェクトとして返します。
柔軟性と将来の拡張性を考慮し、このメソッドはパース処理を非常に緩く行い、エラーを発生させません。
欠落しているフィールドは、警告なしでNoneに設定されます。
ユーザーがログインしていない場合（セッションクッキーに情報がない場合）、Noneを返します。
このメソッドの使用方法の例については、attach_huggingface_oauth()を参照してください。
OAuthOrgInfo
クラス huggingface_hub.OAuthOrgInfo
< source >( sub: strname: strpreferred_username: strpicture: strplan: str | None = Nonecan_pay: bool | None = Nonerole_in_org: str | None = Nonesecurity_restrictions: list[typing.Literal['ip', 'token-policy', 'mfa', 'sso']] | None = None )
パラメータ
- 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
< source >( sub: strname: strpreferred_username: stremail_verified: bool | Noneemail: str | Nonepicture: strprofile: strwebsite: str | Noneis_pro: boolcan_pay: bool | Noneorgs: list[huggingface_hub._oauth.OAuthOrgInfo] | None )
パラメータ
- 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) — ユーザーがプロユーザーかどうかを示します。Hugging Face のフィールドです。 - can_pay (
Optional[bool]、任意) — ユーザーが支払い方法を設定しているかどうかを示します。Hugging Face のフィールドです。 - orgs (
Optional[list[OrgInfo]], 任意) — ユーザーが所属している組織のリスト。Hugging Face のフィールドです。
OAuthでログインしたユーザーに関する情報。
OAuthInfo
クラス huggingface_hub.OAuthInfo
< source >( access_token: straccess_token_expires_at: datetimeuser_info: OAuthUserInfostate: str | Nonescope: str )
パラメータ
- access_token (
str) — アクセストークンです。 - access_token_expires_at (
datetime.datetime) — アクセストークンの有効期限です。 - user_info (OAuthUserInfo) — ユーザー情報。
- state (
str, 任意) — 元のOAuthプロバイダーへのリクエストで、OAuthプロバイダーに渡されたState。 - scope (
str) — 付与されたスコープ。
OAuthログインに関する情報。