يتم ربط الحسابات باستخدام التدفقات الضمنية والضمنية ورموز التفويض الخاصة ببروتوكول OAuth 2.0. يجب أن تتوافق خدمتك مع نقاط نهاية التفويض وتبادل الرموز المميّزة المتوافقة مع بروتوكول OAuth 2.0.
في عملية الموافقة الضمنية، تفتح Google نقطة نهاية التفويض في browser المستخدم. بعد تسجيل الدخول بنجاح، يمكنك إعادة رمز دخول صالح لفترة طويلة إلى Google. يتم الآن تضمين رمز الوصول هذا في كل طلب يتم إرساله من Google.
في مسار رمز التفويض، تحتاج إلى نقطتَي نهاية:
نقطة نهاية التفويض التي تعرِض واجهة مستخدم تسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول من قبل تُنشئ نقطة نهاية التفويض أيضًا код التفويض الذي ينتهي صلاحيته بعد فترة قصيرة لتسجيل موافقة المستخدمين على الوصول المطلوب.
نقطة نهاية تبادل الرمز المميز، وهي المسؤولة عن نوعين من التبادلات:
- تبديل رمز التفويض برمز مميّز طويل الأمد لإعادة التحميل ورمز مميّز قصير الأمد للدخول يحدث هذا التبادل عندما ينتقل المستخدم إلى مسار ربط الحساب.
- يتم استبدال رمز مميّز طويل الأمد لإعادة التحميل برمز دخول قصير الأمد. يحدث هذا التبادل عندما تحتاج Google إلى رمز دخول مميّز جديد لأنّه انتهت صلاحية الرمز المميّز السابق.
اختيار مسار OAuth 2.0
على الرغم من أنّ التدفق الضمني أبسط في التنفيذ، تنصح Google بعدم انتهاء صلاحية رموز الدخول الصادرة عن التدفق الضمني أبدًا. ويرجع ذلك إلى أن المستخدم يضطر إلى ربط حسابه مرة أخرى بعد انتهاء صلاحية الرمز المميز بالتدفق الضمني. إذا كنت بحاجة إلى انتهاء صلاحية الرمز المميّز لأسباب تتعلق بالأمان، ننصحك بشدة باستخدام مسار رمز التفويض بدلاً من ذلك.
إرشادات التصميم
يصف هذا القسم متطلبات التصميم والاقتراحات المتعلقة بشاشة المستخدم التي تستضيفها لمسارات ربط OAuth. بعد أن يطلب تطبيق Google الحصول على هذه الخدمة، تعرض منصتك صفحة تسجيل الدخول إلى Google وشاشة موافقة ربط الحساب للمستخدم. يتم توجيه المستخدم مرة أخرى إلى تطبيق Google بعد منح الموافقة على ربط الحسابات.
المتطلبات
- عليك إبلاغنا بأنّ حساب المستخدم سيتم ربطه بخدمة Google، وليس بمنتج معيّن من Google، مثل Google Home أو "مساعد Google".
اقتراحات
ننصحك باتّباع الخطوات التالية:
عرض سياسة خصوصية Google: أدرِج رابطًا يؤدي إلى سياسة خصوصية Google على شاشة الموافقة.
البيانات التي ستتم مشاركتها: استخدِم لغة واضحة وموجزة لإعلام المستخدم بال data التي تطلبها Google منه والغرض من ذلك.
عبارة واضحة تحثّ على اتّخاذ إجراء: يجب تضمين عبارة واضحة للحث على اتّخاذ إجراء على شاشة طلب الموافقة، مثل "أوافق وأريد الربط". ويعود سبب ذلك إلى أنّ المستخدمين يحتاجون إلى معرفة البيانات التي سيُطلب منهم مشاركتها مع Google لربط حساباتهم.
إمكانية إلغاء الاشتراك: يجب توفير طريقة للمستخدمين للرجوع أو الإلغاء إذا اختَروا عدم الربط.
عملية تسجيل دخول واضحة: تأكَّد من توفُّر طريقة واضحة للمستخدمين لتسجيل الدخول إلى حساباتهم على Google، مثل حقول لاسم المستخدم وكلمة المرور أو تسجيل الدخول باستخدام حساب Google.
إمكانية إلغاء الربط: يجب توفير آلية تتيح للمستخدمين إلغاء ربط الحساب، مثل عنوان URL يؤدي إلى إعدادات حساباتهم على منصتك. بدلاً من ذلك، يمكنك تضمين رابط يؤدي إلى حساب Google حيث يمكن للمستخدمين إدارة حساباتهم المرتبطة.
القدرة على تغيير حساب المستخدم. اقترح طريقة للمستخدمين للتبديل بين حساباتهم. ويكون هذا مفيدًا بشكل خاص إذا كان المستخدمون يميلون إلى امتلاك حسابات متعددة.
- إذا كان على المستخدم إغلاق شاشة الموافقة لتبديل الحسابات، أرسِل خطأً قابلاً للاسترداد إلى Google حتى يتمكّن المستخدم من تسجيل الدخول إلى الحساب المطلوب باستخدام ربط OAuth ومسار الموافقة الضمنية.
أدرِج شعارك. عرض شعار شركتك على شاشة الموافقة استخدِم إرشادات الأنماط لوضع شعارك. إذا كنت ترغب أيضًا في عرض شعار Google، يمكنك الاطّلاع على الشعارات والعلامات التجارية.
创建项目
如需创建使用账号关联的项目，请执行以下操作：
- 点击 Create project。
- 输入名称或接受生成的建议。
- 确认或修改所有剩余字段。
- 点击创建。
如需查看项目 ID，请执行以下操作：
- 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。
配置 OAuth 权限请求页面
Google 账号关联流程包含一个权限请求页面，该页面会告知用户哪个应用在请求访问其数据、请求访问哪些类型的数据，以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。
- 打开 Google API 控制台的 OAuth 同意屏幕页面。
- 如果出现提示，请选择您刚刚创建的项目。
在“OAuth 同意屏幕”页面上，填写表单，然后点击“保存”按钮。
应用名称：征求用户同意的应用的名称。名称应准确反映您的应用，并与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求界面上。
应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中
支持电子邮件地址：供用户就其同意问题与您联系。
Google API 的范围：借助范围，您的应用可以访问用户的非公开 Google 数据。对于 Google 账号关联使用情形，默认范围（电子邮件地址、个人资料、openid）就足够了，您无需添加任何敏感范围。一般来说，最佳做法是在需要访问权限时逐步请求权限范围，而不是提前请求。了解详情。
已获授权的网域：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。应用的链接必须托管在已获授权的网域上。了解详情。
应用首页链接：应用的首页。必须托管在已获授权的网域上。
应用隐私权政策链接：显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。
应用服务条款链接（可选）：必须托管在已获授权的网域上。
图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面
查看“验证状态”，如果您的应用需要验证，请点击“提交以供验证”按钮，提交应用以供验证。如需了解详情，请参阅 OAuth 验证要求。
تنفيذ خادم OAuth
يتألف تنفيذ خادم OAuth 2.0 من مسار رمز التفويض من نقطتَي النهاية، اللتين تتيحهما خدمتك باستخدام بروتوكول HTTPS. نقطة النهاية الأولى هي نقطة نهاية التفويض، وهي المسئولة عن إيجاد أو الحصول على موافقة المستخدمين على الوصول إلى البيانات. تقدم نقطة نهاية التفويض واجهة المستخدم الخاصة بتسجيل الدخول للمستخدمين الذين لم يسجّلوا الدخول من قبل ويسجّلون الموافقة على الوصول المطلوب. نقطة النهاية الثانية هي نقطة نهاية تبادل الرموز، والتي للحصول على سلاسل مشفرة، تسمى الرموز المميزة، والتي تمنح المستخدم الوصول إلى خدمتك.
عندما يحتاج أحد تطبيقات Google إلى استدعاء إحدى واجهات برمجة التطبيقات الخاصة بخدمتك، تستخدم Google نقاط النهاية هذه معًا للحصول على إذن من المستخدمين بطلب واجهات برمجة التطبيقات هذه نيابةً عنه.
تتضمن جلسة تدفق رمز تفويض OAuth 2.0 التي بدأتها Google ما يلي: التدفق التالي:
- تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا لم يكن التدفق على جهاز الصوت فقط لتنفيذ إجراء، وتنقل Google إلى الهاتف.
- يسجِّل المستخدم الدخول، إذا لم يكن مسجّلاً الدخول، ويمنح Google الإذن الوصول إلى بياناتهم باستخدام واجهة برمجة التطبيقات إذا لم يسبق لهم منحها إذن.
- تنشئ الخدمة رمز تفويض وترسله إلى Google. للقيام بذلك، لذا، عليك إعادة توجيه متصفح المستخدم إلى Google باستخدام رمز التفويض المرفق بالطلب.
- ترسل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة، يتحقق من صحة الرمز ويعرض رمز دخول الرمز المميّز لإعادة التحميل رمز الدخول هو رمز مميز طويل الأجل يمكن لخدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميز لإعادة التحميل طويل الأمد هو رمز مميز يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند تنتهي صلاحيته.
- بعد أن يكمل المستخدم عملية ربط الحساب، يحتوي الطلب المرسل من Google على رمز دخول.
التعامل مع طلبات التفويض
عندما تحتاج إلى ربط الحساب باستخدام رمز تفويض OAuth 2.0 ترسل Google المستخدم إلى نقطة نهاية التفويض من خلال طلب يتضمن المعلَمات التالية:
| مَعلمات نقطة نهاية التفويض | |
|---|---|
client_id |
معرِّف العميل الذي عيّنته لشركة Google. |
redirect_uri |
عنوان URL الذي ترسل إليه الرد على هذا الطلب. |
state |
يشير هذا المصطلح إلى قيمة محاسبة يتم إرسالها إلى Google بدون أي تغيير في معرّف الموارد المنتظم (URI) لإعادة التوجيه. |
scope |
اختياري: مجموعة من سلاسل النطاقات مفصولة بمسافات تحدِّد البيانات التي تطلب Google إذنًا لها. |
response_type |
نوع القيمة المطلوب عرضها في الرد. بالنسبة إلى OAuth 2.0
مسار رمز التفويض، يكون نوع الردّ دائمًا code.
|
user_locale |
إعدادات اللغة في حساب Google RFC5646 يُستخدم لترجمة المحتوى إلى اللغة المفضلة للمستخدم. |
على سبيل المثال، إذا كانت نقطة نهاية التفويض متاحة على
https://myservice.example.com/auth، قد يظهر الطلب على النحو التالي:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
لتتمكَّن نقطة نهاية التفويض من معالجة طلبات تسجيل الدخول، عليك إجراء ما يلي: الخطوات:
- تأكَّد من أنّ
client_idيتطابق مع معرِّف العميل الذي أرسلته إلى Google، وأنّredirect_uriيتطابق مع عنوان URL لإعادة التوجيه الذي توفّره Google لخدمتك. وتعد عمليات التحقق هذه مهمة لمنع منح الوصول إلى تطبيقات العميل غير المقصودة أو التي تم إعدادها بشكلٍ غير صحيح إذا كنت تدعم عدة مستخدمين مسارات OAuth 2.0، تأكَّد أيضًا من أنّresponse_typeهوcode. - تحقق مما إذا كان المستخدم قد سجّل الدخول إلى خدمتك. إذا لم يسجّل المستخدم الدخول، لإكمال عملية تسجيل الدخول أو الاشتراك في الخدمة.
- أنشئ رمز تفويض لتتمكّن Google من استخدامه للوصول إلى واجهة برمجة التطبيقات. يمكن أن تكون رمز التفويض أي قيمة سلسلة، ولكن يجب أن تكون التي تمثل المستخدم والعميل الذي يمثل الرمز المميز وانتهاء صلاحية الرمز الوقت، ويجب ألا يمكن تخمينه. أنت عادةً ما تصدر التفويض التي تنتهي صلاحيتها بعد 10 دقائق تقريبًا.
- تأكَّد من أنّ عنوان URL الذي تحدّده المَعلمة
redirect_uriيحتوي على النموذج التالي:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- إعادة توجيه متصفح المستخدم إلى عنوان URL المحدد من خلال
مَعلمة
redirect_uri. قم بتضمين رمز التفويض الذي قمت التي تم إنشاؤها للتو وقيمة الحالة الأصلية غير المعدلة عند إعادة التوجيه من خلال إلحاق المعلمتَينcodeوstate. فيما يلي مثال على عنوان URL الناتج:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
التعامل مع طلبات تبادل الرموز المميّزة
تكون نقطة نهاية تبادل الرموز المميّزة لخدمتك مسؤولة عن نوعَين من الرموز المميّزة التبادلات:
- استبدال رموز التفويض برموز الدخول ورموز إعادة التحميل
- الرموز المميزة لإعادة تحميل Exchange لرموز الدخول
تشمل طلبات تبادل الرموز المميّزة المَعلمات التالية:
| مَعلمات نقطة نهاية تبادل الرموز المميّزة | |
|---|---|
client_id |
سلسلة تحدِّد مصدر الطلب على أنّه Google. يجب أن تكون هذه السلسلة في نظامك كمعرّف فريد لشركة Google. |
client_secret |
سلسلة سرية سجّلتها لدى Google لخدمتك. |
grant_type |
تمثّل هذه السمة نوع الرمز المميّز الذي يتم تبادله. إنها إما
authorization_code أو refresh_token |
code |
عندما تكون grant_type=authorization_code، تكون هذه المعلمة هي
الرمز الذي تلقّته Google من عملية تسجيل الدخول أو من تبادل الرموز المميّزة
النهائية. |
redirect_uri |
عندما تكون grant_type=authorization_code، تكون هذه المعلمة هي
عنوان URL المستخدم في طلب التفويض الأولي. |
refresh_token |
عندما تكون grant_type=refresh_token، تكون هذه المعلمة هي
الرمز المميّز لإعادة التحميل الذي تلقّته Google من نقطة نهاية تبادل الرموز المميّزة |
استبدال رموز التفويض برموز الدخول ورموز إعادة التحميل
بعد أن يسجِّل المستخدم دخوله وترجع نقطة نهاية التفويض فترة قصيرة رمز التفويض إلى Google، ترسل Google طلبًا إلى عملية تبادل الرمز المميّز نقطة نهاية لاستبدال رمز التفويض برمز الدخول وإعادة التحميل الرمز المميز.
بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي authorization_code،
تشير القيمة code إلى قيمة رمز التفويض الذي منحته سابقًا.
إلى Google. فيما يلي مثال على طلب لتبادل
رمز التفويض لرمز الدخول والرمز المميز لإعادة التحميل:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
لتبادل رموز التفويض لرمز دخول ورمز مميز لإعادة التحميل، يجب
تتجاوب نقطة نهاية تبادل الرموز المميّزة مع طلبات POST من خلال تنفيذ ما يلي:
الخطوات:
- تأكَّد من أنّ
client_idيحدّد مصدر الطلب على أنّه جهة معتمَدة الأصل، وأنclient_secretتتطابق مع القيمة المتوقعة. - تحقق من أن رمز التفويض صالح وليس منتهي الصلاحية، وأن معرِّف العميل المحدّد في الطلب يتطابق مع معرِّف العميل المرتبط رمز التفويض.
- تأكَّد من أنّ عنوان URL الذي تحدّده مَعلمة
redirect_uriمتطابق. إلى القيمة المستخدمة في طلب التفويض الأولي. - إذا لم تتمكن من التحقق من جميع المعايير السابقة، اعرض HTTP
400 خطأ "طلب غير صالح" مع
{"error": "invalid_grant"}كنص الرسالة. - بخلاف ذلك، يمكنك استخدام رقم تعريف المستخدم من رمز التفويض لإعادة تحميل الصفحة. ورمز الدخول. يمكن أن تكون هذه الرموز المميزة أي قيمة سلسلة، لكنها أن يمثل المستخدم والعميل الذي يستخدم الرمز المميز بشكل فريد، يجب ألا يكون قابلاً للتخمين. بالنسبة لرموز الدخول، سجل أيضًا وقت انتهاء صلاحية الرمز، والذي يكون عادةً بعد ساعة من إصدار الرمز. لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل.
- عرض كائن JSON التالي في نص استجابة HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
تخزِّن Google رمز الدخول والرمز المميّز لإعادة التحميل للمستخدم والسجلّات. انتهاء صلاحية رمز الدخول. وعند انتهاء صلاحية رمز الدخول، تستخدم Google الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد من نقطة نهاية تبادل الرموز المميّزة.
الرموز المميزة لإعادة تحميل Exchange لرموز الدخول
عند انتهاء صلاحية رمز الدخول، ترسل Google طلبًا إلى عملية تبادل الرمز المميّز. نقطة نهاية لاستبدال رمز تحديث مميز برمز دخول جديد.
بالنسبة إلى هذه الطلبات، تكون قيمة grant_type هي refresh_token، والقيمة
لـ refresh_token هي قيمة الرمز المميز لإعادة التحميل الذي منحته سابقًا
Google. في ما يلي مثال على طلب استبدال رمز مميّز لإعادة التحميل.
لرمز الدخول:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
لاستبدال رمز مميز لإعادة التحميل برمز دخول، يجب أن تكون نقطة نهاية تبادل الرموز المميّزة
يستجيب لطلبات POST من خلال تنفيذ الخطوات التالية:
- تأكَّد من أنّ
client_idيحدّد مصدر الطلب على أنّه Google أنclient_secretتتطابق مع القيمة المتوقعة. - تأكَّد من صلاحية الرمز المميّز لإعادة التحميل ومن أنّ معرِّف العميل المحدَّد في يتطابق الطلب مع معرِّف العميل المرتبط بالرمز المميّز لإعادة التحميل.
- إذا لم تتمكن من التحقق من جميع المعايير السابقة، اعرض HTTP 400
حدث خطأ في الطلب غير صالح مع
{"error": "invalid_grant"}كنص أساسي. - بخلاف ذلك، يمكنك استخدام رقم تعريف المستخدم من الرمز المميّز لإعادة التحميل لإنشاء إذن وصول. الرمز المميز. يمكن أن تكون هذه الرموز المميزة أي قيمة سلسلة، ولكن يجب أن يمثل المستخدم والعميل الذي يمثله الرمز المميز، ويجب ألا يمكن تخمينه. بالنسبة لرموز الدخول، سجّل أيضًا وقت انتهاء صلاحية الرمز، عادةً بعد ساعة من إصدار الرمز المميّز.
- عرض كائن JSON التالي في نص HTTPS
الرد:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
处理 userinfo 请求
userinfo 端点是受 OAuth 2.0 保护的资源，会返回关联用户的声明。实现和托管 userinfo 端点是可选的，但以下用例除外：
从您的令牌端点成功检索到访问令牌后，Google 会向您的 userinfo 端点发送请求，以检索关联用户的基本个人资料信息。
| userinfo 端点请求标头 | |
|---|---|
Authorization header |
Bearer 类型的访问令牌。 |
例如，如果您的 userinfo 端点可通过
https://myservice.example.com/userinfo 时，请求可能如下所示：
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
为了让 userinfo 端点能够处理请求，请执行以下步骤：
- 从 Authorization 标头中提取访问令牌，并返回与访问令牌相关联的用户的信息。
- 如果访问令牌无效，则使用
WWW-Authenticate响应标头返回 HTTP 401 Unauthorized 错误。下面是一个 userinfo 错误响应示例：HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果访问令牌有效，则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回答：
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }userinfo 端点响应 sub系统中用于识别用户的唯一 ID。 email用户的电子邮件地址。 given_name可选：用户的名字。 family_name可选：用户的姓氏。 name可选：用户的全名。 picture可选：用户的个人资料照片。
التحقّق من صحة عملية التنفيذ
يمكنك التحقّق من صحة التنفيذ باستخدام أداة ساحة اختبار OAuth 2.0.
في الأداة، اتّبِع الخطوات التالية:
- انقر على رمز الإعدادات لفتح نافذة ضبط OAuth 2.0.
- في حقل مسار OAuth، اختَر جانب العميل.
- في الحقل نقاط نهاية OAuth، اختَر مخصّص.
- حدِّد نقطة نهاية OAuth 2.0 ومعرّف العميل الذي عيّنته لخدمة Google في الحقول المقابلة.
- في قسم الخطوة 1، لا تختَر أيّ نطاقات Google. بدلاً من ذلك، اترك هذا الحقل فارغًا أو اكتب نطاقًا صالحًا لخادمك (أو سلسلة عشوائية إذا كنت لا تستخدم نطاقات OAuth). عند الانتهاء، انقر على تفويض واجهات برمجة التطبيقات.
- في القسمَين الخطوة 2 والخطوة 3، انتقِل إلى مسار OAuth 2.0 وتحقَّق من أنّ كل خطوة تعمل على النحو المطلوب.
يمكنك التحقّق من صحة عملية التنفيذ باستخدام أداة العرض التوضيحي لربط حساب Google.
في الأداة، اتّبِع الخطوات التالية:
- انقر على الزر تسجيل الدخول باستخدام حساب Google.
- اختَر الحساب الذي تريد ربطه.
- أدخِل رقم تعريف الخدمة.
- يمكنك اختياريًا إدخال نطاق واحد أو أكثر لطلب الوصول إليه.
- انقر على بدء العرض التجريبي.
- أكِّد أنّه يمكنك الموافقة على طلب ربط الحساب ورفضه عندما يُطلب منك ذلك.
- تأكَّد من إعادة توجيهك إلى منصّتك.