OAuth 2.0 لتطبيقات الجوّال وAMP

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
<a href="/intl/ar/ads/">البرنامج الإعلاني</a> وتوضّح هذه النظرة العامة مسارات OAuth 2.0 المتوافقة مع Google، ما يساعدك على ضمان اختيار المسار المناسب لتطبيقك.

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

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

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

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

البدائل

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

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

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

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

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

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

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

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

  1. Open the API Library في Google API Console.
  2. If prompted, select a project, or create a new one.
  3. تسرد API Library جميع واجهات برمجة التطبيقات المتاحة مجمّعة حسب مجموعة المنتجات ومدى رواجها. إذا كانت واجهة برمجة التطبيقات التي تريد تفعيلها غير مرئية في القائمة، استخدِم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
  4. اختر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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

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

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

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

ننصح باستخدام مخطط معرف موارد منتظم (URI) لتطبيقات Android وتطبيقات iOS وتطبيقات Universal Windows Platform (UWP).

Android
  1. اختَر نوع التطبيق Android.
  2. أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في مشروعك Credentials page للتعرّف على العميل.
  3. أدخِل اسم حزمة تطبيقك المتوافق مع Android. ويتم تحديد هذه القيمة في سمة package للعنصر <manifest> في ملف بيان تطبيقك.
  4. أدخِل الملف المرجعي لشهادة توقيع SHA-1 لتوزيع التطبيق.
    • إذا كان تطبيقك يستخدم توقيع التطبيق من Google Play، انسخ بصمة إصبع SHA-1 من صفحة توقيع التطبيق على Play Console.
    • إذا كنت تدير ملف تخزين المفاتيح ومفاتيح التوقيع الخاصة بك، استخدِم الأداة keytool المضمّنة في لغة Java لطباعة معلومات الشهادة بتنسيق يمكن للمستخدمين قراءته. انسَخ القيمة SHA1 في القسم Certificate fingerprints من إخراج keytool. لمزيد من المعلومات، راجِع مصادقة البرنامج في Google APIs لمستندات Android.
  5. انقر على إنشاء.
iOS
  1. اختَر نوع التطبيق iOS.
  2. أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في مشروعك Credentials page للتعرّف على العميل.
  3. أدخِل معرِّف الحزمة لتطبيقك. ورقم تعريف الحزمة هو قيمة مفتاح CFBundleIdentifier في ملف موارد قائمة معلومات التطبيق (info.plist). ويتم عرض القيمة بشكل أكثر شيوعًا في اللوحة العامة أو لوحة التوقيعات والإمكانات في محرّر مشروع Xcode. يتم عرض رقم تعريف الحزمة أيضًا في قسم"المعلومات العامة"في صفحة"معلومات التطبيق"للتطبيق على موقع Apple App Connect الإلكتروني.
  4. (سؤال اختياري)

    أدخل معرّف متجر التطبيقات لتطبيقك إذا تم نشر التطبيق في Apple App Store. رقم تعريف المتجر هو سلسلة رقمية مضمّنة في كل عنوان URL لمتجر Apple App Store.

    1. افتح تطبيق Apple App Store على جهاز iOS أو iPadOS.
    2. ابحث عن تطبيقك.
    3. اختَر الزر "مشاركة" (رمز مربّع وسهم متّجه للأعلى).
    4. اختَر نسخ الرابط.
    5. الصِق الرابط في محرِّر نصوص. رقم تعريف متجر التطبيقات هو الجزء الأخير من عنوان URL.

      مثال: https://apps.apple.com/app/google/id284815942

  5. (سؤال اختياري)

    أدخِل رقم تعريف الفريق. اطّلِع على تحديد موقع رقم تعريف الفريق في مستندات حساب مطوّر برامج Apple للحصول على مزيد من المعلومات.

  6. انقر على إنشاء.
النطاق الفائق العرض (UWP)
  1. اختَر نوع تطبيق Universal Windows Platform.
  2. أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم في مشروعك Credentials page للتعرّف على العميل.
  3. أدخل معرّف متجر Microsoft المكون من 12 حرفًا. يمكنك العثور على هذه القيمة في مركز شركاء Microsoft في صفحة هوية التطبيق في قسم إدارة التطبيقات.
  4. انقر على إنشاء.

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

عنوان IP لإعادة التشغيل (على نظامي التشغيل macOS وLinux وWindows)

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

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

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

نسخ/لصق يدوي

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

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

قبل البدء في تنفيذ تفويض 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 حرفًا والحد الأقصى للطول هو 8 أحرف.

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

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

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

طرق إنشاء اختبار الرمز
S256 (مقترَح) وتحدّي الرمز هو ترميز Base64URL (بدون مساحة متروكة) وتجزئة SHA256 لأداة التحقّق من الرمز.
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. تتعامل نقطة النهاية هذه مع البحث النشط في الجلسة، وتصادق المستخدم، وتحصل على موافقة المستخدم. ويمكن الوصول إلى نقطة النهاية فقط عبر طبقة المقابس الآمنة، وترفض الاتصالات عبر بروتوكول HTTP (غير طبقة المقابس الآمنة).

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

المعلَمات
client_id مطلوب

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

redirect_uri مطلوب

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

يجب أن تتطابق القيمة تمامًا مع أحد معرفات الموارد المنتظمة (URI) لإعادة التوجيه لعميل OAuth 2.0، الذي هيأته في API Console Credentials page. وإذا لم تتطابق هذه القيمة مع معرِّف الموارد المنتظم (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 المميّز وتأكيده.

login_hint اختياريّ

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

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

نماذج عناوين URL للتفويض

تعرض علامات التبويب أدناه نماذج عناوين URL للتفويض لخيارات إعادة توجيه معرّفات الموارد المنتظمة (URI) المختلفة لإعادة التوجيه.

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

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=&
 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=&
 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 أو OpenID Foundation وAppAuth لنظام التشغيل Android بدلاً من ذلك.

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

iOS

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

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

org_internal

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

redirect_uri_mismatch

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

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

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

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

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

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

لتبادل رمز تفويض باستخدام رمز الدخول، عليك استدعاء نقطة نهاية 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 API.
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/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

استدعاء واجهات Google API

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

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

أمثلة HTTP GET

قد يبدو استدعاء نقطة نهاية drive.files (واجهة برمجة تطبيقات ملفات Drive) باستخدام عنوان 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 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",
  "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 مع رمز خطأ.

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

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