ربط حساب Google باستخدام OAuth

ويتم ربط الحسابات باستخدام مساري OAuth 2.0 الضمني ورمز التفويض القياسي في المجال. يجب أن تتوافق خدمتك مع نقاط نهاية التفويض والتبادل المميز المتوافقة مع OAuth 2.0.

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

في مسار رمز التفويض، تحتاج إلى نقطتَي نهاية:

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

  • نقطة نهاية تبادل الرموز المميزة المسؤولة عن نوعين من التبادلات:

    1. يعمل هذا الإعداد على استبدال رمز تفويض برمز مميز لإعادة التحميل طويل الأجل ورمز دخول قصير الأجل. ويحدث هذا التبادل عندما يخضع المستخدم لعملية ربط الحساب.
    2. لتبادل رمز إعادة تحميل طويل الأمد لرمز دخول قصير الأجل. وتتم عملية التبادل هذه عندما تحتاج Google إلى رمز دخول جديد لأنّ الرمز الذي انتهت صلاحيته.

اختيار مسار OAuth 2.0

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

إرشادات التصميم

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

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

المتطلبات

  1. عليك إعلام المستخدم بأنّ حساب المستخدم سيتم ربطه بحساب Google، وليس على منتج محدّد من Google، مثل Google Home أو "مساعد Google".

الاقتراحات

ننصحك بتنفيذ الإجراءات التالية:

  1. عرض سياسة خصوصية Google: إدراج رابط يؤدي إلى سياسة خصوصية Google على شاشة طلب الموافقة

  2. البيانات التي ستتم مشاركتها. استخدام لغة واضحة وموجزة لإطلاع المستخدم على البيانات التي طلبها من Google والغرض من ذلك

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

  4. إمكانية الإلغاء. قدِّم للمستخدمين طريقة للرجوع أو الإلغاء في حال اختيار عدم الربط.

  5. محو عملية تسجيل الدخول تأكّد من أن المستخدمين لديهم طريقة واضحة لتسجيل الدخول إلى حساباتهم على Google، مثل حقول اسم المستخدم وكلمة المرور، أو تسجيل الدخول باستخدام حساب Google.

  6. إمكانية إلغاء الربط: قدِّم آلية تتيح للمستخدمين إلغاء الربط، مثل عنوان URL بإعدادات الحساب على النظام الأساسي. بدلاً من ذلك، يمكنك تضمين رابط إلى حساب Google حيث يمكن للمستخدمين إدارة الحساب المرتبط.

  7. إمكانية تغيير حساب المستخدم. اقتراح طريقة تتيح للمستخدمين تبديل حساباتهم ويُعد ذلك مفيدًا على وجه الخصوص إذا كان المستخدمون يميلون إلى امتلاك حسابات متعددة.

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

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

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. انقر فوق إنشاء مشروع .
  3. أدخل اسمًا أو اقبل الاقتراح الذي تم إنشاؤه.
  4. قم بتأكيد أو تحرير أي حقول متبقية.
  5. انقر فوق إنشاء .

لعرض معرف المشروع الخاص بك:

  1. Go to the Google API Console.
  2. ابحث عن مشروعك في الجدول على الصفحة المقصودة. يظهر معرف المشروع في عمود المعرف .

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.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. 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

  4. 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授权端点。此端点负责身份验证并获得用户对数据访问的同意。授权端点向尚未登录的用户显示登录 UI，并记录对请求访问的同意。

当 Google 应用程序需要调用您的服务的授权 API 之一时，Google 会使用此端点来获得您的用户的许可，以代表他们调用这些 API。

一个典型的由 Google 发起的 OAuth 2.0 隐式流会话具有以下流程：

  1. Google 在用户的浏览器中打开您的授权端点。用户登录（如果尚未登录）并授予 Google 使用您的 API 访问其数据的权限（如果他们尚未授予权限）。
  2. 您的服务创建的访问令牌并将其返回给谷歌。为此，请使用附加到请求的访问令牌将用户的浏览器重定向回 Google。
  3. Google 会调用您服务的 API 并在每个请求中附加访问令牌。您的服务会验证访问令牌是否授予 Google 访问 API 的授权，然后完成 API 调用。

处理授权请求

当 Google 应用程序需要通过 OAuth 2.0 隐式流执行帐户链接时，Google 会将用户发送到您的授权端点，并包含以下参数的请求：

授权端点参数
client_id您分配给 Google 的客户端 ID。
redirect_uri您向其发送对此请求的响应的 URL。
state传递回 Google 的簿记值在重定向 URI 中保持不变。
response_type要在响应中返回的值的类型。对于的OAuth 2.0隐式流程中，响应类型总是token 。
user_locale在谷歌帐户语言设置RFC5646格式用于本地化用户的首选语言内容。

例如，如果您的授权端点可在https://myservice.example.com/auth ，请求看起来像下面这样：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

对于处理登录请求的授权端点，请执行以下步骤：

  1. 验证client_id和redirect_uri值，以防止授权访问意外或错误配置的客户端应用程序：

    • 确认该client_id你分配给谷歌的客户ID相匹配。
    • 确认URL指定由redirect_uri参数有以下形式：
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. 检查用户是否已登录您的服务。如果用户未登录，请完成服务的登录或注册流程。

  3. 生成供 Google 用来访问您的 API 的访问令牌。访问令牌可以是任何字符串值，但它必须唯一地代表用户和令牌所针对的客户端，并且不能被猜测。

  4. 发送用户的浏览器重定向到被指定的URL的HTTP响应redirect_uri参数。在 URL 片段中包含以下所有参数：

    • access_token ：刚才生成的令牌，你的访问
    • token_type ：字符串bearer
    • state ：从原始请求的未修改的状态值

    以下是所得的URL的一个示例：

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

谷歌的OAuth 2.0重定向处理接收的令牌的访问并确认state的值并没有改变。在 Google 为您的服务获取访问令牌后，Google 会将令牌附加到对您的服务 API 的后续调用中。

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
    If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

التحقّق من صحة عملية التنفيذ

يمكنك التحقق من صحة التطبيق الخاص بك باستخدام ملعب أوث 2.0 الأداة.

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

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

يمكنك التحقق من صحة التطبيق الخاص بك باستخدام حساب Google ربط تجريبي الأداة.

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

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