تتيح ميزة ربط حساب 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 تستضيف email_verified لعنوان بريد إلكتروني. في الحالات التي تكون فيها Google مخولة ، من المعروف حاليًا أن المستخدم هو المالك الشرعي للحساب ويمكنك تخطي كلمة المرور أو طرق التحقق الأخرى. بخلاف ذلك ، يمكن استخدام هذه الطرق للتحقق من الحساب قبل الربط.
الحالات التي يكون فيها Google موثوقًا:
- يحتوي
emailعلى لاحقة@gmail.com، وهذا حساب Gmail. -
email_verifiedصحةemail_verifiedوتم تعيينhd، هذا حساب G Suite.
يمكن للمستخدمين التسجيل في حسابات Google دون استخدام Gmail أو G Suite. عندما لا يحتوي email على لاحقة @gmail.com ويكون hd غائبًا ، لا يكون Google موثوقًا ويوصى باستخدام كلمة المرور أو طرق التحدي الأخرى للتحقق من المستخدم. يمكن أيضًا أن يكون email_verfied صحيحًا نظرًا لأن Google قد تحققت في البداية من المستخدم عند إنشاء حساب Google ، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني للجهة الخارجية.