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

• مكتبة AppAuth لنظام Android
• مكتبة AppAuth لنظام التشغيل iOS
• بروتوكول OAuth للتطبيقات: نظام التشغيل 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 API الذي يتطلب تفويض المستخدم.

الخطوة 1: إنشاء أداة للتحقّق من الرموز وإجراء اختبار

تتيح Google استخدام مفتاح التدقيق لتبادل الرموز. (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=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

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

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

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

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

الخطوة 5: تغيير رمز التفويض لإعادة التحميل والوصول رموز مميزة

لاستبدال رمز تفويض برمز دخول، عليك طلب نقطة نهاية 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

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

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

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