# OAuth وFastAPI

OAuth هو معيار مفتوح لتفويض الوصول، ويُستخدم بشكل شائع لمنح التطبيقات وصولاً محدوداً إلى معلومات المستخدم دون كشف بيانات الاعتماد الخاصة به. عند دمجه مع FastAPI، يتيح لك بناء واجهات برمجة تطبيقات آمنة تتيح للمستخدمين تسجيل الدخول باستخدام مزودي هوية خارجيين مثل Google أو GitHub. في السيناريو المعتاد:
- ستحدد FastAPI نقاط نهاية واجهة برمجة التطبيقات وتتعامل مع طلبات 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. أما عند استخدامها محليًا، فستحقن مستخدمًا وهميًا. انقر هنا لمعرفة المزيد حول [إضافة خيار تسجيل الدخول عبر 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). للحصول على تطبيق أكثر شمولاً، اطّلع على مساحة [medoidai/GiveBackGPT](https://huggingface.co/spaces/medoidai/GiveBackGPT) التي تنفّذ OAuth الخاص بـ HF في تطبيق على نطاق كامل.

### 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/ar/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/ar/package_reference/oauth#huggingface_hub.OAuthInfo).

من أجل المرونة والاستعداد للمستقبل، تكون هذه الطريقة متسامحة جداً في عملية التحليل ولا تطلق أخطاء. تُضبط الحقول الناقصة على `None` دون أي تحذير.

تُرجع `None` إذا لم يكن المستخدم مسجلاً الدخول (لا توجد معلومات في كوكي الجلسة).

راجع [attach_huggingface_oauth()](/docs/huggingface_hub/main/ar/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`) : عنوان صورة الملف الشخصي للمنظمة. حقل 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]`، *اختياري*) : عنوان موقع المستخدم على الويب. حقل 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/main/src/huggingface_hub/_oauth.py#L100)

**المعاملات:**

access_token (`str`) : رمز الوصول.

access_token_expires_at (`datetime.datetime`) : تاريخ انتهاء صلاحية رمز الوصول.

user_info ([OAuthUserInfo](/docs/huggingface_hub/main/ar/package_reference/oauth#huggingface_hub.OAuthUserInfo)) : معلومات المستخدم.

state (`str`، *اختياري*) : الحالة التي تُمرَّر إلى مزوّد OAuth في الطلب الأصلي إلى مزوّد OAuth.

scope (`str`) : النطاق الممنوح.

معلومات حول تسجيل الدخول عبر OAuth.