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

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

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

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

ويشبه مسار التفويض هذا المسار المستخدَم في تطبيقات خادم الويب. ويتمثل الاختلاف الرئيسي في أنّ التطبيقات المثبّتة يجب أن تفتح متصفّح النظام وأن توفّر عنوان URL لإعادة التوجيه محليًا من أجل معالجة الاستجابات من خادم التفويض من 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. يتم عرض معرِّف الحزمة أيضًا في قسم "المعلومات العامة" ضمن صفحة "معلومات التطبيق" للتطبيق على موقع Apple App Store Connect.
  4. (سؤال اختياري)

    أدخِل رقم تعريف تطبيقك في App Store إذا كان قد تم نشره في App Store من Apple. معرِّف المتجر هو سلسلة رقمية مضمّنة في كل عنوان 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 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. عدِّل الرمز لاستخدام حزمة تطوير برامج 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)
قيم النماذج اضبط نوع التطبيق على تطبيق متوافق مع أجهزة الكمبيوتر المكتبي.

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

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

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

قبل البدء في تنفيذ تفويض 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 (يُنصح به) ويتمثل اختبار الرمز في تجزئة 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. تعالج نقطة النهاية هذه البحث عن جلسة نشطة، وتصادق على المستخدم، وتحصل على موافقة المستخدم. لا يمكن الوصول إلى نقطة النهاية إلا عبر طبقة المقابس الآمنة، وترفض اتصالات 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 للحصول على مثال حول كيفية إنشاء رمز 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 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 تستخدم طريقة دمج مقترَحة
  • يتم استخدام مخطّط مخصّص لمعرّف الموارد المنتظم (URI) لإعادة التوجيه : إذا ظهرت لك رسالة الخطأ إنّ مخطط معرّف الموارد المنتظم (URI) المخصّص غير متوافق مع تطبيقات Chrome أو لم يتم تفعيل نظام معرّف الموارد المنتظم (URI) المخصّص لعميل Android، هذا يعني أنّك تستخدم مخطط معرّف موارد منتظم (URI) مخصّص غير متوافق مع تطبيقات Chrome، ويتم إيقافه تلقائيًا على أجهزة Android. مزيد من المعلومات حول بدائل مخطّط عنوان URL المخصّص

الخطوة 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

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

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

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