تسجيل الدخول باستخدام Hugging Face

يمكنك استخدام تدفق HF OAuth / OpenID connect لإنشاء تدفق “تسجيل الدخول عبر HF” في أي موقع ويب أو تطبيق.

سيُمكّن هذا المستخدمين من تسجيل الدخول إلى موقعك الإلكتروني أو تطبيقك باستخدام حساب HF الخاص بهم، من خلال النقر على زر مشابه لهذا:

بعد النقر على هذا الزر، سيُعرض على مستخدميك نافذة منبثقة للأذونات للسماح لتطبيقك:

إنشاء تطبيق oauth

يمكنك إنشاء تطبيقك في الإعدادات:

تطبيقات OAuth المملوكة للمنظمة

تُعد هذه الميزة جزءًا من خطط الفريق والمؤسسات.

يمكن أن تكون تطبيقات OAuth مملوكة لمنظمة بدلاً من حساب فردي. وهذا مفيد للتطبيقات التي يديرها فريقك معًا، إذ تبقى ضمن المنظمة بدلاً من الاعتماد على حساب عضو واحد.

يمكن لمسؤولي المنظمة إنشاء التطبيقات المملوكة للمنظمة وإدارتها من قسم OAuth Apps في إعدادات المنظمة (https://huggingface.co/organizations/<your-org>/settings/applications). يمكن لجميع مسؤولي المنظمة تعديل التطبيق، أو تدوير سر العميل الخاص به، أو حذفه. يعرض قائمة التطبيقات العضو الذي أنشأ كل تطبيق، وتُسجَّل التغييرات على التطبيقات في سجلات التدقيق الخاصة بالمنظمة.

تُدرج الصفحة نفسها أيضًا تطبيق تبادل الرموز الخاص بالمنظمة، إذا تم إعداده.

يمكنك أيضًا نقل تطبيق OAuth موجود تملكه إلى منظمة أنت مدير فيها، من قسم النقل إلى منظمة في صفحة إعدادات التطبيق. يجب أن تكون المنظمة على خطة Team أو Enterprise. بعد النقل، يُدار التطبيق من قبل جميع مديري المنظمة. تبقى معرّف العميل (client ID) وسر العميل (client secret) والصلاحيات والرموز الحالية كما هي، لذا يستمر موقعك الإلكتروني أو تطبيقك في العمل دون أي تغييرات. لا يمكن التراجع عن النقل من صفحة الإعدادات.

تطبيقات OAuth العامة (بدون سر)

يمكنك إنشاء تطبيقات OAuth أو استخدامها دون الحاجة إلى سر عميل. وهذا مفيد للتطبيقات الأصلية، وأدوات سطر الأوامر، أو السياقات الأخرى التي يكون فيها الاحتفاظ بسر عمليًا أمرًا غير عملي.

• عند إنشاء التطبيق: عند إنشاء تطبيق OAuth جديد، يمكنك اختيار إنشائه بدون سر.
• بعد الإنشاء: بالنسبة لتطبيق موجود مسبقًا، يمكنك حذف سر العميل في إعدادات التطبيق. سيعمل التطبيق بعد ذلك كتطبيق عام.

تستخدم التطبيقات العامة المصادقة باستخدام معرّف العميل فقط (على سبيل المثال، في تدفقات رمز الجهاز أو رمز التفويض مع PKCE). لا يزال بإمكان التطبيقات التي تمتلك سرًا استخدام هذا السر عند الحاجة (على سبيل المثال، Authorization: Basic لطلبات الرموز).

عناوين إعادة التوجيه

يجب أن يطابق redirect_uri المُرسَل في طلب الترخيص أحد عناوين إعادة التوجيه المسجلة في تطبيقك بشكلٍ تام.

تُعدّ مُعرّفات التوجيه (URIs) الخاصة بالتحويل إلى حلقة الاستجابة (Loopback) الاستثناء الوحيد: فبالنسبة للمعرّفات التي تستخدم مخطط http على مضيف حلقة الاستجابة (localhost أو 127.0.0.1 أو [::1])، يُقبل أي منفذ عند وقت الطلب، طالما أن جميع المكونات الأخرى تطابق مُعرّفًا مسجّلًا. يتبع ذلك RFC 8252 §7.3 / OAuth 2.1، مما يتيح للتطبيقات الأصلية وأدوات سطر الأوامر (CLIs) وعملاء MCP تسجيل مُعرّف بلا منفذ مثل http://localhost/callback ثم الاستماع على أي منفذ مؤقت يخصصه نظام التشغيل لهم (مثل http://localhost:49282/callback).

بعض الأمور التي يجب وضعها في الاعتبار:

• تنطبق الاستثناء فقط على مخطط http. أما عناوين إعادة التوجيه لمخططي https والمخططات المخصصة (مثل myapp://callback) فتتطلب دائمًا تطابقًا تامًا، بما في ذلك المنفذ.
• تُطابَق مضيفات Loopback بشكل فردي: فطلب http://localhost:49282/callback لا يطابق http://127.0.0.1/callback المسجّل. سجّل كلاهما إذا كان تطبيقك قد يستخدم أيّاً منهما.
• قد يختلف المنفذ فقط. أما المسار والاستعلام ومعلومات المستخدم فيجب أن تتطابق تماماً.

إذا كنت تستضيف في Spaces

إذا كنت تستضيف تطبيقك على Spaces، فسيكون تنفيذ هذا التدفق أسهل (وهو مدمج في Gradio مباشرةً)؛ راجد دليل OAuth الخاص بـ Spaces لدينا.

إنشاء تطبيق oauth تلقائي

تدعم Hugging Face بروتوكول CIMD المعروف باسم Client ID Metadata Documents، والذي يتيح لك إنشاء تطبيق oauth لموقعك الإلكتروني بطريقة آلية:

• أضِف نقطة نهاية إلى موقعك الإلكتروني /.well-known/oauth-cimd تُرجع ما يلي بصيغة JSON:

{
  client_id:                  "[your website url]/.well-known/oauth-cimd",
  client_name:                "Your Website",
  redirect_uris:              ["[your website url]/oauth/callback/huggingface"],
  token_endpoint_auth_method: "none",
  logo_uri:                  "https://....", // optional
  client_uri:                 "[your website url]", // optional
}

• استخدم "[your website url]/.well-known/oauth-cimd" كمعرّف للعميل، واستخدم PCKE كآلية للمصادقة

يمكن للتطبيقات الأصلية وعملاء MCP الذين يستقبلون رمز التفويض على منفذ محلي إدراج عناوين URI حلقة رجوع بدون منفذ في redirect_uris، مثل ["http://localhost/callback", "http://127.0.0.1/callback"] — راجع عناوين URI لإعادة التوجيه.

يُعدّ هذا مفيدًا بشكل خاص للبيئات المؤقتة أو لعملاء MCP. راجع مثالًا على التنفيذ في Hugging Chat.

OAuth لرمز الجهاز

يتيح تدفق رمز الجهاز للمستخدمين تفويض تطبيق على جهاز واحد (مثل سطر الأوامر) عن طريق إدخال رمز قصير على جهاز آخر (مثل هاتف أو متصفح). لا يتطلب ذلك وجود عنوان إعادة توجيه أو متصفح على الجهاز الذي يعمل عليه التطبيق.

الاختبار باستخدام سكربت عينة

يمكنك اختبار تطبيق OAuth الذي يستخدم رمز الجهاز باستخدام السكربت التالي. استبدل <Client ID> بمعرّف العميل الخاص بتطبيقك. بالنسبة للتطبيقات العامة (بدون سر)، يعمل السكربت كما هو. أما بالنسبة للتطبيقات التي تحتوي على سر، فأضف ترويسة Authorization: Basic (وهي Base64 لـ client_id:client_secret) إلى كلٍّ من طلبات الجهاز والرمز.

#!/bin/bash
CLIENT_ID="<Client ID>"

# Step 1: Get device code
RESPONSE=$(curl -s -X POST https://huggingface.co/oauth/device \
  -d "client_id=$CLIENT_ID")

DEVICE_CODE=$(echo $RESPONSE | jq -r '.device_code')
USER_CODE=$(echo $RESPONSE | jq -r '.user_code')
VERIFICATION_URI=$(echo $RESPONSE | jq -r '.verification_uri')

echo "Device Code: $DEVICE_CODE"
echo "User Code: $USER_CODE"
echo ""
echo "Open: ${VERIFICATION_URI}"
echo "Enter the user code: $USER_CODE"
echo ""
read -p "Press Enter after authorizing..."

# Step 3: Get token
curl -X POST https://huggingface.co/oauth/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
  -d "device_code=$DEVICE_CODE" \
  -d "client_id=$CLIENT_ID"

بالنسبة لتطبيقات OAuth التي تحتوي على سر عميل (client secret)، يجب تضمين ترويسة Authorization: Basic (مع client_id:client_secret مُرمّز باستخدام Base64) في كلٍّ من طلب رمز الجهاز وطلب الرمز.

النطاقات المدعومة حاليًا

النطاقات المدعومة حاليًا هي:

• openid: استلام رمز تعريف (ID token) بالإضافة إلى رمز الوصول.
• profile: قراءة معلومات ملف المستخدم الشخصي (اسم المستخدم، الصورة الرمزية، إلخ)
• email: قراءة عنوان البريد الإلكتروني للمستخدم.
• read-billing: معرفة ما إذا كان المستخدم قد قام بإعداد طريقة دفع.
• read-memberships: قراءة المنظمات التي ينتمي إليها المستخدم، ودوره في كل منها. لا يمنح هذا الوصول إلى إعدادات المنظمات أو مواردها.
• read-repos: قراءة مستودعات المستخدم الشخصية.
• gated-repos: قراءة محتوى المستودعات العامة المقيدة التي مُنح المستخدم صلاحية الوصول إليها. على عكس read-repos، لا تمنح هذه الصلاحية الوصول إلى المستودعات الخاصة.
• contribute-repos: إنشاء المستودعات والوصول إلى تلك التي أنشأها هذا التطبيق. لا يمكن الوصول إلى أي مستودعات أخرى ما لم تُمنح أذونات إضافية.
• write-repos: قراءة مستودعات المستخدم الشخصية وكتابة بيانات فيها.
• manage-repos: إدارة مستودعات المستخدم الشخصية بالكامل، بما في ذلك إنشاؤها وحذفها.
• read-collections: قراءة مجموعات المستخدم الشخصية.
• write-collections: قراءة مجموعات المستخدم الشخصية وكتابتها، بما في ذلك إنشاؤها وحذفها.
• inference-api: إرسال طلبات الاستدلال إلى موفّري الاستدلال نيابةً عن المستخدم.
• read-endpoints: عرض نقاط الاستدلال الخاصة بالمستخدم وإرسال طلبات الاستدلال إليها نيابةً عنه.
• write-endpoints: إدارة نقاط الاستدلال (Inference Endpoints) الخاصة بالمستخدم، بما في ذلك إنشاؤها وحذفها. يتضمن وصول read-endpoints.
• jobs: تشغيل jobs
• webhooks: إدارة webhooks
• write-discussions: فتح النقاشات وطلبات الدمج نيابةً عن المستخدم، وكذلك التفاعل مع النقاشات (بما في ذلك التفاعلات، نشر/تعديل التعليقات، إغلاق النقاشات، ...). لفتح طلبات الدمج في المستودعات الخاصة، تحتاج إلى طلب نطاق read-repos أيضًا.

جميع المعلومات الأخرى متاحة في بيانات OpenID الوصفية.

يرجى التواصل معنا إذا كنت بحاجة إلى نطاقات إضافية.

الوصول إلى موارد المنظمة

بشكل افتراضي، لا يحتاج تطبيق oauth إلى الوصول إلى موارد المنظمة.

لكن بعض النطاقات مثل read-repos أو read-billing تنطبق على المنظمات أيضاً.

يمكن للمستخدم تحديد المنظمات التي سيتم منحها الوصول عند تفويض التطبيق. إذا كنت بحاجة إلى الوصول إلى منظمة محددة، يمكنك إضافة orgIds=ORG_ID كعامل استعلام إلى عنوان URL لتفويض OAuth. يتوفر معرّف المنظمة في حقل orgs[].sub من استجابة userinfo.

مزامنة عضوية المنظمة كمجموعات

تتضمن استجابة userinfo (https://huggingface.co/oauth/userinfo) مطالبة groups: وهي أسماء المنظمات التي ينتمي إليها المستخدم، على شكل مصفوفة من النصوص.

{
  "sub": "...",
  "preferred_username": "my-username",
  "groups": ["my-org", "another-org"],
  "orgs": [ ... ]
}

يمكن لعملاء OIDC الكثر (مثل Discourse وGrafana وArgo CD وVault وKubernetes) مزامنة عضوية المجموعات من مطالبة تحتوي على مصفوفة من النصوص، وغالبًا ما يتم تكوينها بمطالبة groups. يمكنك استخدام ذلك لربط منظمات Hugging Face بالأدوار أو المجموعات في تطبيقك. لمزيد من التفاصيل حول كل منظمة (المعرّف، الدور، إلخ)، استخدم حقل orgs بدلاً من ذلك.

بعض الأمور التي يجب وضعها في الاعتبار:

• لا يُعاد ادعاء groups إلا من نقطة نهاية userinfo، وليس في رمز الهوية.
• يتضمن أسماء المنظمات، وليس المعرّفات. إذا تم تغيير اسم منظمة، فإن الخرائط التي تستخدم اسمها القديم ستتوقف عن التطابق.
• لا تُدرَج مجموعات الموارد. بالنسبة إلى المنظمات التي تشترك في خطة مدفوعة، تُدرَج مجموعات الموارد والأدوار الخاصة بالمستخدم في orgs[].resourceGroups.

العلامة التجارية

يمكنك استخدام تصميمك الخاص للزر. أدناه بعض صور SVG مُقدَّمة بشكل مفيد.

اطّلع على شاراتنا مع الشروحات الخاصة بدمجها في markdown أو HTML.

تبادل الرموز للمنظمات (RFC 8693)

تُعد هذه الميزة جزءًا من خطة Enterprise.

يتيح تبادل الرموز (Token Exchange) للمنظمات إصدار رموز وصول لأعضائها برمجياً دون الحاجة إلى موافقة تفاعلية من المستخدم. وهذا مفيد بشكل خاص لبناء الأدوات الداخلية، وخطوط أتمتة العمليات، والتكاملات المؤسسية التي تحتاج إلى الوصول إلى موارد Hugging Face نيابةً عن أعضاء المنظمة.

إذا كنت بحاجة فقط إلى المصادقة بدون مفاتيح من سير عمل CI/CD (GitHub Actions، GitLab CI، CircleCI، ...) — دون إصدار رموز لكل عضو — راجع Trusted Publishers، الذي يستخدم أيضاً /oauth/token لكنه يتخذ رمز id_token من نوع OIDC مُصدراً من مزود CI الخاص بك كرمز موضوع (لا يتطلب خطة Enterprise، ولا بيانات اعتماد عميل).

تنفّذ هذه الميزة RFC 8693 - OAuth 2.0 Token Exchange، وهو بروتوكول قياسي لسيناريوهات تبادل الرموز.

حالات الاستخدام

صُمم تبادل الرموز (Token Exchange) للسيناريوهات التي تحتاج فيها مؤسستك إلى:

• بناء منصات داخلية: أنشئ لوحات تحكم أو بوابات تصل إلى موارد Hugging Face نيابةً عن أعضاء فريقك، دون الحاجة إلى أن يقوم كل مستخدم بالتحقق من هويته يدويًا.
• أتمتة خطوط CI/CD: أصدر رموز وصول قصيرة العمر ومحددة النطاق للتدفقات التلقائية التي تحتاج إلى دفع النماذج أو مجموعات البيانات إلى مستودعات المؤسسة.
• التكامل مع أنظمة الهوية المؤسسية: اربط مزوّد الهوية الحالي لديك بـ Hugging Face من خلال إصدار الرموز (tokens) بناءً على دليل المستخدمين الداخلي لديك.
• تنفيذ ضوابط وصول مخصصة: قم ببناء وسيط (middleware) يصدر رموزًا (tokens) بنطاقات محددة بناءً على السياسات الداخلية لمنظمتك.

كيف يعمل

1. يتمتع تطبيق OAuth الخاص بمنظمتك بصلاحية token-exchange المرتبط بمنظمتك.
2. يقوم خادمك الخلفي (Backend) بالتحقق من هويته باستخدام بيانات اعتماد العميل (Client Credentials) الخاصة بتطبيق OAuth هذا.
3. تطلب خدمتك رمز وصول لعضو محدد في المنظمة (يُعرَّف بالبريد الإلكتروني).
4. تحقّق Hugging Face من أن المستخدم عضو في منظمتك ثم تصدر رمز نطاق محدد.
5. لا يمكن للرمز المُصدَر الوصول إلى الموارد إلا ضمن نطاق مؤسستك.

المتطلبات

لاستخدام Token Exchange، تحتاج إلى تطبيق OAuth مرتبط بالمنظمة ويحمل صلاحية token-exchange. تواصل مع دعم Hugging Face لإعداد تطبيق OAuth مؤهل لمنظمتك.

بمجرد إتمام التهيئة، ستحصل على:

• معرّف عميل Client ID (على سبيل المثال، a1b2c3d4-e5f6-7890-abcd-ef1234567890)
• سر العميل (احتفظ به بأمان!)

يمكن لمسؤولي المنظمة إدارة تطبيق OAuth بعد إنشائه، بما في ذلك تحديث سر العميل وإعداد مدة صلاحية الرمز. يُدرج التطبيق في قسم OAuth Apps ضمن إعدادات منطمتك، وتُسجَّل أي تغييرات عليه في سجلات التدقيق الخاصة بالمنظمة.

المصادقة

يستخدم تبادل الرموز (Token Exchange) المصادقة الأساسية عبر HTTP باستخدام بيانات اعتماد تطبيق OAuth الخاص بك. أنشئ ترويسة التفويض (authorization header) عن طريق ترميز client_id:client_secret الخاص بك باستخدام Base64:

# Create the authorization header
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export AUTH_HEADER=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)

إصدار الرموز المميزة عبر البريد الإلكتروني

لإصدار رمز وصول لعضو في المنظمة باستخدام عنوان بريده الإلكتروني:

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email"

الاستجابة

يعيد الطلب الناجح رمز وصول:

{
  "access_token": "hf_oauth_...",
  "token_type": "bearer",
  "expires_in": 28800,
  "scope": "openid profile email read-repos",
  "id_token": "eyJhbGciOiJS...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

يُضمَّن حقل id_token عند طلب نطاق openid.

يمكنك بعد ذلك استخدام هذا الرمز لإجراء طلبات واجهة برمجة التطبيقات نيابةً عن المستخدم:

curl "https://huggingface.co/api/whoami-v2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

التحكم في النطاق

بشكل افتراضي، ترث الرموز الصادرة جميع النطاقات المُهيأة على تطبيق OAuth. يمكنك طلب نطاقات محددة عن طريق إضافة معامل scope. راجع النطاقات المدعومة حاليًا للقيم المتاحة.

تُقيَّد الصلاحيات الفعلية للرمز المميز (Token) بكل من النطاق المطلوب ودور المستخدم داخل المنظمة.

curl -X POST "https://huggingface.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic ${AUTH_HEADER}" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=user@yourorg.com" \
  -d "subject_token_type=urn:huggingface:token-type:user-email" \
  -d "scope=openid profile"

اتبع مبدأ الحد الأدنى من الصلاحيات: اطلب فقط النطاقات التي يحتاجها تطبيقك فعليًا.

اعتبارات أمنية

تتمتع الرموز الصادرة عبر تبادل الرموز (Token Exchange) بقيود أمنية مدمجة:

• محدود النطاق بالتنظيم: لا يمكن للرموز الوصول إلى الموارد إلا داخل تنظيمك (النماذج، مجموعات البيانات، المساحات، والمجموعات التي يملكها التنظيم). خارج التنظيم، يكون الوصول للقراءة فقط ومحدودًا بما يلي: المجموعات العامة من أي مستخدم أو تنظيم، والمستودعات العامة المُقيَّدة التي مُنح المستخدم إذنًا فرديًا للوصول إليها.
• لا يوجد وصول شخصي: لا يمكن للرموز الوصول إلى مستودعات المستخدم الخاصة الشخصية أو المستودعات الخاصة من منظمات أخرى.
• قصير العمر: تنتهي صلاحية الرموز بعد 8 ساعات افتراضيًا. يمكن لمديري المؤسسة تكوين مدة الرمز (حتى 30 يومًا) في إعدادات تطبيق OAuth. لا يتم توفير رموز تحديث.
• قابل للتدقيق: يتم تسجيل جميع عمليات تبادل الرموز (Tokens) وعرضها في سجلات التدقيق الخاصة بمنظمتك.

احرص على حماية بيانات اعتماد تطبيق OAuth الخاص بك بعناية. فأي شخص لديه وصول إلى سر العميل الخاص بك يمكنه إصدار رموز لأي عضو في مؤسستك.

استجابات الأخطاء

مرجع

نوع الإذن:

urn:ietf:params:oauth:grant-type:token-exchange

معامل الطلب (subject_token_type):

حقل الاستجابة (issued_token_type):

التوثيق ذي الصلة:

• وثيقة الاقتراح RFC 8693 - تبادل الرموز OAuth 2.0
• سجلات التدقيق