تتيح ميزة ربط حساب Google لأصحاب حسابات Google إمكانية الربط بخدماتك بسرعة وسلاسة وأمان ومشاركة البيانات مع Google.
يؤدي تسجيل الدخول إلى الحساب المرتبط إلى تفعيل ميزة تسجيل الدخول بنقرة واحدة باستخدام حساب Google للمستخدمين الذين لديهم حساب Google مرتبط بخدمتك. يؤدي ذلك إلى تحسين تجربة المستخدمين، إذ يمكنهم تسجيل الدخول بنقرة واحدة بدون إعادة إدخال اسم المستخدم وكلمة المرور. كما يقلل ذلك من فرص إنشاء المستخدمين لحسابات مكرّرة على خدمتك.
المتطلّبات
لاستخدام ميزة "تسجيل الدخول إلى حساب مرتبط"، يجب استيفاء المتطلّبات التالية:
- لديك تنفيذ ربط OAuth لحساب Google يتوافق مع مسار رمز تفويض OAuth 2.0. يجب أن يتضمن تنفيذ بروتوكول OAuth نقاط النهاية التالية:
- نقطة نهاية التفويض لمعالجة طلبات التفويض.
- نقطة نهاية الرمز المميّز لمعالجة طلب رموز الدخول وإعادة التحميل.
- نقطة نهاية userinfo لاسترداد معلومات الحساب الأساسية حول المستخدم المرتبط والتي يتم عرضها للمستخدم أثناء عملية تسجيل الدخول إلى الحساب المرتبط.
- لديك تطبيق Android.
آلية العمل
شرط أساسي : ربط المستخدم في السابق حسابه على Google بحسابه على خدمتك.
- يمكنك الموافقة على عرض الحسابات المرتبطة أثناء عملية تسجيل الدخول بنقرة واحدة.
- يظهر للمستخدم رسالة تطلب منك تسجيل الدخول بنقرة واحدة مع خيار تسجيل الدخول إلى خدمتك باستخدام حسابه المرتبط.
- إذا اختار المستخدم المتابعة باستخدام الحساب المرتبط، ترسل Google طلبًا إلى نقطة نهاية الرمز المميّز لحفظ رمز تفويض. ويحتوي الطلب على رمز دخول المستخدم الصادر عن خدمتك ورمز تفويض من Google.
- تستبدل رمز تفويض Google برمز مميز لمعرّف Google يحتوي على معلومات حول حساب المستخدم على Google.
- يتلقّى تطبيقك أيضًا رمزًا مميّزًا للمعرّف عند انتهاء التدفق وطابِقه مع معرّف المستخدم في الرمز المميّز للمعرّف الذي استلمه خادمك من أجل تسجيل دخول المستخدم إلى تطبيقك.
تنفيذ ميزة "تسجيل الدخول إلى الحساب المرتبط" في تطبيق 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 |
مطلوب رمز تفويض 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 (OK) إذا كان الطلب صالحًا وتم استبدال رمز المصادقة بالرمز المميز لـ Google ID، أو برمز خطأ في 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-Auth: Bearer" في عنوان الاستجابة |
رمز دخول الشريك غير صالح. |
403 | {"error": "insufficient_permission"}
تضمين تحدي مصادقة "WWW-Auth: Bearer" في عنوان الاستجابة |
لا يحتوي رمز دخول الشريك على النطاقات اللازمة لإجراء بروتوكول 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 يحتوي على معلومات حول حساب المستخدم على Google.
لاستبدال رمز تفويض برمز مميّز لمعرّف Google، يمكنك طلب نقطة النهاية https://oauth2.googleapis.com/token
وضبط المَعلمات التالية:
حقول الطلب | |
---|---|
client_id |
مطلوب معرّف العميل الذي تم الحصول عليه من صفحة بيانات الاعتماد لوحدة تحكم واجهة برمجة التطبيقات. وستكون هذه عادةً بيانات الاعتماد التي تحمل الاسم تطبيق "المهام الجديدة من 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 API |
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، ولكن ملكية الجهة الخارجية
ربما تغير حساب بريدك الإلكتروني منذ ذلك الحين.