ربط حساب Google باستخدام OAuth (Implicit Flow - مؤرشف)

خطر: التدفق الضمني غير متاح لـ MCP وUCP والتدفقات التي يبدأها الوكيل. ننصح بشكل عام بعدم استخدامها في جميع عمليات الدمج الجديدة بسبب اعتبارات الأمان. استخدِم مسار رمز التفويض بدلاً من ذلك.

لإتاحة مسار الوصول الضمني في OAuth 2.0، يجب أن توفّر خدمتك نقطة نهاية للتفويض عبر HTTPS. هذه نقطة النهاية مسؤولة عن المصادقة والحصول على موافقة المستخدمين على الوصول إلى البيانات. تعرض نقطة نهاية التفويض واجهة مستخدم لتسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول بعد، وتسجّل الموافقة على الوصول المطلوب.

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

ربط حساب Google: مسار OAuth الضمني

يوضّح مخطط التسلسل التالي تفاعلات بين المستخدم وGoogle ونقاط نهاية خدمتك.

الشكل 1. تسلسل الأحداث في مسار OAuth 2.0 الضمني لربط حساب Google

الأدوار والمسؤوليات

يحدّد الجدول التالي أدوار ومسؤوليات الجهات الفاعلة في عملية ربط حساب Google (GAL) باستخدام OAuth Implicit flow. يُرجى العِلم أنّه في GAL، تعمل Google كعميل لبروتوكول OAuth، بينما تعمل خدمتك كموفّر هوية/خدمة.

الجهة الفاعلة / المكوّن	دور قائمة العناوين العمومية	المسؤوليات
تطبيق / خادم Google	عميل OAuth	يبدأ عملية الحصول على الرمز المميز للوصول من خلال إعادة التوجيه إلى المتصفّح، ويخزّنه بشكل آمن للوصول إلى واجهات برمجة التطبيقات الخاصة بخدمتك.
نقطة نهاية التفويض	خادم التفويض	تتم مصادقة المستخدمين والحصول على موافقتهم وإصدار رموز دخول طويلة الأجل مباشرةً إلى Google.
معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه من Google	نقطة نهاية معاودة الاتصال	يتلقّى عملية إعادة توجيه المستخدم من خدمة التفويض مع القيمتَين access_token وstate في جزء عنوان URL.

تتضمّن جلسة نموذج التدفّق الضمني لبروتوكول OAuth 2.0 التي تبدأها Google الخطوات التالية:

1. يفتح Google نقطة نهاية التفويض في متصفّح المستخدم. يسجّل المستخدم الدخول، إذا لم يكن قد سجّل الدخول من قبل، ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات، إذا لم يسبق له منح الإذن.
2. تنشئ خدمتك رمز دخول وتعيده إلى Google. لإجراء ذلك، أعِد توجيه متصفّح المستخدم إلى Google مع تضمين رمز الدخول في الطلب.
3. تتصل Google بواجهات برمجة التطبيقات الخاصة بخدمتك وتُرفق رمز الدخول بكل طلب. تتحقّق خدمتك من أنّ رمز الدخول يمنح Google إذنًا بالوصول إلى واجهة برمجة التطبيقات، ثم تُكمل طلب البيانات من واجهة برمجة التطبيقات.

وصفة التنفيذ

اتّبِع الخطوات التالية لتنفيذ عملية التدفّق الضمني.

الخطوة 1: التعامل مع طلبات التفويض

عندما تبدأ Google عملية ربط الحساب، تعيد توجيه المستخدم إلى نقطة نهاية التفويض. للاطّلاع على عقود البروتوكول التفصيلية ومتطلبات المَعلمات، يُرجى الرجوع إلى نقطة نهاية التفويض.

للتعامل مع الطلب، اتّخِذ الإجراءات التالية:

1. التحقّق من صحة الطلب:

   • تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي تمّ تعيينه إلى Google.
   • تأكَّد من أنّ redirect_uri يتطابق مع عنوان URL المتوقّع لإعادة التوجيه من Google: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
   • تأكَّد من أنّ response_type هو token.

2. مصادقة المستخدم:

   • تحقَّق مما إذا كان المستخدم قد سجّل الدخول إلى خدمتك.
   • إذا لم يكن المستخدم مسجّلاً الدخول، اطلب منه إكمال خطوات تسجيل الدخول أو الاشتراك.

3. إنشاء رمز دخول:

   • أنشئ رمز دخول فريدًا لا يمكن تخمينه ويكون مرتبطًا بالمستخدم والعميل.

4. إعادة التوجيه إلى Google:

   • أعِد توجيه المتصفّح إلى عنوان URL المقدَّم في redirect_uri.
   • أضِف المَعلمات التالية في جزء من عنوان URL (علامة الهاش):
     • ‫access_token: رمز الدخول الذي أنشأته.
     • ‫token_type: يجب أن تكون bearer.
     • state: قيمة الحالة غير المعدَّلة التي تم تلقّيها من Google

التعامل مع طلبات معلومات المستخدم

نقطة نهاية userinfo هي مورد OAuth 2.0 محمي يعرض مطالبات بشأن المستخدم المرتبط. يُعد تنفيذ نقطة نهاية userinfo واستضافتها اختياريًا، باستثناء حالات الاستخدام التالية:

• تسجيل الدخول إلى حساب مرتبط باستخدام Google One Tap.
• اشتراك سلس على AndroidTV.

بعد استرداد رمز الدخول بنجاح من نقطة نهاية الرمز المميّز، ترسل Google طلبًا إلى نقطة نهاية معلومات المستخدم لاسترداد معلومات الملف الشخصي الأساسية عن المستخدم المرتبط.

عناوين طلبات نقطة نهاية userinfo
Authorization header	رمز الدخول من النوع "الحامل".

على سبيل المثال، إذا كانت نقطة نهاية userinfo متاحة على https://myservice.example.com/userinfo، قد يظهر الطلب على النحو التالي:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

لتتمكّن نقطة نهاية معلومات المستخدم من معالجة الطلبات، عليك اتّباع الخطوات التالية:

1. يمكنك استخراج رمز الدخول من عنوان التفويض ومعلومات الإرجاع للمستخدم المرتبط برمز الدخول.
2. إذا كان رمز الدخول غير صالح، يمكنك عرض الخطأ HTTP 401 "غير مصرح به" مع استخدام عنوان الاستجابة WWW-Authenticate. في ما يلي مثال على استجابة خطأ في معلومات المستخدم:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   إذا تم عرض رسالة الخطأ 401 "غير مصرّح به" أو أي استجابة أخرى غير ناجحة للخطأ أثناء عملية الربط، لن تتمكّن من استرداد الخطأ، وسيتم تجاهل الرمز المميّز الذي تم استرداده وسيضطر المستخدم إلى بدء عملية الربط مرة أخرى.

3. إذا كان رمز الدخول صالحًا، يتم عرض الاستجابة HTTP 200 مع كائن JSON التالي في نص HTTPS. الرد:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   إذا عرضت نقطة نهاية معلومات المستخدم استجابة نجاح HTTP 200، يتم تسجيل الرمز المميز الذي تم استرداده والمطالبات مقابل حساب المستخدم على Google.

   استجابة نقطة نهاية لمعلومات المستخدم
   sub	معرّف فريد يعرّف المستخدِم في نظامك.
   email	عنوان البريد الإلكتروني للمستخدم.
   given_name	اختياري: الاسم الأول للمستخدم.
   family_name	اختياري: اسم العائلة للمستخدم.
   name	اختياري: اسم المستخدم الكامل.
   picture	اختياري: صورة الملف الشخصي للمستخدم.