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

يوضّح هذا المستند كيف تستخدم التطبيقات المثبّتة على الأجهزة، مثل الهواتف والأجهزة اللوحية وأجهزة الكمبيوتر، نقاط نهاية 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 الموضّح في هذا المستند:

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

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

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

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

  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 APIs بيانات اعتماد تفويض لتعريف التطبيق على خادم OAuth 2.0 من Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن لتطبيقاتك بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.

  1. Go to the Credentials page.
  2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
  3. تصف الأقسام أدناه أنواع البرامج وطرق إعادة التوجيه التي يتوافق معها خادم التفويض في Google. اختَر نوع العميل المقترَح لتطبيقك، وأدخِل اسمًا لعميل OAuth، ثم اضبط الحقول الأخرى في النموذج على النحو المناسب.
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. (اختياري) أثبِت ملكية تطبيق Android.
  6. انقر على إنشاء.
iOS
  1. اختَر نوع تطبيق iOS.
  2. أدخِل اسمًا لعميل OAuth. يظهر هذا الاسم على Credentials page الخاص بمشروعك لتحديد العميل.
  3. أدخِل معرِّف الحزمة لتطبيقك. ويكون معرِّف الحزمة هو قيمة المفتاح CFBundleIdentifier في ملف موارد قائمة خصائص معلومات تطبيقك (info.plist). ويتم عرض القيمة غالبًا في اللوحة العامة أو جزء التوقيع والإمكانات في محرِّر مشروع Xcode. يتم عرض معرّف الحزمة أيضًا في قسم "المعلومات العامة" ضمن صفحة "معلومات التطبيق" الخاصة بالتطبيق على موقع App Store Connect من Apple.
  4. (سؤال اختياري)

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

    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 Store والمؤلّف من 12 حرفًا. يمكنك العثور على هذه القيمة في مركز شركاء Microsoft ضمن صفحة هوية التطبيق في قسم "إدارة التطبيقات".
  4. انقر على إنشاء.

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

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

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

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

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

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

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

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

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

  1. عدِّل الرمز لاستخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android لميزة "تسجيل الدخول بحساب Google":
    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 لمزيد من التفاصيل حول تنسيق قيمة المخطط المخصّص لمعرّف الموارد المنتظم (URI).
    2. دوِّن مَعلمتَي طلب scope وclient_id اللتين ستحتاج إليهما لإعداد حزمة تطوير البرامج (SDK) لتسجيل الدخول بحساب Google.
    3. اتّبِع تعليمات بدء دمج ميزة "تسجيل الدخول بحساب Google" في تطبيق Android لإعداد حزمة تطوير البرامج (SDK). يمكنك تخطّي خطوة الحصول على معرِّف عميل OAuth 2.0 لخادم الخلفية أثناء إعادة استخدام client_id الذي استرددته من الخطوة السابقة.
    4. اتّبِع تعليمات تفعيل الوصول إلى واجهة برمجة التطبيقات من جهة الخادم. ويتضمّن ذلك الخطوات التالية:
      1. استخدِم طريقة getServerAuthCode لاسترداد رمز مصادقة للنطاقات التي تطلب إذنًا لها.
      2. أرسِل رمز المصادقة إلى خلفية تطبيقك لاستبداله بالرمز المميّز للوصول وإعادة التحميل.
      3. استخدِم رمز الدخول الذي تم استرداده لإجراء طلبات من Google APIs بالنيابة عن المستخدم.
  2. أوقِف إتاحة المخطّط المخصّص في وحدة تحكّم واجهة Google API:
    1. انتقِل إلى قائمة بيانات اعتماد OAuth 2.0 واختَر برنامج Android الذي تستخدمه.
    2. انتقِل إلى قسم الإعدادات المتقدمة وأزِل العلامة من مربّع الاختيار تفعيل مخطط معرِّف الموارد المنتظم (URI) المخصّص، وانقر على حفظ لإيقاف التوافق مع مخطَّط URI المخصّص.
تفعيل مخطط معرّف موارد منتظم (URI) مخصّص
إذا لم يكن البديل المقترَح مناسبًا لك، يمكنك تفعيل مخطّطات معرّفات الموارد المنتظمة (URI) المخصّصة لبرنامج Android من خلال اتّباع التعليمات التالية:
  1. انتقِل إلى قائمة بيانات اعتماد OAuth 2.0 واختَر برنامج Android الخاص بك.
  2. انتقِل إلى قسم الإعدادات المتقدمة وضَع علامة في مربّع الاختيار تفعيل مخطط معرِّف الموارد المنتظم (URI) المخصَّص، ثم انقر على حفظ لتفعيل التوافق مع مخطَّط URI المخصّص.
بديل لاستخدام المخططات المخصصة لمعرّفات الموارد المنتظمة (URI) في تطبيقات Chrome

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

إثبات ملكية التطبيق (نظام التشغيل 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، انقر على زر إثبات الملكية لإكمال عملية إثبات الملكية.

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

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

لإصلاح إخفاق عملية التحقق، يُرجى تجربة ما يلي:

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

عنوان IP للاسترجاع (في نظام التشغيل macOS وLinux وWindows)

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

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

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

النسخ/اللصق اليدوي

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

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

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

يحتوي مستند نطاقات OAuth 2.0 API على قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى واجهات 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 مطلوب

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

redirect_uri مطلوب

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

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

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

قيم redirect_uri
مخطط معرّف موارد منتظم (URI) مخصّص com.example.app:redirect_uri_path

أو

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

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

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

response_type مطلوب

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

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

scope مطلوب

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

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

code_challenge سمة مقترَحة

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

code_challenge_method سمة مقترَحة

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

state سمة مقترَحة

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

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

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=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.

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 لنظام التشغيل iOS أو AppAuth for 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 تستخدم إحدى طرق الدمج المقترَحة.
  • يتم استخدام مخطط مخصّص لمعرّف الموارد المنتظم (URI) لإعادة التوجيه : إذا ظهرت رسالة الخطأ نظام معرّف الموارد المنتظم (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 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 APIs

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

ويمكنك تجربة جميع واجهات برمجة تطبيقات 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 مع رمز الخطأ.

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

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