يتم ربط الحسابات باستخدام التدفقات الضمنية والضمنية ورموز التفويض الخاصة ببروتوكول 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 the project
To create your project to use account linking:
- Go to the Google API Console.
- Click Create project.
- Enter a name or accept the generated suggestion.
- Confirm or edit any remaining fields.
- Click Create.
To view your project ID:
- Go to the Google API Console.
- Find your project in the table on the landing page. The project ID appears in the ID column.
Configure your OAuth Consent Screen
The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.
- Open the OAuth consent screen page of the Google APIs console.
- If prompted, select the project you just created.
On the "OAuth consent screen" page, fill out the form and click the “Save” button.
Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.
Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings
Support email: For users to contact you with questions about their consent.
Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.
Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.
Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.
Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.
Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.
Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery
Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.
تنفيذ خادم 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 错误响应示例: 如果在关联过程中返回 401 未经授权错误或任何其他失败的错误响应,该错误将无法恢复,检索到的令牌将被舍弃,并且用户必须重新开始关联流程。HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
如果访问令牌有效,则返回 HTTPS 正文中包含以下 JSON 对象的 HTTP 200 响应 回答:
如果您的 userinfo 端点返回 HTTP 200 成功响应,则系统会针对用户的 Google 账号注册检索到的令牌和声明。{ "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.
- اختَر الحساب الذي تريد ربطه.
- أدخِل رقم تعريف الخدمة.
- يمكنك اختياريًا إدخال نطاق واحد أو أكثر لطلب الوصول إليه.
- انقر على بدء العرض التجريبي.
- أكِّد أنّه يمكنك الموافقة على طلب ربط الحساب ورفضه عندما يُطلب منك ذلك.
- تأكَّد من إعادة توجيهك إلى منصّتك.