ربط حساب Google باستخدام OAuth

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

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.

6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

إنشاء المشروع

لإنشاء مشروعك من أجل استخدام ميزة ربط الحسابات، اتّبِع الخطوات التالية:

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

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

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

ضبط شاشة موافقة OAuth

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

1. افتح صفحة شاشة موافقة OAuth في وحدة تحكُّم Google APIs.
2. اختَر المشروع الذي أنشأته للتو، إذا طُلب منك ذلك.

3. في صفحة "شاشة موافقة OAuth"، املأ النموذج وانقر على زر "حفظ".

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

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

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

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

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

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

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

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

   

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

4. تحقق من "حالة إثبات الملكية"، إذا كان طلبك يحتاج إلى التحقق، فانقر على الزر "إرسال للتحقق" لإرسال طلبك للتحقق. يمكنك الرجوع إلى متطلبات التحقُّق من 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	نوع القيمة المراد إرجاعها في الاستجابة. لتدفق الضمني أوث 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 يطابق معرف العميل الذي قمت بتعيينه إلى 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

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

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

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

• ربط حساب الدخول في مع جوجل بنقرة واحدة.
• الاشتراك الاحتكاك على AndroidTV.

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

رؤوس طلب نقطة نهاية userinfo
Authorization header	رمز الوصول من نوع Bearer.

على سبيل المثال، إذا كان لديك المعلومات حول المستخدم نقطة النهاية هي متوفرة في 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، واسترجاع رمز ويتم تسجيل الدعاوى المرفوعة ضد جوجل الخاص بالمستخدم الحساب.

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

التحقّق من صحة عملية التنفيذ

يمكنك التحقق من صحة التطبيق الخاص بك باستخدام ملعب أوث 2.0 الأداة.

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

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

يمكنك التحقق من صحة التطبيق الخاص بك باستخدام حساب Google ربط تجريبي الأداة.

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

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