ربط حساب Google بـ OAuth

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

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

في تدفق كود التفويض ، تحتاج إلى نقطتي نهاية:

  • نقطة نهاية التفويض ، التي تقدم واجهة مستخدم تسجيل الدخول للمستخدمين الذين لم يسجلوا الدخول بالفعل. تنشئ نقطة نهاية التفويض أيضًا رمز ترخيص قصير العمر لتسجيل موافقة المستخدمين على الوصول المطلوب.

  • نقطة نهاية تبادل الرموز ، وهي المسؤولة عن نوعين من التبادلات:

    1. يتبادل رمز التفويض لرمز تحديث طويل الأمد ورمز وصول قصير العمر. يحدث هذا التبادل عندما يمر المستخدم خلال تدفق ربط الحساب.
    2. تبادل رمز تحديث طويل الأمد لرمز وصول قصير العمر. يحدث هذا التبادل عندما تحتاج Google إلى رمز وصول جديد لأن الرمز الذي انتهت صلاحيته.

اختر تدفق OAuth 2.0

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

موجهات التصميم

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

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

متطلبات

  1. يجب أن تبلغ أن حساب المستخدم سيكون مرتبطًا بـ Google ، وليس منتجًا معينًا من منتجات Google مثل صفحة Google الرئيسية أو مساعد Google.

التوصيات

نوصي بالقيام بما يلي:

  1. اعرض سياسة خصوصية Google. قم بتضمين رابط لسياسة خصوصية Google على شاشة الموافقة.

  2. البيانات المراد تقاسمها. استخدم لغة واضحة وموجزة لإخبار المستخدم بالبيانات التي تتطلبها Google ولماذا.

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

  4. القدرة على الإلغاء. وفر طريقة للمستخدمين للعودة أو الإلغاء ، إذا اختاروا عدم الارتباط.

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

  6. القدرة على فك الارتباط. قدم آلية للمستخدمين لإلغاء الارتباط ، مثل عنوان URL لإعدادات حساباتهم على النظام الأساسي الخاص بك. بدلاً من ذلك ، يمكنك تضمين رابط إلى حساب Google حيث يمكن للمستخدمين إدارة حساباتهم المرتبطة.

  7. القدرة على تغيير حساب المستخدم. اقترح طريقة للمستخدمين لتبديل حساباتهم. هذا مفيد بشكل خاص إذا كان المستخدمون يميلون إلى امتلاك حسابات متعددة.

    • إذا كان يجب على المستخدم إغلاق شاشة الموافقة لتبديل الحسابات ، فأرسل خطأً قابلاً للاسترداد إلى Google حتى يتمكن المستخدم من تسجيل الدخول إلى الحساب المطلوب من خلال ربط OAuth والتدفق الضمني .
  8. قم بتضمين شعارك. اعرض شعار شركتك على شاشة الموافقة. استخدم إرشادات أسلوبك لوضع شعارك. إذا كنت ترغب أيضًا في عرض شعار Google ، فراجع الشعارات والعلامات التجارية .

أنشئ المشروع

لإنشاء مشروعك لاستخدام ربط الحساب:

  1. Go to the Google API Console.
  2. انقر فوق إنشاء مشروع .
  3. أدخل اسمًا أو اقبل الاقتراح الذي تم إنشاؤه.
  4. قم بتأكيد أو تحرير أي حقول متبقية.
  5. انقر فوق إنشاء .

لعرض معرف المشروع الخاص بك:

  1. Go to the Google API Console.
  2. ابحث عن مشروعك في الجدول على الصفحة المقصودة. يظهر معرف المشروع في عمود المعرف .

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

  1. افتح صفحة شاشة موافقة OAuth لوحدة تحكم Google APIs.
  2. إذا طُلب منك ذلك ، فحدد المشروع الذي أنشأته للتو.
  3. في صفحة "شاشة موافقة OAuth" ، املأ النموذج وانقر على الزر "حفظ".

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

    شعار التطبيق: صورة على شاشة الموافقة تساعد المستخدمين في التعرف على تطبيقك. يظهر الشعار على شاشة الموافقة على ربط الحساب وعلى إعدادات الحساب

    البريد الإلكتروني للدعم: للمستخدمين للاتصال بك لطرح أسئلة حول موافقتهم.

    نطاقات Google APIs: تسمح النطاقات لتطبيقك بالوصول إلى بيانات Google الخاصة بالمستخدم. بالنسبة لحالة استخدام ربط حساب Google ، يكفي النطاق الافتراضي (البريد الإلكتروني ، الملف الشخصي ، openid) ، لست بحاجة إلى إضافة أي نطاقات حساسة. من أفضل الممارسات عمومًا طلب النطاقات بشكل متزايد ، في الوقت الذي يكون الوصول فيه مطلوبًا ، وليس مقدمًا. اعرف المزيد .

    المجالات المصرح بها: لحمايتك وحماية المستخدمين ، تسمح Google فقط للتطبيقات التي تقوم بالمصادقة باستخدام OAuth باستخدام المجالات المصرح بها. يجب استضافة روابط تطبيقاتك على المجالات المصرح بها. اعرف المزيد .

    رابط الصفحة الرئيسية للتطبيق: الصفحة الرئيسية للتطبيق الخاص بك. يجب أن تكون مستضافة على مجال مصرح به.

    رابط سياسة خصوصية التطبيق: يظهر على شاشة الموافقة على ربط حساب Google. يجب أن تكون مستضافة على مجال مصرح به.

    رابط شروط خدمة التطبيق (اختياري): يجب استضافته على نطاق مصرح به.

    الشكل 1 . شاشة الموافقة على ربط حساب Google لتطبيق وهمي ، Tunery

  4. تحقق من "حالة التحقق" ، إذا كان طلبك يحتاج إلى التحقق ، فانقر فوق الزر "إرسال للتحقق" لإرسال طلبك للتحقق. راجع متطلبات التحقق من OAuth للحصول على التفاصيل.

نفِّذ خادم OAuth

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

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

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

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

التعامل مع طلبات التفويض

عندما يحتاج تطبيق Google إلى إجراء ربط الحساب عبر التدفق الضمني OAuth 2.0 ، ترسل Google المستخدم إلى نقطة نهاية التفويض الخاصة بك بطلب يتضمن المعلمات التالية:

معلمات نقطة نهاية التفويض
client_id معرّف العميل الذي عينته لـ Google.
redirect_uri عنوان URL الذي ترسل إليه الرد على هذا الطلب.
state قيمة مسك الدفاتر التي يتم إرجاعها إلى Google بدون تغيير في عنوان URI لإعادة التوجيه.
response_type نوع القيمة المراد إرجاعها في الاستجابة. بالنسبة للتدفق الضمني لـ OAuth 2.0 ، يكون نوع الاستجابة دائمًا token .
user_locale يُستخدم إعداد لغة حساب Google بتنسيق RFC5646 لترجمة المحتوى الخاص بك باللغة المفضلة للمستخدم.

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

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

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

  1. تحقق من client_id و redirect_uri لمنع منح الوصول إلى تطبيقات العميل غير المقصودة أو client_id بشكل خاطئ:

    • تأكد من أن client_id يطابق معرّف العميل الذي عينته لـ Google.
    • تأكد من أن عنوان URL المحدد بواسطة معلمة redirect_uri يحتوي على الشكل التالي:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. تحقق مما إذا كان المستخدم قد قام بتسجيل الدخول إلى خدمتك. إذا لم يقم المستخدم بتسجيل الدخول ، أكمل عملية تسجيل الدخول أو تسجيل الاشتراك في الخدمة.

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

  4. أرسل استجابة HTTP تعيد توجيه متصفح المستخدم إلى عنوان URL المحدد بواسطة معلمة redirect_uri . قم بتضمين جميع المعلمات التالية في جزء عنوان URL:

    • access_token : رمز الوصول الذي أنشأته للتو
    • token_type : bearer السلسلة
    • state : قيمة الحالة غير المعدلة من الطلب الأصلي

    فيما يلي مثال على عنوان URL الناتج:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

يتلقى معالج إعادة توجيه OAuth 2.0 من Google رمز الوصول ويؤكد أن قيمة state لم تتغير. بعد حصول Google على رمز وصول لخدمتك ، تقوم Google بإرفاق الرمز المميز بالمكالمات اللاحقة بواجهات برمجة تطبيقات الخدمة.

التحقق من صحة التنفيذ الخاص بك

يمكنك التحقق من صحة التنفيذ باستخدام أداة OAuth 2.0 Playground .

في الأداة ، قم بالخطوات التالية:

  1. انقر على التهيئة لفتح نافذة تهيئة OAuth 2.0.
  2. في حقل تدفق OAuth ، حدد من جانب العميل .
  3. في حقل نقاط نهاية OAuth ، حدد مخصص .
  4. حدد نقطة نهاية OAuth 2.0 ومعرف العميل الذي عينته لـ Google في الحقول المقابلة.
  5. في قسم الخطوة 1 ، لا تحدد أيًا من نطاقات Google. بدلاً من ذلك ، اترك هذا الحقل فارغًا أو اكتب نطاقًا صالحًا لخادمك (أو سلسلة عشوائية إذا كنت لا تستخدم نطاقات OAuth). عند الانتهاء ، انقر فوق تخويل واجهات برمجة التطبيقات .
  6. في قسمي الخطوة 2 والخطوة 3 ، انتقل عبر تدفق OAuth 2.0 وتحقق من أن كل خطوة تعمل على النحو المنشود.

يمكنك التحقق من صحة التنفيذ باستخدام أداة Google Account Linking Demo .

في الأداة ، قم بالخطوات التالية:

  1. انقر فوق الزر تسجيل الدخول باستخدام Google .
  2. اختر الحساب الذي ترغب في ربطه.
  3. أدخل معرف الخدمة.
  4. اختياريًا ، أدخل نطاقًا واحدًا أو أكثر ستطلب الوصول إليه.
  5. انقر فوق بدء العرض التوضيحي .
  6. عند المطالبة ، أكد أنه يمكنك الموافقة ورفض طلب الربط.
  7. تأكد من إعادة توجيهك إلى النظام الأساسي الخاص بك.