دليل استخدام OAuth 2.1

يوضّح هذا الدليل كيفية منح منصة "التطبيقات المرتبطة" الإذن بالوصول إلى خدماتك بشكل آمن. بالنسبة إلى عمليات دمج MCP في التطبيقات المرتبطة، ننصح بشدة باستخدام OAuth 2.1، وهو المعيار المتّبع في المجال للتفويض المفوَّض، مع Proof Key for Code Exchange (PKCE) لضمان أعلى مستوى من الأمان لبيانات المستخدمين والموثوقية في مسارات "الوكيل". تتيح منصة "التطبيقات المرتبطة" نوع إذن الوصول إلى رمز التفويض باستخدام مَعلمات مفتاح Proof Key for Code Exchange‏ (PKCE).

يُعدّ PKCE إلزاميًا لجميع عمليات OAuth 2.1 واختياريًا لعمليات OAuth2.0.

لتفعيل الاكتشاف التلقائي وتبسيط عملية الإعداد، يجب أن يتيح خادم التفويض استخدام إضافة البيانات الوصفية لخادم التفويض، والتي يُشار إليها أيضًا باسم "اكتشاف OAuth".

كيفية جلب Gemini MCP لملف إعدادات JSON

تحاول وحدة تحكّم Gemini MCP جلب ملف JSON الخاص بالإعدادات من عناوين URL التالية، بالترتيب الموضّح في هذا القسم.

إذا كان عنوان URL الخاص بخادم التفويض يقع في المستوى الأعلى من نطاقك (على سبيل المثال، https://auth.example.com)، يضيف Gemini أدلة "معروفة" عادية إلى نطاقك ويبحث عن الخادم بالترتيب التالي:

  1. https://auth.example.com/.well-known/oauth-authorization-server
  2. https://auth.example.com/.well-known/openid-configuration

إذا كان عنوان URL لخادم التفويض يقع ضمن دليل فرعي أو مسار محدّد على نطاقك، مثل https://auth.example.com/realms/master، يضيف Gemini المسارات "المعروفة" نفسها مباشرةً إلى ذلك الدليل الفرعي بالترتيب التالي.

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. ‫.../realms/master/.well-known/openid-configuration (يتيح استخدام المسارات المُدمجة)

إمكانات JSON المطلوبة

يجب أن تتضمّن استجابة البيانات الوصفية الحقول التالية. ستفشل عملية الدمج في حال عدم توفّر الحقول الإلزامية أو عدم العثور على أنواع صالحة.

authorization_endpoint
يجب أن يكون عنوان URL صالحًا.
token_endpoint
يجب أن يكون عنوان URL صالحًا.
response_types_supported
يجب أن يحتوي على السلسلة code.
registration_endpoint

في الوقت الحالي، تعتمد Play Console على Dynamic Client.

(RFC 7591). يجب تقديم نقطة نهاية للتسجيل في البيانات الوصفية، أو إدخال معرّف العميل أو السر مباشرةً في واجهة مستخدم Play Console.

إذا كان خادم التفويض لا يتيح ميزة Dynamic Client Registration (DCR)، عليك تنفيذ حقلي معرِّف العميل وسر العميل يدويًا وملؤهما ضمن واجهة مستخدم Play Console لإكمال عملية الدمج.

إذا كان التنفيذ يتيح استخدام "مفتاح حماية تبادل الرموز" (PKCE) أو الجلسات المستمرة، يجب تضمين حقول الإمكانات ذات الصلة (مثل طرق التحدي وأنواع منح الإذن) في ملف JSON الخاص بالاكتشاف. يساعد ذلك في ضمان التوافق مع معايير الأمان وإمكانية الاتصال في Gemini. إذا كنت تتيح استخدام السمة scope، يجب تضمين الحقل scopes_supported.

مثال على الإعداد

في ما يلي ردّ صالح بتنسيق JSON يستوفي متطلبات العميل.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

في الحالات التي يتم فيها تضمين PKCE، يعرض المقتطف التالي مثالاً لما يمكن تضمينه في مجموعة JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

في الحالات التي يتم فيها تضمين الحقل scopes_supported، يعرض المقتطف التالي مثالاً على ما يمكن تضمينه في مجموعة JSON.

"scopes_supported": ["mcp", "cart.order"],

مسار رمز التفويض (النسخة المبسّطة)

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

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

    يتضمّن هذا الطلب معرِّف العميل (أو يتم إنشاؤه تلقائيًا باستخدام DCR) ومعرِّف الموارد المنتظم (URI) لإعادة التوجيه في Gemini ومَعلمات PKCE المهمة (code_challenge وcode_challenge_method).

    أضِف عناوين URL التالية إلى القائمة المسموح بها لإعداد OAuth:

    • https://oauth-redirect.googleusercontent.com/r/*
    • https://oauth-redirect-sandbox.googleusercontent.com/r/*
    • https://oauth-redirect-test.googleusercontent.com/r/*
    • https://oauth-redirect.googleusercontent.com/a/*
    • https://oauth-redirect-sandbox.googleusercontent.com/a/*
    • https://oauth-redirect-test.googleusercontent.com/a/*

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

  3. منح الرمز: بعد موافقة المستخدم، يعيد الخادم توجيه متصفّح المستخدم إلى RedirectURI في Gemini، مع إلحاق رمز تفويض مؤقت بعنوان URL.

  4. تبادل الرموز المميّزة: يرسل النظام الخلفي لـ Gemini طلب POST إلى نقطة نهاية الرمز المميّز، ويستبدل رمز التفويض برمز وصول مميّز.

  5. منح إذن الوصول: تتحقّق نقطة نهاية الرمز المميّز من الرمز ومَعلمات PKCE، وتُصدر رمز دخول ورمزًا مميزًا لإعادة التحميل (اختياري)، ثم تُرسلهما إلى Gemini.

المتطلبات الأساسية لمفتاح PKCE

يضيف PKCE طبقة أمان لمنع الاعتراض غير المصرّح به لرموز التفويض.

  • ‫code_verifier: سلسلة عشوائية مشفَّرة ينشئها Gemini في بداية العملية ويتم الحفاظ على خصوصية هذه المعلومات.
  • ‫code_challenge: تحويل code_verifier، عادةً ما يكون تجزئة SHA256. يتم إرسال هذا الطلب بشكل علني، كما هو موضّح في الخطوة 1 من مسار رمز التفويض.
  • التحقّق: يجب أن تتحقّق نقطة نهاية الرمز المميّز (الموضّحة في الخطوة 4 من مسار رمز التفويض) من أنّ قيمة code_verifier التي تم تلقّيها تتطابق مع قيمة code_challenge الأصلية عند تحويلها.

تصحيح الأخطاء

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

متطلبات إعدادات ربط حساب Google

يُرجى قراءة إرشادات واجهة برمجة التطبيقات التالية للحصول على معلومات حول إعدادات ربط حساب Google.

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

حقل الإعداد

الوصف

مسؤولية المطوّر

معرّف العميل وسر العميل

بيانات الاعتماد الفريدة التي ينشئها خادم التفويض خصيصًا لمنصة "التطبيقات المرتبطة". "سر العميل" هو بيانات اعتماد خاصة بالأمان (كلمة المرور) المرتبطة بمعرّف العميل.

ملاحظة: إذا أصدر المطوّر معرّف العميل، عليه تقديمه. إذا أصدرت Google معرّف العميل، قد يحتاج المطوّر إلى تسجيل رمز سري أو التحقّق منه.

استخدِم المعرّف الذي توفّره المنصة في جميع طلبات التفويض.

نقطة نهاية التفويض

عنوان URL لإعادة توجيه المستخدمين من أجل المصادقة ومنح الموافقة

استضافة نقطة النهاية، على سبيل المثال، https://yourdomain.com/oauth/authorize

نقطة نهاية الرمز المميّز

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

استضافة نقطة النهاية هذه، على سبيل المثال، https://yourdomain.com/oauth/token

نقطة نهاية الإبطال
اختيارية

عنوان URL لإعلام نظامك بإبطال رمز مميّز عندما يقطع المستخدم الاتصال.

عندما يلغي مستخدم عملية الربط أو يفصل عملية التكامل من داخل منصة "التطبيقات المرتبطة"، سنرسل طلب POST إلى نقطة النهاية ‎/revoke التي تحتوي على رمز الوصول أو الرمز المميز لإعادة التحميل.

يُرجى الاطّلاع على مقالة إلغاء ربط الحسابات لمزيد من المعلومات.

استضافة نقطة النهاية، على سبيل المثال، https://yourdomain.com/oauth/revoke

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

معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه

عنوان URL المحدّد لمعاودة الاتصال الذي توفّره المنصة حيث يرسل خادم التفويض الرمز مرة أخرى بعد الموافقة.

اضبط خادم التفويض لقبول معرّف الموارد المنتظم (URI) الرسمي والمسجَّل لإعادة التوجيه من المنصة فقط.

كيفية إعادة التحميل

‫"/token" مع "grant_type=refresh_token"

هي آلية تتيح لمنصة "التطبيقات المرتبطة" الحصول على رمز وصول جديد عند انتهاء صلاحية الرمز الحالي، ما يحافظ على سلاسة عملية الربط بدون الحاجة إلى تسجيل دخول المستخدم بشكل متكرر.

عند انتهاء صلاحية رمز الدخول الحالي، ستُرسل منصة "التطبيقات المرتبطة" تلقائيًا طلب POST إلى نقطة نهاية /token. ستتضمّن حمولة الطلب grant_type=refresh_token مع الرمز المميّز لإعادة التحميل الذي أصدره خادمك سابقًا.

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

نوع الردّ

يجب ضبط هذه القيمة على CODE لإتاحة مسار رمز التفويض.

النطاقات

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

عليك تقديم قائمة بالنطاقات التلقائية (على سبيل المثال، openid, profile, email) التي يجب أن تطلبها منصة "التطبيقات المرتبطة" عند بدء العملية.

يجب أن تكون النطاقات المطلوبة محدودة قدر الإمكان (مبدأ الحد الأدنى من الامتيازات)، ولكن يجب أن تكون كافية تمامًا لرحلات المستخدم الأساسية (CUJ) التي يتيحها تكامل MCP.

مواد عرض واجهة المستخدم: الشعار

شعار المطوّر الذي سيتم عرضه على شاشات ربط الحساب وشاشة طلب الموافقة

يجب أن يكون الشعار صورة متّجه مربّعة (SVG) بمظهر دائري وبحجم 500 × 500 بكسل على الأقل. على سبيل المثال، يمكنك الاطّلاع على https://[partner-domain]/assets/logo.svg أو ملف SVG الأوّلي.

ربط التطبيقات الأصلية (ربط التطبيقات بسرعة)

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

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة ربط حساب Google باستخدام ميزة "ربط التطبيقات بسرعة" المستندة إلى بروتوكول OAuth.

أكمِل عملية التحقّق من "متجر Google Play" و"متجر التطبيقات"، وأدرِج عناوين URI لإعادة التوجيه من Google مباشرةً في تطبيقاتك الأصلية لضمان التبديل الآمن للمصادقة من تطبيق إلى آخر.

مدة صلاحية الرمز المميّز

(اختياري) مدة صلاحية رمز الوصول قبل أن يتطلب إعادة تحميله. هذه السياسة مفيدة لضبط سياسات المهلة في GAL.

تتراوح أوقات انتهاء الصلاحية الشائعة بين دقائق وساعات وأيام، حسب احتياجات الأمان، على سبيل المثال، 30 days)

الأخطاء الشائعة في عملية الدمج

في ما يلي قائمة بالأخطاء الشائعة والحلول المحتملة التي تنطبق على عملية الدمج.

  • عدم توفّر منح "الرمز": يتحقّق النظام الآلي في منصة Gemini صراحةً من قيمة "الرمز" في response_types_supported.
  • عدم توفّر نقطة نهاية التسجيل: حتى إذا كان خادمك يتيح مستندات البيانات الوصفية لمعرّف العميل، يتطلّب تطبيق Gemini (الذي يعمل كعميل OAuth يتصل بخادمك) حاليًا توفّر نقطة نهاية registration_endpoint مخصّصة في ملف JSON الخاص بالاكتشاف.
  • خطأ غير 200: إذا واجهت آلية الاستكشاف التلقائي للبيانات الوصفية في Gemini عنوان URL المتعارف عليه وتلقّت الخطأ 404 أو 500، لن تحاول تخمين عناوين URL أخرى. يُرجى التأكّد من أنّ عنوان URL لمستند الاستكشاف متاح للجميع.