تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

البدائل

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

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

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

ننصحك بالاستعانة بالمكتبات والعيّنات التالية لمساعدتك في تنفيذ عملية OAuth 2.0 الموضّحة في هذا المستند:

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

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

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

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

Open the API Library في Google API Console.
If prompted, select a project, or create a new one.
استخدِم صفحة "المكتبة" للعثور على YouTube Data API وتفعيلها. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعِّلها أيضًا.

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

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

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

Android

اختَر نوع تطبيق Android.
أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في Credentials page لتحديد العميل.
أدخِل اسم حزمة تطبيق Android. يتم تحديد هذه القيمة في سمة package للعنصر <manifest> في ملف بيان تطبيقك.
أدخِل الملف المرجعي لشهادة التوقيع SHA-1 لتوزيع التطبيق.
- إذا كان تطبيقك يستخدِم ميزة "توقيع التطبيق" من Google Play، انسخ الملف المرجعي SHA-1 من صفحة توقيع التطبيق في Play Console.
- إذا كنت تدير ملف تخزين المفاتيح ومفاتيح التوقيع الخاصة بك، استخدِم الأداة keytool المضمّنة في Java لطباعة معلومات الشهادة بتنسيق يمكن لشخص عادي قراءته. انسخ قيمة SHA1 في قسم Certificate fingerprints من المخرجات keytool. اطّلِع على مصادقة العميل في مستندات Google APIs لنظام التشغيل Android للحصول على مزيد من المعلومات.
(اختياري) أثبِت ملكية تطبيق Android الخاص بك.
انقر على إنشاء.

iOS

اختَر نوع تطبيق iOS.
أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في Credentials page لتحديد العميل.
أدخِل معرّف الحزمة لتطبيقك. معرّف الحزمة هو قيمة مفتاح CFBundleIdentifier في ملف موارد قائمة المواقع المعلوماتية لتطبيقك (info.plist). يتم عرض القيمة في أغلب الأحيان في اللوحة "الإعدادات العامة" أو اللوحة "التوقيع والإمكانات" في محرِّر مشاريع 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 للحصول على مزيد من المعلومات.
ملاحظة: يجب ملء حقل "رقم تعريف الفريق" في حال تفعيل ميزة "فحص التطبيق" لعميلك.
(اختياري)
فعِّل ميزة "فحص التطبيقات" لتطبيقك على نظام التشغيل iOS. عند تفعيل هذه الميزة، يتم استخدام خدمة "إثبات ملكية التطبيق" من Apple للتحقّق من أنّ طلبات OAuth 2.0 الواردة من عميل OAuth حقيقية وأنّها تأتي من تطبيقك. يساعد ذلك في الحدّ من خطر انتحال هوية التطبيق. مزيد من المعلومات عن تفعيل ميزة "فحص التطبيق" في تطبيقك المتوافق مع نظام التشغيل iOS
انقر على إنشاء.

UWP

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

بالنسبة إلى تطبيقات UWP، لا يمكن أن يزيد طول مخطّط عنوان URL المخصّص عن 39 حرفًا.

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

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

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

يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:

المناظير
https://www.googleapis.com/auth/youtube	إدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creator	الاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-ssl	الاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonly	عرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.upload	إدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartner	عرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	عرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

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

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

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

الخطوة 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`)))
عادي	تحدّي الرمز هو القيمة نفسها لجهاز التحقّق من الرمز الذي تم إنشاؤه أعلاه. `code_challenge` = `code_verifier`

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

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

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

المعلمات

client_id

مطلوب

معرّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page.

redirect_uri

مطلوب

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

يجب أن تتطابق القيمة تمامًا مع أحد عناوين URL المعتمَدة لإعادة التوجيه الخاصة بعميل OAuth 2.0، والذي أعددته في العميل API Console Credentials page. إذا لم تتطابق هذه القيمة مع عنوان URL مفوَّض، ستظهر لك رسالة خطأ 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 للمستخدم.

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

يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:

المناظير
https://www.googleapis.com/auth/youtube	إدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creator	الاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-ssl	الاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonly	عرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.upload	إدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartner	عرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	عرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

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

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 لمنح الأذونات لخيارات عناوين URL لإعادة التوجيه المختلفة.

يطلب كل عنوان URL الوصول إلى نطاق يسمح بالوصول لاسترداد data YouTube الخاصة بالمستخدم.

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

مخطّط معرّف الموارد المنتظم (URI) المخصّص

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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.

Android

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

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

iOS

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

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

`org_internal`

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

`invalid_grant`

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

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

`redirect_uri_mismatch`

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

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

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

`invalid_request`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استدعاء واجهات برمجة تطبيقات Google

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

تجدر الإشارة إلى أنّ واجهة برمجة التطبيقات YouTube Live Streaming API لا تتيح مسار حساب الخدمة. بما أنّه ليس هناك طريقة لربط حساب خدمة بحساب YouTube، ستؤدي محاولات تفويض الطلبات باستخدام هذه الخطوات إلى ظهور خطأ NoLinkedYouTubeAccount.

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

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

قد تبدو طلبًا موجّهًا إلى نقطة نهاية liveBroadcasts.list (YouTube Live Streaming API) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. يُرجى العِلم أنّك بحاجة إلى تحديد رمز الدخول الخاص بك:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

أمثلة على `curl`

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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

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

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

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

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

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "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) مخصّص (Android وiOS وUWP)

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

بديل لاستخدام مخطّطات معرّفات الموارد المنتظمة (URI) المخصّصة على Android

استخدِم حزمة SDK لميزة "تسجيل الدخول باستخدام حساب Google" على Android التي تُرسِل استجابة OAuth 2.0 مباشرةً إلى تطبيقك، ما يُلغي الحاجة إلى عنوان URL لإعادة التوجيه.

إذا كنت تستخدِم مخطّطًا مخصّصًا لدمج OAuth على Android، عليك إكمال الإجراءات التالية لنقل البيانات بالكامل إلى استخدام حزمة تطوير البرامج (SDK) المُقترَحة من Google لتسجيل الدخول على Android:

عدِّل الرمز البرمجي لاستخدام حزمة تطوير البرامج (SDK) لميزة "تسجيل الدخول باستخدام حساب Google".
أوقِف ميزة توفير مخطّط مخصّص في "وحدة تحكّم واجهة برمجة تطبيقات Google".

اتّبِع الخطوات التالية لنقل البيانات إلى حزمة تطوير البرامج (SDK) لنظام التشغيل Android من ميزة "تسجيل الدخول باستخدام حساب Google":

عدِّل الرمز البرمجي لاستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android من Google Sign-In:
1. راجِع الرمز البرمجي لتحديد الموضع الذي يتم فيه إرسال طلب إلى خادم OAuth 2.0 في Google. في حال استخدام مخطّط مخصّص، سيظهر طلبك على النحو التالي:
```
  https://accounts.google.com/o/oauth2/v2/auth?
  scope=<SCOPES>&
  response_type=code&
  &state=<STATE>&
  redirect_uri=com.example.app:/oauth2redirect&
  client_id=<CLIENT_ID>
  
```
  com.example.app:/oauth2redirect هو معرّف الموارد المنتظم (URI) لإعادة التوجيه في المخطّط المخصّص في المثال أعلاه. اطّلِع على تعريف المَعلمة redirect_uri للحصول على مزيد من التفاصيل عن تنسيق قيمة مخطّط معرّف الموارد المنتظم المخصّص.
2. دوِّن مَعلمتَي الطلب scope وclient_id اللتين ستحتاج إليهما لضبط حزمة تطوير البرامج (SDK) لميزة "تسجيل الدخول باستخدام حساب Google".
  ملاحظة: إذا كنت تستخدم مكتبة تابعة لجهة خارجية، راجِعملف الإعدادات للمكتبة للعثور على هذه المعلومات.
3. اتّبِع تعليمات بدء دمج ميزة "تسجيل الدخول باستخدام حساب Google" في تطبيق Android لإعداد حزمة SDK. يمكنك تخطّي خطوة الحصول على معرِّف عميل OAuth 2.0 لخادم الخلفية لأنّك ستعيد استخدام client_id الذي استردته من الخطوة السابقة.
4. اتّبِع تعليمات تفعيل الوصول إلى واجهة برمجة التطبيقات من جهة الخادم. ويشمل ذلك الخطوات التالية:
  1. استخدِم طريقة getServerAuthCode لاسترداد رمز التفويض لتحديد النطاقات التي تطلب الحصول على إذن لها.
  2. أرسِل رمز التفويض إلى الخلفية في تطبيقك لاستبداله برمز مميّز للوصول وإعادة التحديث.
  3. استخدِم رمز الوصول الذي تم استرداده لإجراء طلبات إلى Google APIs بالنيابة عن المستخدم.
  ملاحظة: إذا كان تطبيقك لا يتطلّب الوصول إلى البيانات بلا إنترنت، اتّبِع هذه التعليمات بدلاً من ذلك لطلب الوصول إلى واجهة برمجة التطبيقات من جهة العميل.
أوقِف ميزة استخدام المخطط المخصّص في "وحدة تحكّم Google API":
1. انتقِل إلى قائمة بيانات اعتماد OAuth 2.0 واختَر عميل Android.
2. انتقِل إلى قسم الإعدادات المتقدّمة، وأزِل العلامة من مربّع الاختيار تفعيل نظام معرِّف موارد منتظم (URI) مخصَّص، ثم انقر على حفظ لمحاولة إيقاف إتاحة نظام معرِّف الموارد المنتظم (URI) المخصَّص.

تفعيل مخطّط URI المخصّص

إذا لم ينجح البديل المقترَح، يمكنك تفعيل مخطّطات عناوين URL المخصّصة لجهاز العميل الذي يعمل بنظام التشغيل Android باتّباع التعليمات التالية:

انتقِل إلى قائمة بيانات اعتماد OAuth 2.0 و اختَر عميل Android.
انتقِل إلى قسم الإعدادات المتقدّمة، وضَع علامة في مربّع الاختيار تفعيل مخطّط URI المخصّص، ثم انقر على حفظ لتفعيل التوافق مع مخطّط URI المخصّص.

بديل لاستخدام مخططات معرّفات الموارد المنتظمة (URI) المخصّصة في تطبيقات Chrome

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

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

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

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

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

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

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

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

إثبات ملكية التطبيق (على Android وChrome)

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

Android

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

يجب أن يكون لديك تطبيق مسجَّل في Google Play Console يحمل اسم الحزمة بصمة شهادة التوقيع SHA-1 نفسها المستخدَمة في ملف العميل OAuth لنظام التشغيل Android الذي تتم إكمال عملية إثبات ملكيته.
يجب أن يكون لديك إذن المشرف للتطبيق في Google Play Console. مزيد من المعلومات حول إدارة الأذونات في Google Play Console

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

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

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

تأكَّد من أنّ التطبيق الذي تُجري عملية إثبات ملكيته مسجَّل في Google Play Console.
تأكَّد من حصولك على إذن المشرف للتطبيق في Google Play Console.

Chrome

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

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

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

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

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

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

فحص التطبيق (iOS فقط)

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

تفعيل ميزة "فحص التطبيقات" لعميل iOS

يجب استيفاء المتطلبات التالية لتفعيل ميزة "فحص التطبيقات" لعملاء iOS بنجاح:

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

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

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

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

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

فرض ميزة "فحص التطبيق" على عميل iOS

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

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

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

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

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

إيقاف فرض ميزة "فحص التطبيق" على عميل iOS

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

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

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

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

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

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

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

مراجع إضافية

تُحدِّد أفضل الممارسات الحالية في 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 للتطبيقات المتوافقة مع الأجهزة الجوّالة وأجهزة الكمبيوتر المكتبي

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

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

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

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

Android

iOS

UWP

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

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

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

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

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

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

أمثلة على عناوين URL لمنح الأذونات

مخطّط معرّف الموارد المنتظم (URI) المخصّص

عنوان IP للحلقة المُغلقة

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

الأخطاء

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_grant

redirect_uri_mismatch

invalid_request

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

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

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

استدعاء واجهات برمجة تطبيقات Google

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

أمثلة على curl

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

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

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

مخطّط معرّف موارد منتظم (URI) مخصّص (Android وiOS وUWP)

بديل لاستخدام مخطّطات معرّفات الموارد المنتظمة (URI) المخصّصة على Android

كيفية نقل البيانات إلى حزمة تطوير البرامج (SDK) لميزة "تسجيل الدخول بحساب Google" على Android

تفعيل مخطّط URI المخصّص

بديل لاستخدام مخططات معرّفات الموارد المنتظمة (URI) المخصّصة في تطبيقات Chrome

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

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

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

إثبات ملكية التطبيق (على Android وChrome)

Android

Chrome

فحص التطبيق (iOS فقط)

تفعيل ميزة "فحص التطبيقات" لعميل iOS

فرض ميزة "فحص التطبيق" على عميل iOS

إيقاف فرض ميزة "فحص التطبيق" على عميل iOS

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

مراجع إضافية

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

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

أمثلة على `curl`