Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

بروتوكول OAuth 2.0 للتطبيقات المتوافقة مع أجهزة iOS والكمبيوتر

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

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

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

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

المكتبات والعينات

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

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

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

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

يجب تفعيل أي واجهات برمجة تطبيقات تستدعي Google APIs في API Console.

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

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

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

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

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

iOS

اختَر نوع تطبيق iOS.
أدخِل اسمًا لعميل OAuth. يظهر هذا الاسم في صفحة العملاء الخاصة بمشروعك لتحديد العميل.
أدخِل معرّف الحزمة لتطبيقك، وهو قيمة المفتاح CFBundleIdentifier في ملف الموارد الخاص بقائمة خصائص معلومات تطبيقك (info.plist). يتم عرض القيمة بشكل شائع في اللوحة General أو اللوحة Signing & Capabilities في أداة تعديل مشاريع Xcode. يظهر معرّف الحزمة أيضًا في قسم "المعلومات العامة" ضمن صفحة "معلومات التطبيق" الخاصة بالتطبيق على موقع App Store Connect الإلكتروني من Apple.
تأكَّد من استخدام معرّف الحزمة الصحيح لتطبيقك، لأنّه لن يكون بإمكانك تغييره إذا كنت تستخدم ميزة فحص التطبيقات.
(اختياري)
أدخِل رقم تعريف تطبيقك في App Store إذا كان التطبيق منشورًا في متجر Apple App Store. معرّف المتجر هو سلسلة رقمية مضمّنة في كل عنوان URL في Apple App Store.
1. افتح تطبيق Apple App Store على جهاز iOS أو iPadOS.
2. ابحث عن تطبيقك.
3. انقر على زر المشاركة (مربّع وسهم للأعلى).
4. انقر على نسخ الرابط.
5. الصِق الرابط في محرِّر نصوص. معرّف App Store هو الجزء الأخير من عنوان URL.
  مثلاً: https://apps.apple.com/app/google/id284815942
(اختياري)
أدخِل معرّف الفريق. يمكنك الاطّلاع على العثور على معرّف الفريق في مستندات حساب المطوّرين على Apple للحصول على مزيد من المعلومات.
ملاحظة: يجب ملء حقل "معرّف الفريق" إذا كنت تريد تفعيل App Check للعميل.
(اختياري)
فعِّل خدمة فحص التطبيقات لتطبيق iOS. عند تفعيل خدمة فحص التطبيقات، يتم استخدام خدمة App Attest من Apple للتحقّق من أنّ طلبات OAuth 2.0 الصادرة من عميل OAuth حقيقية وصادرة من تطبيقك. يساعد ذلك في الحدّ من مخاطر انتحال هوية التطبيق. مزيد من المعلومات عن تفعيل خدمة فحص التطبيقات لتطبيق iOS
انقر على إنشاء.

UWP

اختَر نوع التطبيق النظام الأساسي العام لـ Windows.
أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في مشروعك لتحديد العميل.
أدخِل معرّف Microsoft Store الخاص بتطبيقك والمؤلّف من 12 حرفًا. يمكنك العثور على هذه القيمة في Microsoft Partner Center في صفحة هوية التطبيق ضمن قسم "إدارة التطبيقات".
انقر على إنشاء.

بالنسبة إلى تطبيقات UWP، يتم إنشاء معرّف الموارد المنتظم لإعادة التوجيه باستخدام معرّف أمان الحزمة الفريد لتطبيقك (SID). يمكنك العثور على ملف Package SID الخاص بتطبيقك في ملف Package.appxmanifest ضمن مشروعك في Visual Studio.

عند إنشاء معرّف العميل في وحدة تحكّم Google Cloud، يجب تحديد معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه بالتنسيق التالي، باستخدام قيمة معرّف الأمان (SID) لحزمة التطبيق بأحرف صغيرة:

ms-app://YOUR_APP_PACKAGE_SID

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

بالنسبة إلى تطبيقات النظام الأساسي العالمي لـ Windows (UWP)، لا يمكن أن يزيد طول مخطط URI المخصّص عن 39 حرفًا، كما هو موضّح في مستندات Microsoft.

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

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

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

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

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

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

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

تتيح Google بروتوكول مفتاح الحماية لتبادل الرموز (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 (غير SSL).

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

المعلمات

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 للاطّلاع على مثال حول كيفية إنشاء رمز مميّز 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 Foundation.

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

`org_internal`

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

`deleted_client`

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

`invalid_grant`

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

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

`redirect_uri_mismatch`

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

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

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

`invalid_request`

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

لم يتم تنسيق الطلب بشكل صحيح
لم يتضمّن الطلب المَعلمات المطلوبة
يستخدم الطلب طريقة لا تسمح بها Google لمنح إذن الوصول. التأكّد من أنّ عملية دمج OAuth تستخدم طريقة دمج مقترَحة
تم استخدام مخطّط مخصّص غير متوافق لمعرّف الموارد المنتظم لإعادة التوجيه. إذا ظهرت لك رسالة الخطأ مخطّط 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 أو Secure Enclaves أو مخازن مفاتيح أخرى مستنِدة إلى الأجهزة. لاستخدام 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 هما إحداثيات مفتاحك العام لمنحنى القطع الناقص (EC) بترميز Base64Url. استخدِم ترميز 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 (وقت الإصدار). إذا تلقّيت قيمة nonce من الخادم في عنوان DPoP-Nonce ضمن الاستجابة لطلب سابق، عليك تضمين قيمة 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))".
- بالنسبة إلى عمليات استبدال الرموز المميزة لإعادة التحميل، يجب أن يكون 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 في ردّ رمز الدخول. نطاقات الوصول التي يمنحها رمز access_token، ويتم التعبير عنها كقائمة من السلاسل الحساسة لحالة الأحرف والمفصولة بمسافات

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

  {
    "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 أو قيمة Bearer في عنوان HTTP Authorization. عند الإمكان، من الأفضل استخدام عنوان HTTP، لأنّ سلاسل طلبات البحث تكون عادةً مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة برامج العميل لإعداد طلباتك إلى واجهات Google API (على سبيل المثال، عند طلب 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`	معرّف العميل الذي تم الحصول عليه من وحدة تحكّم API
`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 أيضًا عنوان DPoP-Nonce HTTP جديدًا في الردّ. وفي حال عرضه، يجب أن يخزّن العميل هذا الرقم الخاص مؤقتًا وأن يدرجه في مطالبة 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 المخصّصة في تطبيقات Chrome

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

فحص التطبيقات (على أجهزة iOS فقط)

تساعد ميزة فحص التطبيقات في حماية تطبيقات iOS من الاستخدام غير المصرَّح به من خلال استخدام خدمة App Attest من Apple للتحقّق من أنّ الطلبات المُرسَلة إلى نقاط نهاية Google OAuth 2.0 صادرة من تطبيقاتك الأصلية. يساعد ذلك في تقليل مخاطر انتحال هوية التطبيق.

تفعيل فحص التطبيقات على عميل iOS

يجب استيفاء المتطلبات التالية لتفعيل App Check بنجاح على عميل iOS:

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

لتفعيل ميزة "فحص التطبيقات"، فعِّل زر التبديل حماية عميل OAuth من إساءة الاستخدام باستخدام ميزة "فحص التطبيقات من Firebase" في عرض التعديل لعميل iOS.

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

قد تظهر لك أخطاء متعلّقة بميزة "فحص التطبيق" عند تفعيلها لتطبيق iOS. لحلّ هذه الأخطاء، جرِّب ما يلي:

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

فرض استخدام فحص التطبيقات لعميل iOS

لا يؤدي تفعيل فحص التطبيقات لتطبيقك إلى حظر الطلبات غير المعروفة تلقائيًا. لتفعيل هذه الحماية، انتقِل إلى عرض التعديل في تطبيق iOS. ستظهر لك مقاييس فحص التطبيقات على يسار الصفحة ضمن قسم Google Identity لنظام التشغيل iOS. تتضمّن المقاييس المعلومات التالية:

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

راجِع هذه المقاييس لمعرفة تأثير فرض استخدام فحص التطبيقات على المستخدمين.

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

ملاحظة: بعد تفعيل خيار فرض القيود، قد يستغرق تطبيق التغييرات ما يصل إلى 15 دقيقة.

إيقاف فرض استخدام فحص التطبيقات على عميل iOS

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

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

ملاحظة: بعد إيقاف فرض استخدام فحص التطبيقات، قد يستغرق تطبيق التغييرات مدة تصل إلى 15 دقيقة.

إيقاف فحص التطبيقات لعميل iOS

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

لإيقاف ميزة فحص التطبيقات لعميل iOS، انتقِل إلى عرض التعديل الخاص بعميل iOS وأوقِف زر التبديل حماية عميل OAuth من إساءة الاستخدام باستخدام ميزة فحص التطبيقات من Firebase.

ملاحظة: بعد إيقاف فحص التطبيقات، قد يستغرق تطبيق التغييرات مدة تصل إلى 15 دقيقة.

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

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

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

محتوى إضافي للقراءة

تحدّد وثيقة IETF Best Current Practice 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 للتطبيقات المتوافقة مع أجهزة iOS والكمبيوتر تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المكتبات والعينات

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

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

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

iOS

UWP

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

الحصول على رموز الدخول عبر 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

فحص التطبيقات (على أجهزة iOS فقط)

تفعيل فحص التطبيقات على عميل iOS

فرض استخدام فحص التطبيقات لعميل iOS

إيقاف فرض استخدام فحص التطبيقات على عميل iOS

إيقاف فحص التطبيقات لعميل iOS

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

محتوى إضافي للقراءة

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

بروتوكول OAuth 2.0 للتطبيقات المتوافقة مع أجهزة iOS والكمبيوتر

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`deleted_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

أمثلة على `curl`