إضافة زر تسجيل الدخول عبر HF إلى مساحتك

يمكنك تفعيل تدفق تسجيل دخول مدمج في مساحتك من خلال إنشاء تطبيق OAuth/OpenID connect وربطه بسلاسة، مما يتيح للمستخدمين تسجيل الدخول باستخدام حساباتهم على HF.

يتيح ذلك حالات استخدام جديدة لمساحتك. فعلى سبيل المثال، عند دمجه مع Storage Buckets، يمكن لمساحة الذكاء الاصطناعي التوليدي أن تتيح للمستخدمين تسجيل الدخول للوصول إلى عمليات التوليد السابقة الخاصة بهم، والتي لا يمكن الوصول إليها إلا من قِبلهم.

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

يمكنك أيضًا استخدام تدفق HF OAuth لإنشاء تدفق "تسجيل الدخول عبر HF" في أي موقع ويب أو تطبيق، خارج نطاق Spaces. اقرأ صفحة OAuth العامة لدينا.

إنشاء تطبيق OAuth

كل ما عليك فعله هو إضافة hf_oauth: true إلى بيانات Space الوصفية داخل ملف README.md الخاص بك.

فيما يلي مثال على البيانات الوصفية لمساحة Gradio:

title: Gradio Oauth Test
emoji: 🏆
colorFrom: pink
colorTo: pink
sdk: gradio
sdk_version: 3.40.0
python_version: 3.10.6
app_file: app.py

hf_oauth: true
# optional, default duration is 8 hours/480 minutes. Max duration is 30 days/43200 minutes.
hf_oauth_expiration_minutes: 480
# optional, see "Scopes" below. "openid profile" is always included.
hf_oauth_scopes:
 - read-repos
 - gated-repos
 - write-repos
 - manage-repos
 - inference-api
# optional, restrict access to members of specific organizations
hf_oauth_authorized_org: ORG_NAME
hf_oauth_authorized_org:
  - ORG_NAME1
  - ORG_NAME2

يمكنك الاطلاع على وثائق مرجع التهيئة لمزيد من المعلومات.

سيؤدي هذا إلى إضافة متغيرات البيئة التالية إلى مساحتك:

• OAUTH_CLIENT_ID: معرّف العميل لتطبيق OAuth الخاص بك (عام)
• OAUTH_CLIENT_SECRET: سر العميل الخاص بتطبيق OAuth الخاص بك
• OAUTH_SCOPES: النطاقات المتاحة لتطبيق OAuth الخاص بك.
• OPENID_PROVIDER_URL: عنوان URL لمزوّد OpenID. ستكون بيانات OpenID الوصفية متاحة في {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

أما أي متغير بيئة آخر، فيمكنك استخدامه في الكود الخاص بك باستخدام os.getenv("OAUTH_CLIENT_ID")، على سبيل المثال.

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

يمكنك استخدام أي عنوان URL للتحويل تريده، طالما أنه يستهدف مساحتك.

لاحظ أن SPACE_HOST متاحة كمتغير بيئة.

على سبيل المثال، يمكنك استخدام https://{SPACE_HOST}/login/callback كـ URI لإعادة التوجيه.

النطاقات

تُضمَّن النطاقات التالية دائمًا للمساحات:

• openid: استلام رمز تعريف (ID token) بالإضافة إلى رمز الوصول.
• profile: قراءة معلومات ملف المستخدم الشخصي (اسم المستخدم، الصورة الرمزية، إلخ)

تلك النطاقات اختيارية ويمكن إضافتها عن طريق تعيين hf_oauth_scopes في بيانات الوصف الخاصة بمساحتك:

• 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 أيضًا.

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

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

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

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

إضافة الزر إلى مساحتك

لديك الآن كل المعلومات اللازمة لإضافة زر “تسجيل الدخول عبر HF” إلى مساحتك. يمكن لبعض المكتبات (Python، NodeJS) مساعدتك في تنفيذ بروتوكول OpenID/OAuth.

توفر Gradio وhuggingface.js أيضًا دعمًا مدمجًا، مما يجعل تنفيذ زر تسجيل الدخول عبر HF أمرًا سهلًا؛ يمكنك الاطلاع على الأدلة المرتبطة بـ gradio وبـ huggingface.js.

في الأساس، عليك أن:

• وجّه المستخدم إلى https://huggingface.co/oauth/authorize?redirect_uri={REDIRECT_URI}&scope=openid%20profile&client_id={CLIENT_ID}&state={STATE}، حيث STATE هو نص عشوائي ستحتاج إلى التحقق منه لاحقًا.
• تعامل مع الاستدعاء العكسي على /auth/callback أو /login/callback (أو عنوان الاستدعاء العكسي المخصص لديك) وتحقق من معامل state.
• استخدم معامل الاستعلام code للحصول على رمز وصول (access token) ورمز معرف (id token) من https://huggingface.co/oauth/token (طلب POST مع client_id وcode وgrant_type=authorization_code وredirect_uri كبيانات نموذج، ومع Authorization: Basic {base64(client_id:client_secret)} كترويسة).

يجب عليك استخدام target=_blank على الزر لفتح صفحة تسجيل الدخول في علامة تبويب جديدة، ما لم تكن تشغّل المساحة خارج iframe الخاص بها. وإلا، فقد تواجه مشاكل مع ملفات تعريف الارتباط في بعض المتصفحات.

أمثلة:

• تطبيق اختبار Gradio
• هوغينغ شات (NodeJS/SvelteKit)
• أدوات الاستدلال (Auth.js/SvelteKit)، تستخدم نطاق inference-api لإرسال طلبات الاستدلال نيابةً عن المستخدم.
• على جانب العميل في مساحة ثابتة (huggingface.js) - مثال بسيط جدًا بلغة JavaScript.

مثال على كود JS:

import { oauthLoginUrl, oauthHandleRedirectIfPresent } from "@huggingface/hub";

const oauthResult = await oauthHandleRedirectIfPresent();

if (!oauthResult) {
  // If the user is not logged in, redirect to the login page
  window.location.href = await oauthLoginUrl();
}

// You can use oauthResult.accessToken, oauthResult.userInfo among other things
console.log(oauthResult);