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

بروتوكول OAuth 2.0 للتطبيقات المتوافقة مع الكمبيوتر المكتبي

يوضّح هذا المستند كيفية استخدام تطبيقات الكمبيوتر المكتبي (مثل التطبيقات التي تعمل على نظام التشغيل Windows أو macOS أو Linux أو أدوات واجهة سطر الأوامر (CLI)) لنقاط نهاية OAuth 2.0 من Google لمنح الإذن بالوصول إلى Google APIs.

يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محدَّدة مع أحد التطبيقات والحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن لأحد التطبيقات استخدام OAuth 2.0 للحصول على إذن من المستخدمين لتخزين الملفات في Google Drive.

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

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

المكتبات والنماذج

ننصحك باستخدام مكتبات عملاء Google API للغة البرمجة التي تستخدمها (مثل Python وJava وNode.js وGo و‎.NET) عند تنفيذ OAuth 2.0 لتطبيقات الكمبيوتر المكتبي. تتولى مكتبات العملاء إدارة تفويض المستخدمين والرموز المميّزة، ما يجعل عملية التنفيذ أبسط وأقل عرضة للأخطاء مقارنةً باستخدام نقاط نهاية HTTP/REST ذات المستوى الأدنى مباشرةً.

بالنسبة إلى التطبيقات المتوافقة مع الأجهزة الجوّالة، اطّلِع على دليلَي التفويض لنظامَي التشغيل Android وiOS.

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

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

يجب أن يفعّل أي تطبيق يطلب بيانات من Google APIs واجهات برمجة التطبيقات هذه في "وحدة تحكّم واجهة برمجة التطبيقات".

لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:

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

إنشاء بيانات اعتماد التفويض

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

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

يتم إنشاء معرّف العميل وسر العميل وعرضهما في وحدة تحكّم Google Cloud. التطبيقات المتوافقة مع الكمبيوتر المكتبي هي برامج عملاء عامة ولا يمكنها الحفاظ على سرية المعلومات السرية. استخدِم دائمًا مفتاح الحماية لتبادل الرموز (PKCE) عند طلب رموز التفويض.

تحديد نطاقات الوصول

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

قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.

يحتوي مستند نطاقات OAuth 2.0 API على قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs.

الحصول على رموز الدخول عبر OAuth 2.0

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

الخطوة 1: إنشاء أداة التحقّق من الرمز والتحدي

تتيح Google استخدام بروتوكول Proof Key for Code Exchange (PKCE) لجعل مسار التطبيق المثبّت أكثر أمانًا. يتم إنشاء أداة تحقّق فريدة من الرمز لكل طلب تفويض، ويتم إرسال قيمتها المحوَّلة، والتي تُسمى "code_challenge"، إلى خادم التفويض للحصول على رمز التفويض.

إنشاء أداة التحقّق من الرمز

‫code_verifier هي سلسلة عشوائية مشفّرة ذات عشوائية عالية تستخدم الأحرف غير المحجوزة [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"، بحد أدنى للطول يبلغ 43 حرفًا وحد أقصى للطول يبلغ 128 حرفًا.

يجب أن يحتوي أداة التحقّق من الرمز على إنتروبيا كافية لجعل تخمين القيمة غير عملي.

إنشاء رمز التحقّق

تتوفّر طريقتان لإنشاء تحدّي الرمز.

طرق إنشاء تحدّي الرمز
S256 (يُنصح به)	رمز التحدي هو تجزئة SHA256 بترميز Base64URL (بدون إضافة) لرمز التحقّق. `code_challenge` = BASE64URL-ENCODE(SHA256(ASCII(`code_verifier`)))
plain	تحدّي الرمز هو القيمة نفسها التي تم إنشاؤها أعلاه لرمز التحقّق. `code_challenge` = `code_verifier`

الخطوة 2: إرسال طلب إلى خادم OAuth 2.0 من Google

للحصول على تفويض المستخدم، أرسِل طلبًا إلى خادم التفويض في Google على العنوان https://accounts.google.com/o/oauth2/v2/auth. تعالج نقطة النهاية هذه عملية البحث عن الجلسة النشطة، وتصادق المستخدم، وتحصل على موافقته. لا يمكن الوصول إلى نقطة النهاية إلا عبر طبقة المقابس الآمنة (SSL)، وهي ترفض اتصالات HTTP (غير المتوافقة مع طبقة المقابس الآمنة).

يتيح خادم التفويض مَعلمات سلسلة طلب البحث التالية للتطبيقات المثبّتة:

المعلمات

client_id

مطلوب

معرّف العميل لتطبيقك يمكنك العثور على هذه القيمة في صفحة "العملاء" في Cloud Console.

redirect_uri

مطلوب

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

يجب أن تتطابق القيمة تمامًا مع أحد عناوين URI لإعادة التوجيه المصرّح بها لعميل OAuth 2.0، والتي تم ضبطها في صفحة "العملاء" في Cloud Console الخاصة بالعميل. إذا لم تتطابق هذه القيمة مع معرّف موارد منتظم (URI) معتمَد، سيظهر لك الخطأ redirect_uri_mismatch.

يعرض الجدول قيمة المَعلمة redirect_uri المناسبة لكل طريقة:

قيم redirect_uri

مخطّط URI مخصّص

com.example.app:redirect_uri_path

أو

com.googleusercontent.apps.123:redirect_uri_path

‫com.example.app هو تدوين نظام أسماء النطاقات العكسي لنطاق تتحكّم فيه. يجب أن يحتوي المخطط المخصّص على نقطة ليكون صالحًا.
‫com.googleusercontent.apps.123 هو تدوين نظام أسماء النطاقات العكسي لمعرِّف العميل.
‫redirect_uri_path هو مكوّن مسار اختياري، مثل /oauth2redirect. يُرجى العِلم أنّ المسار يجب أن يبدأ بشرطة مائلة واحدة، وهو ما يختلف عن عناوين URL العادية التي تستخدم HTTP.

عنوان IP للاسترجاع

‫http://127.0.0.1:port أو http://[::1]:port

أرسِل طلبًا إلى نظامك الأساسي للحصول على عنوان IP ذي الصلة بالاسترجاع وابدأ مستمع HTTP على منفذ متاح عشوائي. استبدِل port برقم المنفذ الفعلي الذي يستمع إليه تطبيقك.

يُرجى العِلم أنّ خيار إعادة التوجيه إلى عنوان IP للاسترجاع على التطبيقات المتوافقة مع الأجهزة الجوّالة متوقّف نهائيًا.

response_type

مطلوب

يحدّد هذا الإعداد ما إذا كانت نقطة نهاية Google OAuth 2.0 ستعرض رمز تفويض أم لا.

اضبط قيمة المَعلمة على code للتطبيقات المثبّتة.

scope

مطلوب

قائمة مفصولة بمسافات للنطاقات التي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. تُعلم هذه القيم شاشة طلب الموافقة التي تعرضها Google للمستخدم.

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

code_challenge

مقترَح

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

code_challenge_method

مقترَح

تحدّد هذه المَعلمة الطريقة التي تم استخدامها لترميز code_verifier سيتم استخدامه أثناء تبادل رمز التفويض. يجب استخدام هذه المَعلمة مع المَعلمة code_challenge. يتم ضبط قيمة code_challenge_method تلقائيًا على plain إذا لم تكن متوفّرة في الطلب الذي يتضمّن code_challenge. القيمتان الوحيدتان المسموح بإدراجهما لهذه المَعلمة هما S256 أو plain.

state

مقترَح

تحدّد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض. يعرض الخادم القيمة الدقيقة التي ترسلها كزوج name=value في جزء من عنوان URL (#) لـ redirect_uri بعد موافقة المستخدم على طلب وصول تطبيقك أو رفضه.

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

ملاحظة مهمة: يجب أن يمنع عميل OAuth هجمات CSRF كما هو موضّح في مواصفات OAuth2 . ويمكنك تحقيق ذلك من خلال استخدام المَعلمة state للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.

login_hint

اختياريّ

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

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

ملاحظة: لا تتوفّر ميزة التفويض المتزايد مع التطبيقات المثبّتة لأنّ العميل لا يمكنه الحفاظ على سرية client_secret.

أمثلة على عناوين URL للتفويض

تعرض علامات التبويب أدناه نماذج عناوين URL للمصادقة لخيارات عناوين URI المختلفة لإعادة التوجيه.

عنوانا URL متطابقان باستثناء قيمة المَعلمة redirect_uri. تحتوي عناوين URL أيضًا على المَعلمتَين المطلوبتَين response_type وclient_id بالإضافة إلى المَعلمة الاختيارية state. يحتوي كل عنوان URL على فواصل أسطر ومسافات لسهولة القراءة.

مخطّط URI مخصّص

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

عنوان IP للاسترجاع

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

الخطوة 3: تطلب Google من المستخدم الموافقة

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

لا يحتاج تطبيقك إلى تنفيذ أي إجراء في هذه المرحلة أثناء انتظار الردّ من خادم OAuth 2.0 في Google للإشارة إلى ما إذا تم منح أي إذن بالوصول. يتم شرح هذا الرد في الخطوة التالية.

الأخطاء

قد تؤدي الطلبات الموجّهة إلى نقطة نهاية تفويض OAuth 2.0 من Google إلى عرض رسائل خطأ موجّهة للمستخدمين بدلاً من مسارات المصادقة والتفويض المتوقّعة. في ما يلي رموز الخطأ الشائعة والحلول المقترَحة:

`admin_policy_enforced`

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

`disallowed_useragent`

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

قد يواجه مطوّرو تطبيقات iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في WKWebView. على المطوّرين استخدام مكتبات iOS بدلاً من ذلك، مثل تسجيل الدخول باستخدام حساب Google لنظام التشغيل iOS أو AppAuth لنظام التشغيل iOS من مؤسسة OpenID.

قد يواجه مطوّرو تطبيقات الويب هذا الخطأ عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالجات الروابط العامة أو تطبيق المتصفّح التلقائي. وتُعدّ مكتبة SFSafariViewController أيضًا خيارًا متاحًا.

`org_internal`

معرّف عميل OAuth في الطلب هو جزء من مشروع يقيّد الوصول إلى حسابات Google في مؤسسة Google Cloud معيّنة. لمزيد من المعلومات حول خيار الضبط هذا، يُرجى الاطّلاع على قسم نوع المستخدم في مقالة المساعدة "إعداد شاشة طلب الموافقة عبر OAuth".

`deleted_client`

تم حذف عميل OAuth المستخدَم لإرسال الطلب. يمكن أن تتم عملية الحذف يدويًا أو تلقائيًا في حال عدم استخدام العملاء. يمكن استعادة العملاء المحذوفين خلال 30 يومًا من الحذف. مزيد من المعلومات

`invalid_grant`

إذا كنت تستخدم أداة التحقّق من الرمز والتحدي، تكون المَعلمة code_challenge غير صالحة أو غير متوفّرة. تأكَّد من ضبط المَعلمة code_challenge بشكل صحيح.

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

`redirect_uri_mismatch`

لا يتطابق معرّف الموارد المنتظم (URI) لإعادة التوجيه redirect_uri الذي تم تمريره في طلب التفويض مع معرّف الموارد المنتظم (URI) المعتمَد لإعادة التوجيه لمعرّف عميل OAuth. راجِع معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في صفحة "العملاء" ضمن Google Cloud Console.

قد تكون قيمة redirect_uri التي تم تمريرها غير صالحة لنوع العميل.

قد تشير المَعلمة redirect_uri إلى عملية OAuth خارج النطاق (OOB) التي تم إيقافها نهائيًا ولم تعُد متاحة. يُرجى الرجوع إلى دليل نقل البيانات لتعديل عملية الدمج.

`invalid_request`

حدث خطأ في الطلب الذي قدّمته. قد يرجع ذلك إلى عدد من الأسباب:

لم يتم تنسيق الطلب بشكل صحيح
لم يتضمّن الطلب المَعلمات المطلوبة
يستخدم الطلب طريقة مصادقة لا تتيحها Google. التأكّد من أنّ عملية دمج OAuth تستخدم طريقة دمج مقترَحة
تم استخدام مخطّط مخصّص غير متوافق مع معرّف الموارد المنتظم (URI) لإعادة التوجيه. إذا ظهرت لك رسالة الخطأ مخطّط URI المخصّص غير متوافق مع تطبيقات Android أو Chrome، يمكنك التعرّف على مزيد من المعلومات حول بدائل مخطّط URI المخصّص.

الخطوة 4: معالجة استجابة خادم OAuth 2.0

تعتمد الطريقة التي يتلقّى بها تطبيقك ردّ التفويض على مخطّط معرّف الموارد المنتظم (URI) لإعادة التوجيه الذي يستخدمه. بغض النظر عن المخطط، سيحتوي الردّ إما على رمز تفويض (code) أو خطأ (error). على سبيل المثال، يشير error=access_denied إلى أنّ المستخدم رفض الطلب.

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

الخطوة 5: استبدال رمز التفويض برمزَي إعادة التحميل والدخول

لتبديل رمز التفويض برمز وصول، يمكنك استدعاء نقطة النهاية https://oauth2.googleapis.com/token وضبط المَعلمات التالية:

الحقول
`client_id`	معرِّف العميل الذي تم الحصول عليه من صفحة "العملاء" في Cloud Console
`client_secret`	اختياريّ سر العميل الذي تم الحصول عليه من صفحة "العملاء" في Cloud Console
`code`	رمز التفويض الذي تم إرجاعه من الطلب الأولي
`code_verifier`	أداة التحقّق من الرمز التي أنشأتها في الخطوة 1.
`grant_type`	وفقًا لمواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على `authorization_code`.
`redirect_uri`	أحد معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المدرَجة لمشروعك في صفحة "العملاء" في Cloud Console لـ `client_id` المحدّد.

على الرغم من أنّ استخدام DPoP اختياري، يُنصح به لزيادة مستوى الأمان. يعتمد أمان DPoP على حصر المفتاح الخاص بجهاز واحد، لذا ننصح بتخزينه بطريقة لا يمكن من خلالها نسخه خارج الجهاز، على سبيل المثال باستخدام وحدات النظام الأساسي الموثوقة (TPM) أو الجيوب الآمنة أو غيرها من مخازن المفاتيح المستنِدة إلى الأجهزة. لاستخدام DPoP، يجب أن ينشئ تطبيقك رمز JWT جديدًا وفريدًا لإثبات DPoP لكل طلب إلى نقطة نهاية الرمز المميّز وإضافته كعنوان طلب HTTP.

العنوان	مطلوب	الوصف
`DPoP`	اختياري	إثبات DPoP هو رمز JWT يثبت حيازة مفتاح خاص. هذا عنوان وليس مَعلمة. وفي حال توفيره، يتم ربط الرموز المميّزة التي تم عرضها بهذا المفتاح. يجب إنشاء إثبات جديد وفريد لكل طلب، ويجب أن يتضمّن المطالبتَين `htm` (طريقة HTTP) و`htu` (معرّف الموارد المنتظم لبروتوكول HTTP) اللتين تتطابقان مع الطلب.

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

إنشاء إثبات DPoP

توضّح الخطوات التالية كيفية إنشاء إثبات DPoP باستخدام OpenSSL من سطر الأوامر:

أنشئ مفتاحَي تشفير EC P-256:

openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

أنشئ عنوان DPoP:
يجب أن يتضمّن العنوان المطالبات typ وalg وjwk (المفتاح العام). تمثّل القيمتان x وy الإحداثيات المرمّزة باستخدام Base64Url لمفتاح EC العام. ترميز Base64Url لملف JSON هذا:
```
{
  "typ":"dpop+jwt",
  "alg":"ES256",
  "jwk": {
    "kty":"EC",
    "x":"YOUR_PUBLIC_KEY_X",
    "y":"YOUR_PUBLIC_KEY_Y",
    "crv":"P-256"
  }
}
```
إنشاء حمولة DPoP:
يجب أن تتضمّن الحمولة jti (معرّف فريد للطلب) وhtm (طريقة HTTP، مثل POST) وhtu (معرّف الموارد المنتظم (URI) لبروتوكول HTTP، مثل https://oauth2.googleapis.com/token) وiat (وقت الإصدار). إذا تلقّيت رقمًا خاصًا من الخادم في رأس DPoP-Nonce في الردّ على طلب سابق، يجب تضمين قيمة الرقم الخاص في مطالبة nonce. تكون مطالبة nonce اختيارية لعمليات تبادل رموز التفويض، ولا يتم استخدامها إلا عند تلقّي عنوان DPoP-Nonce سابقًا. ترميز Base64Url لملف JSON هذا:
```
{
  "jti":"JTI_VALUE",
  "htm":"POST",
  "htu":"https://oauth2.googleapis.com/token",
  "iat":YOUR_JWT_ISSUED_TIME,
  "nonce":"SERVER_PROVIDED_NONCE"
}
```
تعتمد قيمة jti على نوع التبادل:
- بالنسبة إلى عمليات تبادل رموز التفويض، يجب أن تكون قيمة jti هي قيمة تجزئة SHA256 لرمز التفويض بترميز Base64Url: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
- English: بالنسبة إلى عمليات تبادل الرموز المميزة لإعادة التحميل، يجب أن يكون jti معرّفًا فريدًا لكل طلب: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
التوقيع على الإثبات:
ادمج العنوان المرمَّز والحمولة مع نقطة (.)، ثم وقِّع النتيجة باستخدام مفتاحك الخاص من خلال خوارزمية ES256. يُرجى العِلم أنّ JWS يتطلّب أن يكون التوقيع بتنسيق R | S أولي مدمج (64 بايت لـ P-256). في حال استخدام OpenSSL مباشرةً، يجب تحويل التوقيع التلقائي المرمَّز بتنسيق ASN.1 DER إلى هذا التنسيق الأولي.

تتم الإشارة إلى عملية التبادل الناجحة من خلال استجابة 200 OK تحتوي على الرموز المميّزة. إذا تم استخدام إثبات DPoP صالح أثناء عملية التبادل، سيكون الرمز المميز لإعادة التحميل الذي تعرضه Google مرتبطًا بمفتاحك من خلال DPoP، ولكن لن تكون رموز الوصول مرتبطة من خلال DPoP. ستحتفظ رموز الدخول بـ token_type Bearer بدلاً من DPoP. بالإضافة إلى ذلك، يعرض Google عنوان HTTP يتضمّن DPoP-Nonce في الاستجابة. يجب أن يخزّن برنامجك هذا الرقم الخاص في ذاكرة التخزين المؤقت وأن يضمّنه في مطالبة nonce لإثبات DPoP في الطلبات اللاحقة (مثل عند استبدال الرمز المميز لإعادة التحميل برمز الدخول جديد، أو عند طلب واجهات برمجة تطبيقات محمية باستخدام DPoP). باستخدام هذا الرقم الخاص الصادر مبكرًا، يمكنك تجنُّب حدوث خطأ إضافي في عملية الذهاب والعودة (use_dpop_nonce) في طلبك التالي.

يجب تضمين إثباتات DPoP في طلبات تبادل الرموز المميزة التي يتم إجراؤها باستخدام الرموز المميزة لإعادة التحميل المرتبطة بـ DPoP.

يحدث فشل في عملية التبادل إذا لم يتوفّر عنوان DPoP عندما يكون متوقّعًا أو إذا كان غير صالح أو إذا كان الإثبات يستخدم مفتاحًا مختلفًا عن المفتاح المرتبط بالرمز المميّز. وفي هذه الحالات، يعرض الخادم الخطأ 400 Bad Request. إذا كان إثبات DPoP يتضمّن مطالبات htm أو htu غير متطابقة أو iat منتهي الصلاحية أو jti مُعاد استخدامه أو توقيعًا غير صالح، ستعرض Google رمز الخطأ invalid_dpop_proof. إذا كان رمز nonce لبروتوكول DPoP مطلوبًا، مثلاً أثناء تبادل الرمز المميز لإعادة التحميل، وكان إثبات DPoP يفتقد إلى مطالبة nonce، أو كانت قيمة رمز nonce غير مقبولة للخادم (على سبيل المثال، انتهت صلاحيتها أو سبق استخدامها أو غير صحيحة)، تعرض Google رمز الخطأ use_dpop_nonce مع عنوان HTTP DPoP-Nonce يحتوي على رمز nonce جديد يمكنك استخدامه في طلب لاحق. قد تؤدي حالات الفشل الأخرى إلى عرض invalid_grant.

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

يحتوي الردّ على الحقول التالية:

الحقول
`access_token`	الرمز المميّز الذي يرسله تطبيقك للسماح بطلب بيانات من واجهة برمجة تطبيقات Google.
`expires_in`	المدة المتبقية لرمز الدخول بالثواني
`id_token`	ملاحظة: لا يتم عرض هذه السمة إلا إذا كان طلبك يتضمّن نطاق هوية، مثل `openid` أو `profile` أو `email`. القيمة هي رمز ويب مميّز بتنسيق JSON‏ (JWT) يحتوي على معلومات هوية موقَّعة رقميًا عن المستخدم.
`refresh_token`	رمز مميّز يمكنك استخدامه للحصول على رمز دخول جديد. تظل الرموز المميزة لإعادة التحميل صالحة إلى أن يلغي المستخدم إذن الوصول أو تنتهي صلاحية الرمز المميز لإعادة التحميل. في حال استخدام DPoP، يتم ربط الرمز المميز لإعادة التحميل بالمفتاح الخاص المستخدَم لتوقيع إثبات DPoP. يُرجى العِلم أنّه يتم دائمًا عرض الرموز المميزة لإعادة التحميل للتطبيقات المثبَّتة.
`refresh_token_expires_in`	المدة المتبقية لصلاحية الرمز المميز لإعادة التحميل بالثواني لا يتم ضبط هذه القيمة إلا عندما يمنح المستخدم إذن الوصول المستنِد إلى الوقت.
`scope`	نطاقات الوصول التي يمنحها `access_token`، ويتم التعبير عنها كقائمة من السلاسل النصية التي تفصل بينها مسافات وتكون حساسة لحالة الأحرف.
`token_type`	نوع الرمز المميّز الذي تم عرضه تكون هذه القيمة دائمًا `Bearer`، حتى عند استخدام DPoP.

يعرض المقتطف التالي نموذجًا لعناوين الاستجابة ونصها عند نجاح استخدام DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

ملاحظة: إذا كان تطبيقك يتضمّن رمزًا مميزًا لإعادة التحميل للمستخدم وأردت الحصول على رمز مميز جديد لإعادة التحميل مرتبط ببروتوكول DPoP، على المستخدم إبطال الإذن الحالي أو عليك استخدام المَعلمة prompt=consent في طلب التفويض الأولي لضمان إصدار رمز مميز جديد لإعادة التحميل.

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

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

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

لمزيد من المعلومات التفصيلية، يُرجى الاطّلاع على كيفية التعامل مع الأذونات الدقيقة.

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

استدعاء Google APIs

بعد حصول تطبيقك على رمز مميّز للوصول، يمكنك استخدام الرمز لإجراء طلبات إلى واجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاقات الوصول التي تتطلّبها واجهة برمجة التطبيقات. لإجراء ذلك، يجب تضمين رمز الدخول في طلب موجّه إلى واجهة برمجة التطبيقات من خلال تضمين إما معلَمة طلب البحث access_token أو قيمة عنوان HTTP Authorization Bearer. وعند الإمكان، يُفضَّل استخدام عنوان HTTP، لأنّ سلاسل طلبات البحث تميل إلى أن تكون مرئية في سجلّات الخادم. في معظم الحالات، يمكنك استخدام مكتبة برامج لإعداد طلباتك إلى Google APIs (على سبيل المثال، عند طلب Drive Files API).

يمكنك تجربة جميع واجهات Google APIs والاطّلاع على نطاقاتها في مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد يبدو طلب البيانات من نقطة النهاية drive.files (واجهة Drive Files API) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. يُرجى العِلم أنّه عليك تحديد رمز الدخول الخاص بك:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

في ما يلي طلب إلى واجهة برمجة التطبيقات نفسها للمستخدم الذي تمت مصادقته باستخدام مَعلمة سلسلة طلب البحث access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

أمثلة على `curl`

يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl. في ما يلي مثال يستخدم خيار عنوان HTTP (الخيار المفضّل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

أو يمكنك بدلاً من ذلك استخدام خيار مَعلمة سلسلة طلب البحث:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

إعادة تحميل رمز الدخول

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

لتحديث رمز الدخول، يرسل تطبيقك طلب HTTPS POST إلى خادم التفويض في Google (https://oauth2.googleapis.com/token) يتضمّن المَعلمات التالية في نص الطلب:

الاسم	القيمة
`client_id`	معرِّف العميل الذي تم الحصول عليه من وحدة تحكّم واجهة برمجة التطبيقات
`client_secret`	اختياريّ سر العميل الذي تم الحصول عليه من وحدة تحكّم واجهة برمجة التطبيقات (لا ينطبق `client_secret` على الطلبات الواردة من العملاء المسجَّلين كتطبيقات Android أو iOS أو Chrome).
`grant_type`	كما هو موضّح في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على `refresh_token`.
`refresh_token`	الرمز المميز لإعادة التحميل الذي تم إرجاعه من عملية تبادل رمز التفويض

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

العنوان	مطلوب	الوصف
`DPoP`	اختياري	إثبات DPoP هو رمز JWT يثبت حيازة مفتاح خاص. هذا عنوان وليس مَعلمة. وفي حال توفيره، يتم ربط الرموز المميّزة التي تم عرضها بهذا المفتاح. يجب إنشاء إثبات جديد وفريد لكل طلب، ويجب أن يتضمّن المطالبتَين `htm` (طريقة HTTP) و`htu` (معرّف الموارد المنتظم لبروتوكول HTTP) اللتين تتطابقان مع الطلب.

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: DPOP_PROOF_JWT

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

لاستخدام DPoP مع رمز مميّز لإعادة التحميل، يجب إنشاء رمز JWT جديد وفريد لإثبات DPoP للطلب. يمكنك الاطّلاع على إنشاء إثبات DPoP للحصول على تعليمات مفصّلة حول إنشاء مفتاحَي التشفير وإنشاء رمز JWT.

تتم الإشارة إلى عملية التبادل الناجحة من خلال استجابة 200 OK تحتوي على رمز دخول جديد. عند استخدام DPoP، يكون token_type هو Bearer. ويؤكّد الردّ الناجح قبول إثبات DPoP للرمز المميّز لإعادة التحميل. قد تعرض Google أيضًا عنوان HTTP جديدًا باسم DPoP-Nonce في الاستجابة. في حال عرضه، يجب أن يخزّن العميل هذا الرقم الخاص في ذاكرة التخزين المؤقت وأن يضمّنه في مطالبة nonce لإثبات DPoP في الطلبات اللاحقة.

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

يعرض المقتطف التالي نموذجًا لعناوين الاستجابة ونصها عند نجاح استخدام DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

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

إبطال الرمز المميّز

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

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

لإبطال رمز مميّز آليًا، يرسل تطبيقك طلبًا إلى https://oauth2.googleapis.com/revoke ويتضمّن الرمز المميّز كمَعلمة:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

يمكن أن يكون الرمز المميز رمز دخول أو رمزًا مميزًا لإعادة التحميل. إذا كان الرمز المميز هو رمز دخول وكان لديه رمز مميز لإعادة التحميل، سيتم أيضًا إبطال الرمز المميز لإعادة التحميل.

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة HTTP للاستجابة هو 200. في حالات الخطأ، يتم عرض رمز حالة HTTP ‏400 مع رمز الخطأ.

طُرق إعادة التوجيه إلى التطبيق

مخطّط URI مخصّص

مخطّطات معرّفات الموارد المنتظمة (URI) المخصّصة هي شكل من أشكال الربط بصفحة معيّنة، وتستخدم مخطّط URI مخصّصًا لفتح تطبيقك.

بديل لاستخدام مخطّطات URI المخصّصة في تطبيقات Chrome

استخدِم Chrome Identity API التي تقدّم استجابة OAuth 2.0 مباشرةً إلى تطبيقك، ما يلغي الحاجة إلى معرّف موارد منتظم (URI) لإعادة التوجيه.

عنوان IP للاسترجاع (على أجهزة الكمبيوتر المكتبي التي تعمل بنظام التشغيل macOS أو Linux أو Windows)

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

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

الاستخدام المقترَح	تطبيقات macOS وLinux وWindows المتوافقة مع الكمبيوتر المكتبي
قيم النماذج	اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.

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

النسخ واللصق اليدوي (متوقّف نهائيًا)

حماية تطبيقاتك

إثبات ملكية التطبيق في Chrome

يمكنك إثبات ملكية تطبيقك للحدّ من خطر انتحال هويته.

لإكمال عملية التحقّق، عليك استخدام حساب المطوّر على "سوق Chrome الإلكتروني". يجب استيفاء المتطلبات التالية لإكمال عملية التحقّق بنجاح:

يجب أن يكون لديك سلعة مسجَّلة في لوحة بيانات المطوِّر في سوق Chrome الإلكتروني تحمل معرّف السلعة نفسه الخاص بعميل OAuth لإضافة Chrome الذي تُكمل عملية إثبات الهوية له.
يجب أن تكون ناشرًا للعنصر في "سوق Chrome الإلكتروني". مزيد من المعلومات حول إدارة إمكانية الوصول في "لوحة بيانات المطوِّر في سوق Chrome الإلكتروني"

في قسم إثبات ملكية التطبيق في برنامج إضافة Chrome، انقر على الزر إثبات الملكية لإكمال عملية إثبات الملكية.

ملاحظة: يُرجى الانتظار بضع دقائق قبل إكمال عملية التحقّق من المعلنين بعد منح إذن الوصول إلى حسابك.

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

لحلّ مشكلة تعذُّر إثبات الهوية، جرِّب ما يلي:

تأكَّد من وجود منتج مسجَّل في لوحة بيانات المطوّر في "سوق Chrome الإلكتروني" يحمل رقم تعريف المنتج نفسه لعميل OAuth لإضافة Chrome الذي تُكمل عملية إثبات هويته.
تأكَّد من أنّك ناشر للتطبيق، أي أنّك إما الناشر الفردي للتطبيق أو عضو في مجموعة الناشرين للتطبيق. مزيد من المعلومات حول إدارة إمكانية الوصول في لوحة بيانات المطوِّر في سوق Chrome الإلكتروني.
إذا عدّلت للتو قائمة الناشرين في المجموعة، تأكَّد من مزامنة قائمة أعضاء الناشرين في المجموعة في "لوحة بيانات المطوِّر في سوق Chrome الإلكتروني". مزيد من المعلومات حول مزامنة قائمة المشتركين الداعمين للناشر

الوصول المستند إلى الوقت

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

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

قراءات إضافية

يحدّد معيار "أفضل الممارسات الحالية" (BCP) الصادر عن "مجموعة مهندسي الإنترنت" (IETF) بشأن بروتوكول OAuth 2.0 للتطبيقات الأصلية العديد من أفضل الممارسات الموضّحة هنا.

تنفيذ ميزة "الحماية العابرة للحساب"

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

في ما يلي بعض الأمثلة على أنواع الأحداث التي ترسلها خدمة "الحماية العابرة للحساب" من Google إلى تطبيقك:

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

يمكنك الاطّلاع على صفحة حماية حسابات المستخدمين من خلال ميزة "الحماية العابرة للحساب" لمزيد من المعلومات حول كيفية تنفيذ ميزة "الحماية العابرة للحساب" وللحصول على القائمة الكاملة للأحداث المتاحة.

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

المكتبات والنماذج

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

إنشاء بيانات اعتماد التفويض

تحديد نطاقات الوصول

الحصول على رموز الدخول عبر OAuth 2.0

الخطوة 1: إنشاء أداة التحقّق من الرمز والتحدي

إنشاء أداة التحقّق من الرمز

إنشاء رمز التحقّق

الخطوة 2: إرسال طلب إلى خادم OAuth 2.0 من Google

أمثلة على عناوين URL للتفويض

مخطّط URI مخصّص

عنوان IP للاسترجاع

الخطوة 3: تطلب Google من المستخدم الموافقة

الأخطاء

admin_policy_enforced

disallowed_useragent

org_internal

deleted_client

invalid_grant

redirect_uri_mismatch

invalid_request

الخطوة 4: معالجة استجابة خادم OAuth 2.0

الخطوة 5: استبدال رمز التفويض برمزَي إعادة التحميل والدخول

إنشاء إثبات DPoP

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

استدعاء Google APIs

أمثلة على طلبات HTTP GET

أمثلة على curl

إعادة تحميل رمز الدخول

إبطال الرمز المميّز

طُرق إعادة التوجيه إلى التطبيق

مخطّط URI مخصّص

بديل لاستخدام مخطّطات URI المخصّصة في تطبيقات Chrome

عنوان IP للاسترجاع (على أجهزة الكمبيوتر المكتبي التي تعمل بنظام التشغيل macOS أو Linux أو Windows)

النسخ واللصق اليدوي (متوقّف نهائيًا)

حماية تطبيقاتك

إثبات ملكية التطبيق في Chrome

الوصول المستند إلى الوقت

قراءات إضافية

تنفيذ ميزة "الحماية العابرة للحساب"

بروتوكول OAuth 2.0 للتطبيقات المتوافقة مع الكمبيوتر المكتبي

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`deleted_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

أمثلة على `curl`