تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

المتطلبات

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

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

آلية العمل

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

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

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

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

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

التعامل مع طلبات رمز التفويض من 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

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

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

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

تأكَّد من منح Google رقم access_token من قِبل client_id.
استجب إما باستجابة HTTP 200 (OK) إذا كان الطلب صالحًا وتم استبدال رمز المصادقة بنجاح برمز مميز لمعرّف 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: الحامل" اختبار المصادقة في عنوان الردّ	رمز دخول الشريك غير صالح.
403	`{"error": "insufficient_permission"}` تضمين "مصادقة WWW: الحامل" اختبار المصادقة في عنوان الردّ	لا يحتوي رمز دخول الشريك على النطاقات اللازمة لتنفيذ بروتوكول OAuth المتبادل.
500	`{"error": "internal_error"}`	خطأ في الخادم

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

حقول الرد على الخطأ
`error`	سلسلة خطأ مطلوبة
`error_description`	وصف للخطأ يمكن للمستخدمين قراءته
`error_uri`	معرّف موارد منتظم (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."
}

رمز تفويض Exchange للرمز المميّز للمعرّف

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

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

حقول الطلب
`client_id`	مطلوب هو معرِّف العميل الذي يتم الحصول عليه من صفحة بيانات الاعتماد في وحدة تحكُّم واجهة برمجة التطبيقات. وتكون هذه عادةً بيانات الاعتماد التي تحمل الاسم تطبيق جديد لمهام Google على 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

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

التحقق من صحة تأكيد JWT وفك ترميزه

يمكنك التحقق من صحة تأكيد JWT وفك ترميزه باستخدام مكتبة فك ترميز JWT بلغتك. استخدام مفاتيح Google العامة، متاحة في JWK أو PEM، للتأكّد من توقيع الرمز المميز.

عند فك ترميز النص، يظهر تأكيد JWT على النحو التالي:

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

بالإضافة إلى التحقّق من توقيع الرمز المميّز، تأكَّد من أنّ التأكيد جهة الإصدار (الحقل iss) هي https://accounts.google.com، بحيث يمكن لشريحة الجمهور (الحقل aud) هو معرّف العميل الذي تم تعيينه، ولم تنتهِ صلاحية الرمز المميّز. (حقل exp).

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

الحالات التي تكون فيها Google موثوقة:

السمة email هي اللاحقة @gmail.com، وهذا حساب Gmail.
email_verified صحيح وتم ضبط hd، هذا حساب G Suite.

يمكن للمستخدمين التسجيل للحصول على حسابات Google بدون استخدام Gmail أو G Suite. فعندما لا يحتوي email على اللاحقة @gmail.com وhd غير موجود في Google موثوقة وكلمة المرور أو طرق التحقق الأخرى للتحقق المستخدم. يمكن أن يكون email_verified صحيحًا أيضًا لأن Google تحققت في البداية من صحة المستخدم عند إنشاء حساب Google، ولكن ملكية الجهة الخارجية ربما تغير حساب بريدك الإلكتروني منذ ذلك الحين.