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. الموضحة في هذا المستند:

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

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

يحتاج أي تطبيق يستدعي واجهات Google APIs إلى تفعيل واجهات برمجة التطبيقات هذه في 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 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 لـ Apple App Store.

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

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

  5. (اختياري)

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

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

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

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

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

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

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

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

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

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

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

  1. حدِّث الرمز الخاص بك لاستخدام حزمة تطوير البرامج (SDK) الخاصة بميزة "تسجيل الدخول بحساب Google" على أجهزة Android:
    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 هو عنوان URL لإعادة توجيه المخطط المخصص في المثال أعلاه. يمكنك الاطّلاع على تعريف المَعلمة 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 التي توفر استجابة 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"، انقر على زر إثبات الملكية لإكمال عملية إثبات الملكية.

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

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

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

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

عنوان IP الاسترجاعي (macOS وLinux وWindows Desktop)

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

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

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

نسخ/لصق يدوي

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

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

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

يحتوي مستند نطاقات واجهة برمجة تطبيقات 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 (موصى بها) تحدي الرمز هو تجزئة 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 للاسترجاع على الأجهزة الجوّالة app هو متوقف.

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 بعد موافقة المستخدم على طلب اشتراكك أو رفضه طلب وصول.

ويمكنك استخدام هذه المعلمة لعدة أغراض، مثل توجيه المستخدم إلى الصفحة المورد الصحيح في تطبيقك، وإرسال nonces، وتخفيف طلبات المواقع الإلكترونية المشتركة التزوير. بما أنّه يمكن تخمين redirect_uri باستخدام state قيمة يمكن أن يزيد من ضمانك بأن الاتصال الوارد هو نتيجة طلب مصادقة. إذا قمت بإنشاء سلسلة عشوائية أو ترميز تجزئة ملف تعريف ارتباط أو قيمة أخرى تحدد حالة العميل، فيمكنك التحقق من صحة الاستجابة بالإضافة إلى ذلك أن الطلب والاستجابة قد نشأا في المتصفح نفسه، وتوفير الحماية ضد الهجمات مثل طلب من مواقع إلكترونية متعددة التزوير. يمكنك الاطّلاع على ربط OpenID للحصول على مثال حول كيفية إنشاء رمز مميّز 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

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

Android

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

قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 في Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي نظام التشغيل، والذي يشمل كلاً من Android App Links المستخدم أو تطبيق المتصفح الافتراضي. تشير رسالة الأشكال البيانية علامات التبويب المخصَّصة في 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".

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 أداة التحقّق من الرموز التي أنشأتها في الخطوة الأولى:
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/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

الاتصال بـ Google APIs

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

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

أمثلة على الحصول على HTTP

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

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 وتحدِّد التطبيقات الأصلية العديد من أفضل الممارسات الموثَّقة هنا.

تطبيق ميزة "الحماية العابرة للحساب"

خطوة إضافية ينبغي لك اتخاذها لحماية حسابات المستخدمين الحسابات تنفّذ ميزة "على مستوى الحساب" يمكنك الحماية باستخدام "خدمة الحماية العابرة للحساب" من 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

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