Google Account Linking API

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

المتطلبات الأساسية والمعايير

للتفاعل بنجاح مع نقاط نهاية Google هذه، يجب أن يتوافق الدمج مع المعايير التالية:

  • بروتوكول OAuth 2.0: متوافق مع RFC 6749.
  • رموز JSON المميّزة للويب (JWT): متوافقة مع RFC 7519 (لعملية الربط المبسّطة وRISC).
  • رموز الأمان المميزة للأحداث: متوافقة مع RFC 8417 (بالنسبة إلى RISC).
  • HTTPS: يجب إجراء جميع الطلبات عبر اتصال HTTPS آمن.

معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه في OAuth

نقطة النهاية التي تعيد خدمتك توجيه متصفّح المستخدم إليها بعد إكمال عملية المصادقة والموافقة بنجاح. مَعلمة المسار YOUR_PROJECT_ID هي المعرّف الذي يتم ضبطه أثناء التسجيل.

  • عنوان URL: https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • عنوان URL الخاص ببيئة الاختبار: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • الطريقة: GET (باستخدام إعادة توجيه المتصفّح)

مَعلمات الطلب

عند إعادة توجيه المستخدم إلى Google، يجب إلحاق المَعلمات بعنوان URL. استنادًا إلى مسار OAuth المستخدَم، يتم تنسيق هذه المَعلمات إما كسلسلة طلب بحث (مسار رمز المصادقة) أو كجزء من عنوان URL (التدفّق الضمني).

المَعلمة الوصف
code (مطلوب لمسار رمز التفويض) رمز التفويض الذي أنشأته خدمتك.
state (مطلوبة) قيمة الحالة غير المعدَّلة التي تم تلقّيها في الأصل من Google.
access_token (مطلوب للمسار الضمني) رمز الدخول الطويل الأمد الذي أنشأته خدمتك.
token_type (مطلوب لعملية Implicit Flow) يجب أن تكون القيمة bearer.

الردود التي تتضمّن أخطاء

إذا كان الطلب المُرسَل إلى معرّف الموارد المنتظم لإعادة التوجيه في OAuth غير صالح، ستتلقّى رسالة الخطأ HTTP 400 Bad Request. سيحتوي نص الاستجابة على عنصر JSON بالبنية التالية:

الحقل الوصف
sendPostBody تحدِّد هذه السمة ما إذا كان يجب أن تعيد JavaScript التوجيه إلى redirectUri باستخدام POST. عادةً ما يكون false في هذا السيناريو.
errorMessage رسالة خطأ سيتم عرضها للعميل عندما يتعذّر إكمال عملية إعادة التوجيه. بالنسبة إلى الأجزاء المفقودة، تكون القيمة "A URI fragment or query string must be set."

الردود التي تتضمّن أخطاء في OAuth 2.0

إذا رفض المستخدم منح الموافقة أو واجهت خدمتك خطأً، يجب أن تعيد خدمتك توجيه المستخدم إلى معرّف الموارد المنتظم لإعادة التوجيه في OAuth مع مَعلمات الخطأ العادية في OAuth 2.0 (مثل error=access_denied). ستعالج Google هذه المَعلمات وتعرض للمستخدم شاشة خطأ مناسبة.

واجهة RISC API (اختيارية)

تستخدم خدمتك هذا المعرّف لإرسال إشعارات استباقية إلى Google عندما يلغي المستخدم ربط حسابه على منصتك باستخدام بروتوكول RISC، ما يضمن بقاء المنصتَين متزامنتَين.

  • عنوان URL: https://risc.googleapis.com/v1/events:publish
  • الطريقة: POST
  • المصادقة: تتطلّب رمزًا مميزًا لحساب خدمة Google مع الأذونات المناسبة.
  • Content-Type: application/json

مطالبات رمز الحدث الأمني

يجب أن تتوافق رموز Security Event Token التي تستخدمها لإبلاغ Google بأحداث إبطال الرموز مع المتطلبات الواردة في الجدول التالي:

المطالبة الوصف
iss مطالبة جهة الإصدار: هذا هو عنوان URL تستضيفه أنت، ويتم مشاركته مع Google أثناء التسجيل.
aud مطالبة الجمهور: تحدّد هذه المطالبة Google كمستلِم لرمز JWT. يجب ضبطها على google_account_linking.
jti مطالبة معرّف JWT: هذا هو معرّف فريد تنشئه لكل رمز مميّز لحدث الأمان.
iat مطالبة "وقت الإصدار": هذه قيمة NumericDate تمثّل الوقت الذي تم فيه إنشاء رمز الأمان المميّز هذا.
toe وقت المطالبة بالحدث: هذه قيمة اختيارية NumericDate تمثّل الوقت الذي تم فيه إبطال الرمز المميّز.
exp مطالبة وقت انتهاء الصلاحية: لا تضمِّن هذا الحقل، لأنّ الحدث الذي أدّى إلى ظهور هذا الإشعار قد وقع بالفعل.
events مطالبة أحداث الأمان: هذا عنصر JSON، ويجب أن يتضمّن حدث إبطال رمز مميّز واحدًا فقط يحتوي على الحقول التالية:

  • subject_type: يجب ضبط هذه القيمة على oauth_token.
  • token_type: هذا هو نوع الرمز المميّز الذي يتم إبطاله، إما access_token أو refresh_token.
  • token_identifier_alg: هذه هي الخوارزمية المستخدَمة لترميز الرمز المميّز، ويجب أن تكون hash_SHA512_double.
  • ‫token: هذا هو رقم تعريف الرمز المميّز الذي تم إبطاله.

لمزيد من المعلومات حول أنواع الحقول وتنسيقاتها، يُرجى الاطّلاع على رمز JSON المميّز للويب (JWT).

واجهة "الربط السريع" في ميزة "ربط التطبيقات بسرعة"

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

‫Android (نتيجة Intent)

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

  • الإجراء: com.google.android.gms.auth.CODE_AVAILABLE
  • الميزات الإضافية: code وstate وaccess_token وtoken_type

يفتح تطبيقك Google باستخدام مخطط عنوان URL مخصّص أو رابط عالمي HTTPS. لمزيد من المعلومات، يُرجى الاطّلاع على دليل التنفيذ على نظام التشغيل iOS.

  • التنسيق: <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING