من خلال ميزة ربط حساب 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: الحامل" في عنوان الاستجابة |
رمز دخول الشريك غير صالح. |
| 403 | {"error": "insufficient_permission"}
تضمين اختبار المصادقة "WWW-Auth: الحامل" في عنوان الاستجابة |
لا يحتوي رمز دخول الشريك على النطاقات اللازمة لإجراء بروتوكول 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 ، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني للجهة الخارجية.