يشرح هذا المستند كيفية استخدام التطبيقات المثبّتة على الأجهزة، مثل الهواتف والأجهزة اللوحية وأجهزة الكمبيوتر، لنقاط نهاية 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.
لتمكين واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console.
- If prompted, select a project, or create a new one.
- يضم API Library القائمة جميع واجهات برمجة التطبيقات المتاحة، مجمّعةً حسب عائلة المنتج وشعبيته. إذا كانت واجهة برمجة التطبيقات التي تريد تفعيلها غير مرئية في القائمة، استخدم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
- حدد واجهة برمجة التطبيقات التي تريد تمكينها، ثم انقر على الزر تمكين.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
إنشاء بيانات اعتماد التفويض
يجب أن يحتوي أي تطبيق يستخدم OAuth 2.0 للدخول إلى Google APIs على بيانات اعتماد مصادقة تحدد التطبيق في خادم OAuth 2.0 في Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن للتطبيقات بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- تصف الأقسام أدناه أنواع البرامج وطرق إعادة التوجيه المتوافقة مع خادم تفويض Google. اختَر نوع البرنامج المقترَح لتطبيقك، وأدخِل اسم عميل OAuth، واضبط الحقول الأخرى في النموذج على النحو المناسب.
مخطط معرف موارد منتظم (URI) مخصص (Android وiOS وUWP)
يُنصَح باستخدام نظام URI مخصّص لتطبيقات Android وتطبيقات iOS وتطبيقات Universal Windows Platform (UWP).
Android
- حدد نوع تطبيق Android.
- أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم على Credentials page لمشروعك لتحديد هوية العميل.
- أدخل اسم حزمة تطبيق Android. يتم تحديد هذه القيمة في
سمة
package
للعنصر<manifest>
في ملف بيان تطبيقك. - أدخل الملف المرجعي لشهادة توقيع SHA-1 لتوزيع التطبيق.
- إذا كان تطبيقك يستخدم ميزة "توقيع التطبيق" من Google Play، انسخ بصمة إصبع SHA-1 من صفحة توقيع التطبيق على Play Console.
- إذا كنت تدير ملف تخزين المفاتيح ومفاتيح التوقيع الخاصة بك، يمكنك استخدام الأداة المساعدة keytool المضمّنة في جافا لطباعة معلومات الشهادة بتنسيق يمكن للمستخدمين قراءته. انسخ القيمة
SHA1
في القسمCertificate fingerprints
من الناتج keytool. لمزيد من المعلومات، يمكنك الاطّلاع على مصادقة البرنامج في Google APIs لنظام التشغيل Android.
- انقر على إنشاء.
iOS
- اختَر نوع التطبيق iOS.
- أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم على Credentials page لمشروعك لتحديد هوية العميل.
- أدخِل معرّف الحزمة لتطبيقك. معرّف الحزمة هو قيمة مفتاح CFBundleIdentifier في ملف موارد قائمة معلومات التطبيق (info.plist). يتم عرض القيمة بشكل أكثر شيوعًا في الجزء "عام" أو جزء "التوقيع والإمكانات" من محرّر مشروع Xcode. يتم عرض معرّف الحزمة أيضًا في قسم "معلومات عامة" من صفحة "معلومات التطبيق" الخاصة بالتطبيق على موقع App Store على Apple.
- (سؤال اختياري)
أدخِل رقم تعريف App Store لتطبيقك في حال نشر التطبيق في App Store التابع لشركة Apple. رقم تعريف المتجر هو سلسلة رقمية مضمّنة في كل عنوان URL لتطبيق في Apple App Store.
- افتح تطبيق Apple App Store على جهاز iOS أو iPadOS.
- ابحث عن تطبيقك.
- حدد الزر مشاركة (رمز مربع وسهم لأعلى).
- اختَر نسخ الرابط.
- الصق الرابط في محرر النصوص. رقم تعريف متجر التطبيقات هو الجزء الأخير من عنوان URL.
مثال:
https://apps.apple.com/app/google/id284815942
- (سؤال اختياري)
أدخِل رقم تعريف الفريق. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على تحديد معرّف الفريق في مستندات حساب مطوّر البرامج في Apple.
- انقر على إنشاء.
النظام الأساسي العام (UWP)
- حدد نوع تطبيق Universal Windows Platform.
- أدخِل اسمًا لعميل OAuth. يتم عرض هذا الاسم على Credentials page لمشروعك لتحديد هوية العميل.
- أدخِل معرّف متجر Microsoft المؤلف من 12 حرفًا. يمكنك العثور على هذه القيمة في مركز شركاء Microsoft في صفحة هوية التطبيق في قسم إدارة التطبيقات.
- انقر على إنشاء.
بالنسبة إلى تطبيقات UWP، لا يمكن أن يتجاوز طول مخطط URI المخصص 39 حرفًا.
عنوان IP للاسترجاع (نظام التشغيل macOS أو Linux أو Windows)
لاستلام رمز التفويض باستخدام عنوان URL هذا، يجب أن يستمع تطبيقك إلى خادم الويب المحلي. ويمكن حدوث ذلك على العديد من الأنظمة الأساسية، وليس جميعها. ومع ذلك، إذا كانت المنصّة التي تستخدمها تعتمدها، فهذه هي الآلية المقترَحة للحصول على رمز التفويض.
عندما يتلقّى تطبيقك استجابة التفويض، يجب أن تستجيب الصفحة عن طريق عرض صفحة HTML التي توجّه المستخدم إلى إغلاق المتصفّح والعودة إلى تطبيقك، وذلك لتحقيق أفضل أداء.
الاستخدام المقترَح | تطبيقات macOS وLinux وWindows لسطح المكتب (ولكن ليس لتطبيقات Universal Windows Platform) |
قيم النماذج | اضبط نوع التطبيق على تطبيق متوافق مع أجهزة سطح المكتب. |
النسخ/اللصق اليدوي
تحديد نطاقات الوصول
تمكن النطاقات تطبيقك من طلب الوصول إلى الموارد التي يحتاجها فقط مع تمكين المستخدمين أيضًا من التحكم في مقدار الوصول الذي يمنحونه للتطبيق. وبالتالي، قد تكون هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم.
قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.
يحتوي مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 على قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs.
الحصول على رموز دخول OAuth 2.0 المميزة
توضّح الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 في Google للحصول على موافقة المستخدم على تنفيذ طلب واجهة برمجة التطبيقات بالنيابة عن المستخدم. ويجب أن يحصل تطبيقك على هذه الموافقة قبل أن يتمكن من تنفيذ طلب واجهة برمجة تطبيقات Google الذي يتطلب إذن المستخدم.
الخطوة 1: إنشاء تحقق من صحة الرموز والتحدّي
تتيح Google استخدام بروتوكول Key Key for Code Exchange (PKCE) لجعل تدفق التطبيق المثبّت أكثر أمانًا. ويتم إنشاء أداة تحقق فريدة من الترميز لكل طلب تفويض، ويتم إرسال قيمته المحوّلة، المعروفة باسم "code_challenge"، إلى خادم التفويض للحصول على رمز التفويض.
إنشاء أداة التحقق من الرمز
إنّ code_verifier
عبارة عن سلسلة تشفيرية عالية التشفير باستخدام الأحرف غير المحجوزة
[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"، ويجب ألا يزيد طولها عن 43 حرفًا
وبحد أقصى 128 حرفًا.
يجب أن تشتمل أداة التحقق من الشفرة على إنتروبيا كافية لجعل عملية تخمين القيمة غير عملية.
إنشاء اختبار التحقق من الشفرة
تتوفّر طريقتان لإنشاء تحدي الرمز.
طرق إنشاء تحديات الرموز | |
---|---|
S256 (مقترَح) | يتمثل اختبار الرمز في تجزئة SHA256 المشفّرة (بدون مساحة متروكة) لأداة التحقّق من صحة الرموز.
|
عادي | اختبار التحقق من الشفرة هو نفس قيمة أداة التحقق من الشفرة التي تم إنشاؤها أعلاه.
|
الخطوة 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)
المعتمَد، ستظهر لك رسالة خطأ يعرض الجدول أدناه قيمة المَعلمة
|
||||||
response_type |
مطلوب
تحدِّد هذه السياسة ما إذا كانت نقطة نهاية Google OAuth 2.0 تعرض رمز تفويض أم لا. يمكنك ضبط قيمة المعلمة على |
||||||
scope |
مطلوب
قائمة من النطاقات المحدّدة بمسافات تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. تُعلِم هذه القيم شاشة الموافقة التي تعرضها Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين أيضًا بالتحكم في مقدار الوصول الذي يمنحونه للتطبيق. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمال الحصول على موافقة المستخدم. |
||||||
code_challenge |
سمة مقترَحة
تحدِّد هذه السياسة |
||||||
code_challenge_method |
سمة مقترَحة
تحدّد الطريقة المستخدمة لترميز |
||||||
state |
سمة مقترَحة
لتحديد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلّمة لأغراض متعدّدة، مثل توجيه المستخدم إلى
المورد الصحيح في تطبيقك وإرسال معلومات خاصة والتقليل من تزييف
الطلبات عبر المواقع الإلكترونية. بما أنّه يمكن تخمين |
||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، فيمكنه استخدام هذه المعلمة لتقديم تلميح إلى خادم مصادقة Google. يستخدم الخادم التلميح لتبسيط عملية تسجيل الدخول إما من خلال الملء المسبق لحقل البريد الإلكتروني في نموذج تسجيل الدخول أو من خلال اختيار الجلسة المناسبة لتسجيل الدخول المتعدد. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف |
نماذج لعناوين URL للتفويض
تعرض علامات التبويب أدناه نماذج لعناوين URL للمصادقة لخيارات إعادة توجيه URI المختلفة.
عناوين URL متطابقة باستثناء قيمة المعلمة redirect_uri
. وتحتوي عناوين URL
أيضًا على المَعلمتَين response_type
وclient_id
المطلوبة
بالإضافة إلى المَعلمة state
الاختيارية. يحتوي كل عنوان URL على فواصل أسطر ومسافات لتسهيل القراءة.
مخطط معرف موارد منتظم (URI) مخصص
https://accounts.google.com/o/oauth2/v2/auth? scope=& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
عنوان IP للاسترجاع
https://accounts.google.com/o/oauth2/v2/auth? scope=& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
الخطوة 3: تطلب Google من المستخدم الموافقة
في هذه الخطوة، يقرر المستخدم ما إذا كان يريد منح التطبيق إمكانية الوصول المطلوبة أم لا. في هذه المرحلة، تعرض Google نافذة موافقة تعرض اسم تطبيقك وخدمات Google API التي تطلب إذنًا للوصول إليها من خلال بيانات اعتماد التفويض الخاصة بالمستخدم، بالإضافة إلى ملخص لنطاقات الوصول التي سيتم منحها. ويمكن للمستخدم بعد ذلك الموافقة على منح إمكانية الوصول إلى نطاق واحد أو أكثر من النطاقات التي يطلبها تطبيقك أو رفض الطلب.
لا يحتاج تطبيقك إلى اتخاذ أي إجراء في هذه المرحلة وهو ينتظر استجابة من خادم OAuth 2.0 من Google تشير إلى ما إذا كان قد تم منح أي إذن بالوصول أم لا. يتم شرح هذه الإجابة في الخطوة التالية.
الأخطاء
قد تعرض الطلبات المرسلة إلى نقطة نهاية تفويض OAuth 2.0 من Google رسائل خطأ موجهة للمستخدم بدلاً من تدفقات المصادقة والمصادقة المتوقعة. في ما يلي رموز الأخطاء الشائعة ودرجات الدقة المقترحة.
admin_policy_enforced
يتعذّر على حساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. يُرجى الاطِّلاع على مقالة مساعدة مشرف Google Workspace التحكُّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace للحصول على مزيد من المعلومات عن كيفية تقييد المشرف لإمكانية الوصول إلى جميع النطاقات أو النطاقات الحساسة والمقيَّدة إلى أن يتم منح الوصول صراحةً إلى معرِّف عميل OAuth.
disallowed_useragent
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن لا تسمح به سياسات OAuth 2.0 في Google.
Android
قد تظهر لمطوّري برامج Android رسالة الخطأ هذه عند فتح طلبات التفويض في android.webkit.WebView
.
وعلى مطوّري البرامج استخدام مكتبات Android، مثل تسجيل الدخول بحساب Google لنظام التشغيل Android أو AppAuth لأجهزة Android الخاصة بمؤسسة OpenID.
قد يواجه مطوّرو برامج الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمّنًا وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google من موقعك الإلكتروني. على مطوّري البرامج السماح بفتح الروابط العامة في معالج الروابط التلقائي لنظام التشغيل، ويشمل ذلك معالجات روابط تطبيقات Android أو تطبيق المتصفّح التلقائي، علمًا بأنّ مكتبة علامات التبويب المخصّصة لنظام التشغيل Android هي خيار متوافق أيضًا.
iOS
قد يظهر هذا الخطأ لمطوّري تطبيقات iOS وmacOS عند فتح طلبات التفويض في
WKWebView
.
وعلى مطوّري البرامج استخدام مكتبات iOS، مثل تسجيل الدخول بحساب Google لنظام التشغيل iOS أو AppAuth لنظام التشغيل iOS في مؤسسة OpenID.
قد يواجه مطوّرو البرامج على الويب هذا الخطأ عندما يفتح تطبيق 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) الذي تم إيقافه ولم يعد متوافقًا. يُرجى الرجوع إلى دليل نقل البيانات لتعديل عملية الدمج.
الخطوة 4: معالجة استجابة خادم OAuth 2.0
تعتمد الطريقة التي يتلقّى بها تطبيقك استجابة التفويض على مخطط URI لإعادة التوجيه الذي يستخدمه. بغض النظر عن المخطّط، ستحتوي
الاستجابة على رمز تفويض (code
) أو خطأ
(error
). على سبيل المثال، يشير error=access_denied
إلى أنّ المستخدم
رفض الطلب.
إذا منح المستخدم إمكانية الوصول إلى تطبيقك، يمكنك استبدال رمز التفويض برمز دخول ورمز مميز لإعادة التحميل كما هو موضّح في الخطوة التالية.
الخطوة 5: رمز تفويض Exchange للرموز المميزة للتحديث والوصول
لتبديل رمز التفويض برمز دخول، عليك طلب نقطة نهاية https://oauth2.googleapis.com/token
وضبط المَعلمات التالية:
الحقول | |
---|---|
client_id |
رقم تعريف العميل الذي تم الحصول عليه من API Console Credentials page. |
client_secret |
سر العميل الذي تم الحصول عليه من API Console Credentials page. |
code |
رمز التفويض المعروض من الطلب الأولي. |
code_verifier |
أداة التحقّق من الترميز التي أنشأتها في الخطوة 1. |
grant_type |
وفقًا لما هو محدّد في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على authorization_code . |
redirect_uri |
أحد عناوين URL لإعادة التوجيه المُدرَجة لمشروعك في
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 نيابةً عن حساب مستخدم معيّن إذا تم منح نطاق الوصول المطلوب لواجهة برمجة التطبيقات. ولإجراء ذلك، يمكنك تضمين رمز الدخول في طلب إلى واجهة برمجة التطبيقات من خلال تضمين إما مَعلمة طلب البحث access_token
أو قيمة Authorization
لرأس HTTP Bearer
. ويُفضّل استخدام عنوان HTTP كلما أمكن، لأن سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. وفي معظم
الحالات، يمكنك استخدام مكتبة برامج لإعداد عمليات استدعاء إلى Google APIs (على سبيل المثال، عند
استدعاء واجهة برمجة تطبيقات ملفات Drive).
يمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها في مساحة تخزين بروتوكول OAuth 2.0.
أمثلة HTTP GET
يمكن أن يبدو استدعاء نقطة نهاية
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 للتطبيقات المحلية العديد من أفضل الممارسات الموثقة هنا.