تسجيل الدخول إلى الحساب المرتبط

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

تتيح ميزة ربط حساب Google لمالكي حسابات Google إمكانية الربط بخدماتك ومشاركة البيانات مع Google بسرعة وسلاسة وأمان.

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

ملاحظة: لا تتوفّر ميزة "تسجيل الدخول باستخدام حساب مرتبط" إلّا على أجهزة Android.

المتطلبات

لاستخدام ميزة "تسجيل الدخول باستخدام حساب مرتبط"، يجب استيفاء المتطلبات التالية:

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

آلية العمل

شرط أساسي : سبق أن ربط المستخدم حسابه على Google بحسابه على خدمتك.

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

ملاحظة: يتم تنفيذ الخطوتَين 3 و4 في المرة الأولى التي يحاول فيها المستخدم تسجيل الدخول باستخدام حساب مرتبط. ويتم تخطّي الخطوات عند تسجيل الدخول لاحقًا باستخدام الحساب نفسه.

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

تفعيل ميزة "تسجيل الدخول باستخدام حساب مرتبط" في تطبيق Android

لتفعيل ميزة "تسجيل الدخول باستخدام حساب مرتبط" في تطبيق Android، اتّبِع التعليمات الواردة في دليل تنفيذ ميزة "تسجيل الدخول باستخدام حساب مرتبط" على Android.

معالجة طلبات رمز التفويض من Google

ملاحظة: يجب أن تكون قد سجّلت نقاط نهاية OAuth2 مع Google قبل المتابعة مع الخطوات التالية.

تُرسل Google طلب POST إلى نقطة نهاية الرمز المميّز لحفظ رمز التفويض الذي تتبادله مع الرمز المميّز لتعريف المستخدم. يحتوي الطلب على رمز دخول المستخدم ورمز تفويض OAuth2 صادر عن Google.

قبل حفظ رمز التفويض، عليك التأكّد من أنّك منحت Google رمز الوصول الذي يُعرَف بالرمز client_id.

طلب HTTP

مثال على طلب

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN

يجب أن تكون نقطة نهاية تبادل الرموز المميّزة قادرة على معالجة مَعلمات الطلب التالية:

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

مَعلمات نقطة نهاية الرمز المميّز
code	رمز تفويض Google OAuth2 مطلوب
client_id	مطلوبة معرّف العميل الذي أصدرته لشركة Google
client_secret	مطلوبة سر العميل الذي أصدرته لشركة Google
access_token	سمة مطلوبة: رمز الدخول الذي أصدرته لخدمة Google. ستستخدم هذا للحصول على سياق المستخدم.
grant_type	سمة مطلوبة: يجب ضبط القيمة على urn:ietf:params:oauth:grant-type:reciprocal.

يجب أن تستجيب نقطة نهاية تبادل الرموز المميزة لطلب POST من خلال إجراء ما يلي:

• تأكَّد من أنّه تم منح access_token لشركة Google التي تم تحديدها من خلال client_id.
• يمكنك الردّ إما باستجابة HTTP 200 (حسنًا) إذا كان الطلب صالحًا وتم تبادل رمز المصادقة بنجاح للحصول على رمز تعريف Google، أو رمز خطأ HTTP إذا كان الطلب غير صالح.

استجابة HTTP

تم الإجراء بنجاح

عرض رمز حالة HTTP‏ 200 OK

مثال على ردّ يدل على نجاح العملية

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}

الأخطاء

في حال تلقّي طلب HTTP غير صالح، يجب الردّ باستخدام أحد رموز خطأ HTTP التالية:

رمز حالة HTTP	الجسم	الوصف
400	{"error": "invalid_request"}	لا يتضمّن الطلب مَعلمة، لذا لا يمكن للخادم تنفيذه. وقد يتم عرض هذا الرمز أيضًا إذا كان الطلب يتضمّن مَعلمة غير متوافقة أو يكرّر مَعلمة.
401	{"error": "invalid_request"}	تعذّر مصادقة العميل، مثلاً إذا كان الطلب يحتوي على معرّف عميل أو سر غير صالحَين
401	{"error": "invalid_token"} أدرِج طلب المصادقة "WWW-Authentication: Bearer" في عنوان الاستجابة.	الرمز المميّز للوصول إلى الشريك غير صالح.
403	{"error": "insufficient_permission"} أدرِج طلب المصادقة "WWW-Authentication: Bearer" في عنوان الاستجابة	لا يحتوي رمز دخول الشريك على النطاقات اللازمة لتنفيذ بروتوكول OAuth المتبادل.
500	{"error": "internal_error"}	خطأ في الخادم

يجب أن يحتوي ردّ الخطأ على الحقول التالية :

حقول الاستجابة للأخطاء
error	سلسلة الأخطاء المطلوبة
error_description	وصف الخطأ بلغة يمكن لشخص عادي قراءتها
error_uri	معرّف الموارد المنتظم الذي يقدّم مزيدًا من التفاصيل حول الخطأ

نموذج استجابة الخطأ 400

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "Request was missing the 'access_token' parameter."
}

تبديل رمز التفويض برمز تعريف

عليك استبدال رمز التفويض الذي تلقّيته برمز تعريف Google الذي يحتوي على معلومات عن حساب المستخدم على Google.

لتبديل رمز التفويض برمز تعريف Google، يمكنك طلب نقطة النهاية https://oauth2.googleapis.com/token وضبط المَعلمات التالية:

حقول الطلب
client_id	مطلوبة: معرّف العميل الذي تم الحصول عليه من صفحة بيانات الاعتماد في API Console ستكون هذه عادةً بيانات الاعتماد التي تحمل الاسم تطبيق "المهام الجديدة على Google".
client_secret	مطلوبة سرّ العميل الذي تم الحصول عليه من صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات
code	مطلوبة رمز التفويض الذي تم إرساله في الطلب الأوّلي
grant_type	مطلوبة وفقًا لما هو محدّد في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على authorization_code.

مثال على طلب

POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET

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

يحتوي الردّ على الحقول التالية:

حقول الردود
access_token	رمز مميّز صادر عن Google يرسله تطبيقك لتفويض طلب واجهة برمجة تطبيقات Google
id_token	يحتوي رمز التعريف على معلومات حساب المستخدم على Google. يحتوي قسم "التحقّق من الاستجابة" على تفاصيل عن كيفية فك ترميز استجابة رمز التعريف والتحقّق منها.
expires_in	مدة صلاحية الرمز المميّز للوصول المتبقية بالثواني
refresh_token	رمز مميّز يمكنك استخدامه للحصول على رمز مميّز جديد للوصول تكون رموز إعادة التحميل صالحة إلى أن يبطل المستخدم إذن الوصول.
scope	يتم دائمًا ضبط قيمة هذا الحقل على openid لحالة استخدام "تسجيل الدخول باستخدام الحساب المرتبط".
token_type	نوع الرمز المميّز الذي تم إرجاعه. في الوقت الحالي، يتم دائمًا ضبط قيمة هذا الحقل على Bearer.

نموذج ردّ

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8

{
  "access_token": "Google-access-token",
  "id_token": "Google-ID-token",
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "openid",
  "refresh_token": "Google-refresh-token"
}


POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret

التحقّق من صحة ردّ رمز التعريف