ربط حساب Google باستخدام OAuth (Implicit Flow - مؤرشف)

خطر: عملية التدفق الضمني غير متاحة لبروتوكول سياق النموذج (MCP) وبروتوكول إدارة المستخدمين (UCP) وعمليات التدفق التي تتم بإشراف وكيل. ولا يُنصح عمومًا باستخدامها في عمليات الدمج الجديدة بسبب اعتبارات الأمان. استخدِم مسار رمز التفويض بدلاً من ذلك.

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

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

ربط حساب Google: مسار OAuth الضمني

يوضّح مخطط التسلسل التالي تفاعلات بين المستخدم وGoogle ونقاط نهاية خدمتك.

الشكل 1. تسلسل الأحداث في مسار OAuth 2.0 الضمني لربط الحساب على Google

الأدوار والمسؤوليات

يحدّد الجدول التالي أدوار ومسؤوليات الجهات الفاعلة في عملية الربط بحساب Google باستخدام بروتوكول OAuth الضمني. يُرجى العِلم أنّه في GAL، تعمل Google كعميل لبروتوكول OAuth، بينما تعمل خدمتك كموفّر هوية/خدمة.

الجهة الفاعلة / المكوّن	دور قائمة العناوين العمومية	المسؤوليات
تطبيق / خادم Google	عميل OAuth	يبدأ عملية الحصول على الرمز المميز للوصول من خلال إعادة التوجيه إلى المتصفّح، ويخزّنه بشكل آمن للوصول إلى واجهات برمجة التطبيقات الخاصة بخدمتك.
نقطة نهاية التفويض	خادم التفويض	تتم مصادقة المستخدمين والحصول على موافقتهم وإصدار رموز دخول طويلة الأمد مباشرةً إلى Google.
معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه من Google	نقطة نهاية معاودة الاتصال	يتلقّى عملية إعادة توجيه المستخدم من خدمة التفويض مع القيمتَين access_token وstate في جزء عنوان URL.

تتضمّن جلسة نموذجية لمسار OAuth 2.0 التدفّق الضمني التي تبدأها Google الخطوات التالية:

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

وصفة التنفيذ

اتّبِع الخطوات التالية لتنفيذ عملية "التدفق الضمني".

الخطوة 1: التعامل مع طلبات التفويض

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

للتعامل مع الطلب، يُرجى اتّخاذ الإجراءات التالية:

1. التحقّق من صحة الطلب:

   • تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي تمّ تعيينه لـ Google.
   • تأكَّد من أنّ redirect_uri يتطابق مع عنوان URL المتوقّع لإعادة التوجيه من Google: none https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_ID
   • تأكَّد من أنّ قيمة response_type هي token.

2. مصادقة المستخدم:

   • تحقَّق مما إذا كان المستخدم قد سجّل الدخول إلى خدمتك.
   • إذا لم يكن المستخدم مسجّلاً الدخول، اطلب منه إكمال عملية تسجيل الدخول أو الاشتراك.

3. إنشاء رمز دخول:

   • أنشئ رمز دخول فريدًا لا يمكن تخمينه ويكون مرتبطًا بالمستخدم والعميل.

4. إعادة التوجيه إلى Google:

   • أعِد توجيه المتصفّح إلى عنوان URL المقدَّم في redirect_uri.
   • ألحِق المَعلمات التالية بجزء عنوان URL (علامة الهاش):
     • access_token: رمز الدخول الذي أنشأته.
     • ‫token_type: يجب أن تكون القيمة bearer.
     • state: قيمة الحالة غير المعدَّلة التي تم تلقّيها من Google

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:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

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.