ربط انسيابي مع OAuth وتسجيل الدخول بحساب Google

ملخص

يضيف الربط المبسط لتسجيل الدخول إلى Google المستند إلى OAuth تسجيل الدخول بحساب Google أعلى رابط OAuth . يوفر هذا تجربة ربط سلسة لمستخدمي Google ، كما أنه يتيح ربط الحسابات للمستخدمين الذين سجلوا في خدمتك بهوية غير تابعة لـ Google.

لإجراء ربط الحساب باستخدام OAuth وتسجيل الدخول إلى Google ، اتبع الخطوات العامة التالية:

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

الشكل 3 . ربط الحساب على هاتف المستخدم من خلال الربط المبسط

ترتبط الحسابات باستخدام معيار الصناعة OAuth 2.0 الضمني وتدفق كود التفويض . الخدمة الخاص بك يجب أن يدعم إذن المتوافقة مع 2.0 أوث والنهاية الصرف رمزية. بالإضافة إلى ذلك، يجب أن لديك نقطة النهاية الصرف رمزية دعم JSON الويب رمز (JWT) تأكيدات وتنفيذ check ، create ، و get النوايا.

احصل على معرّف وسر عميل واجهة برمجة تطبيقات Google

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

  1. افتح صفحة بيانات الاعتماد لوحدة تحكم Google API .
  2. إنشاء أو تحديد مشروع Google APIs.

    إذا لم يكن مشروعك يحتوي على معرّف عميل لنوع تطبيق الويب ، فانقر على إنشاء بيانات اعتماد> معرّف عميل OAuth لإنشاء واحد. تأكد من تضمين مجال موقعك في مربع أصول جافا سكريبت المعتمدة . عند إجراء اختبارات أو تطوير محلي ، يجب إضافة كل من http://localhost و http://localhost:<port_number> إلى حقل أصول JavaScript المعتمدة .

نفِّذ خادم OAuth

تحقق من وجود حساب مستخدم موجود

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

إذا كان حساب Google المقابل موجودًا بالفعل في نظام المصادقة الخاص بك ، فإن نقطة نهاية تبادل الرموز الخاصة بك تستجيب بـ account_found=true . إذا كان حساب Google لا يتطابق مع مستخدم حالي ، فإن نقطة نهاية تبادل الرمز الخاص بك تُرجع خطأ HTTP 404 غير موجود مع account_found=false .

الطلب يحتوي على النموذج التالي:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES

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

معلمات نقطة نهاية الرمز المميز
intent لهذه الطلبات ، يتم check من قيمة هذه المعلمة.
grant_type نوع الرمز المميز الذي يتم تبادله. لهذه الطلبات ، يكون لهذه المعلمة القيمة urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion رمز ويب JSON (JWT) يوفر تأكيدًا موقعًا لهوية مستخدم Google. يحتوي JWT على معلومات تتضمن معرف حساب Google للمستخدم واسمه وعنوان بريده الإلكتروني.

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

تحقق من صحة تأكيد 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 ، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني للجهة الخارجية.

تحقق مما إذا كان حساب Google موجودًا بالفعل في نظام المصادقة الخاص بك

تحقق مما إذا كانت أي من الشروط التالية صحيحة:

  • معرف حساب Google ، الموجود في الحقل sub للتأكيد ، موجود في قاعدة بيانات المستخدم الخاصة بك.
  • يتطابق عنوان البريد الإلكتروني في التأكيد مع مستخدم في قاعدة بيانات المستخدم الخاصة بك.

إذا كان أي من الشرطين صحيحًا ، فهذا يعني أن المستخدم قد قام بالتسجيل بالفعل. في هذه الحالة ، قم بإرجاع رد مثل ما يلي:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

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

إذا لم يتطابق معرف حساب Google ولا عنوان البريد الإلكتروني المحدد في التأكيد مع مستخدم في قاعدة البيانات الخاصة بك ، فهذا يعني أن المستخدم لم يشترك بعد. في هذه الحالة ، تحتاج نقطة نهاية تبادل الرمز المميز إلى الرد بخطأ HTTP 404 الذي يحدد "account_found": "false" ، كما في المثال التالي:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}
عندما تتلقى Google استجابة الخطأ 404 مع ظهور خطأ "account_found": "false" ، يعرض Google مربع حوار للمستخدم لطلب الموافقة على إنشاء حساب جديد والوصول إلى النطاقات المطلوبة. بعد حصول Google على موافقة المستخدم ، تتصل Google بنقطة نهاية تبادل الرمز المميز بقيمة معلمة intent تعيينها create وتتضمن رمزًا مميزًا للمعرف يحتوي على معلومات ملف تعريف المستخدم مع الطلب.

التعامل مع الربط التلقائي

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

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

الطلب يحتوي على النموذج التالي:

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

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES

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

معلمات نقطة نهاية الرمز المميز
intent بالنسبة لهذه الطلبات ، تكون قيمة هذه المعلمة هي get .
grant_type نوع الرمز المميز الذي يتم تبادله. لهذه الطلبات ، هذه المعلمة لها القيمة urn:ietf:params:oauth:grant-type:jwt-bearer
assertion رمز ويب JSON (JWT) يوفر تأكيدًا موقعًا لهوية مستخدم Google. يحتوي JWT على معلومات تتضمن معرف حساب Google للمستخدم واسمه وعنوان بريده الإلكتروني.
scope اختياري: أي نطاقات قمت بتكوين Google لطلبها من المستخدمين.

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

تحقق من صحة تأكيد 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 ، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني للجهة الخارجية.

تحقق مما إذا كان حساب Google موجودًا بالفعل في نظام المصادقة الخاص بك

تحقق مما إذا كانت أي من الشروط التالية صحيحة:

  • معرف حساب Google ، الموجود في الحقل sub للتأكيد ، موجود في قاعدة بيانات المستخدم.
  • يتطابق عنوان البريد الإلكتروني في التأكيد مع مستخدم في قاعدة بيانات المستخدم الخاصة بك.

في بعض الحالات ، قد يفشل ربط الحساب بناءً على رمز المعرف المميز للمستخدم. إذا فعلت ذلك لأي سبب من الأسباب ، تحتاج نقطة نهاية تبادل الرمز المميز إلى الرد بخطأ HTTP 401 يحدد error=linking_error ، كما يوضح المثال التالي:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}
عندما تتلقى Google استجابة خطأ 401 مع linking_error ، تستدعي Google نقطة نهاية تبادل الرموز مع ما يلي في الطلب:

  • و intent مجموعة المعلمة إلى create
  • JWT مع الرمز المميز للمعرف ومعلومات ملف تعريف المستخدم

التعامل مع إنشاء الحساب عبر تسجيل الدخول بحساب جوجل

عندما يحتاج المستخدم إلى إنشاء حساب على خدمتك ، تقدم Google طلبًا إلى نقطة نهاية تبادل الرموز التي تحدد intent=create .

الطلب يحتوي على النموذج التالي:

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

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT[&NEW_ACCOUNT_INFO]

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

معلمات نقطة نهاية الرمز المميز
intent بالنسبة لهذه الطلبات ، يتم create قيمة هذه المعلمة.
grant_type نوع الرمز المميز الذي يتم تبادله. لهذه الطلبات ، يكون لهذه المعلمة القيمة urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion رمز ويب JSON (JWT) يوفر تأكيدًا موقعًا لهوية مستخدم Google. يحتوي JWT على معلومات تتضمن معرف حساب Google للمستخدم واسمه وعنوان بريده الإلكتروني.

يحتوي JWT داخل معلمة assertion على معرف حساب Google للمستخدم واسمه وعنوان بريده الإلكتروني ، والذي يمكنك استخدامه لإنشاء حساب جديد على خدمتك.

للاستجابة لطلبات إنشاء الحساب ، يجب أن تنفذ نقطة نهاية تبادل الرمز المميز الخطوات الموضحة في القسمين التاليين.

تحقق من صحة تأكيد 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 ، ولكن ربما تغيرت ملكية حساب البريد الإلكتروني للجهة الخارجية.

التحقق من صحة معلومات المستخدم وإنشاء حساب جديد

تحقق مما إذا كانت أي من الشروط التالية صحيحة:

  • معرف حساب Google ، الموجود في الحقل sub للتأكيد ، موجود في قاعدة بيانات المستخدم الخاصة بك.
  • يتطابق عنوان البريد الإلكتروني في التأكيد مع مستخدم في قاعدة بيانات المستخدم الخاصة بك.

إذا كان أي من الشرطين صحيحًا ، فاطلب من المستخدم ربط حسابه الحالي بحسابه على Google. للقيام بذلك ، قم بالرد على الطلب بخطأ HTTP 401 الذي يحدد error=linking_error ويعطي عنوان البريد الإلكتروني للمستخدم باعتباره login_hint . فيما يلي نموذج للرد:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

عندما تتلقى Google استجابة خطأ 401 مع linking_error ، ترسل Google المستخدم إلى نقطة نهاية التفويض باستخدام login_hint . يكمل المستخدم ربط الحساب باستخدام تدفق ربط OAuth في متصفحه.

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

عند اكتمال الإنشاء ، قم بإصدار رمز وصول وإرجاع القيم الموجودة في كائن JSON في نص استجابة HTTPS ، كما في المثال التالي:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

التحقق من صحة التنفيذ الخاص بك

يمكنك التحقق من صحة التنفيذ باستخدام أداة OAuth 2.0 Playground .

في الأداة ، قم بالخطوات التالية:

  1. انقر على التهيئة لفتح نافذة تهيئة OAuth 2.0.
  2. في حقل تدفق OAuth ، حدد من جانب العميل .
  3. في حقل نقاط نهاية OAuth ، حدد مخصص .
  4. حدد نقطة نهاية OAuth 2.0 ومعرف العميل الذي عينته لـ Google في الحقول المقابلة.
  5. في قسم الخطوة 1 ، لا تحدد أيًا من نطاقات Google. بدلاً من ذلك ، اترك هذا الحقل فارغًا أو اكتب نطاقًا صالحًا لخادمك (أو سلسلة عشوائية إذا كنت لا تستخدم نطاقات OAuth). عند الانتهاء ، انقر فوق تخويل واجهات برمجة التطبيقات .
  6. في قسمي الخطوة 2 والخطوة 3 ، انتقل عبر تدفق OAuth 2.0 وتحقق من أن كل خطوة تعمل على النحو المنشود.

يمكنك التحقق من صحة التنفيذ باستخدام أداة Google Account Linking Demo .

في الأداة ، قم بالخطوات التالية:

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