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

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

• مكتبة AppAuth لنظام التشغيل Android
• مكتبة AppAuth لنظام التشغيل iOS
• OAuth لـ Apps: نماذج Windows

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

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

يحتاج أي تطبيق يستدعي 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، واضبط الحقول الأخرى في النموذج على النحو المناسب.

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

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

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

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

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

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

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 (غير طبقة المقابس الآمنة).

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

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

تعرض علامات التبويب أدناه نماذج لعناوين URL للمصادقة لخيارات إعادة توجيه URI المختلفة.

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

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

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 تشير إلى ما إذا كان قد تم منح أي إذن بالوصول أم لا. يتم شرح هذه الإجابة في الخطوة التالية.

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

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

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

الخطوة 5: رمز تفويض Exchange للرموز المميزة للتحديث والوصول

لتبديل رمز التفويض برمز دخول، عليك طلب نقطة نهاية https://oauth2.googleapis.com/token وضبط المَعلمات التالية:

يعرض المقتطف التالي نموذجًا لطلب:

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": "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) الذي يتضمن المعلمات التالية:

يعرض المقتطف التالي نموذجًا لطلب:

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