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

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

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

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

يشبه مسار التفويض هذا المسار المستخدَم في تطبيقات خادم الويب. يكمن الاختلاف الرئيسي في أنّ التطبيقات المثبَّتة يجب أن تفتح متصفّح النظام وأن تقدّم عنوان URL لإعادة التوجيه المحلي لمعالجة الردود الواردة من خادم التفويض في Google.

البدائل

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

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

المكتبات والعيّنات

ننصحك بالاستعانة بالمكتبات والعيّنات التالية لمساعدتك في تنفيذ عملية OAuth 2.0 الموضّحة في هذا المستند:

• مكتبة AppAuth for 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. تعالج هذه النهاية نقطة البحث عن الجلسات النشطة، وتُجري مصادقة المستخدم، وتحصل على موافقته. لا يمكن الوصول إلى نقطة النهاية إلا من خلال طبقة المقابس الآمنة (SSL)، وتمتنع عن اتصالات HTTP (غير المحمية بطبقة المقابس الآمنة).

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

أمثلة على عناوين URL لمنح الأذونات

تعرض علامات التبويب أدناه أمثلة على عناوين URL لمنح الأذونات لخيارات عناوين URL لإعادة التوجيه المختلفة.

تكون عناوين 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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

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

للتحقّق مما إذا كان المستخدم قد منح تطبيقك إذن الوصول إلى نطاق معيّن، راجِع الحقل scope في استجابة رمز الوصول. نطاقات الوصول الممنوحة من قِبل رمز الأمان access_token مُعبَّرة عنها كقائمة من السلاسل الحساسة لحالة الأحرف والمفصولة بمسافات.

على سبيل المثال، يشير نموذج ردّ رمز الوصول التالي إلى أنّ المستخدم قد منح تطبيقك إذن الوصول إلى أذونات نشاط Drive وأحداث "تقويم Google" للقراءة فقط:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

استدعاء واجهات برمجة تطبيقات Google

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

يمكنك تجربة جميع واجهات برمجة تطبيقات Google والاطّلاع على نطاقات الوصول إليها على مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد يبدو طلب البيانات من نقطة نهاية drive.files (Drive Files API) باستخدام عنوان 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

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

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

لإعادة تحميل رمز مميّز للوصول، يُرسِل تطبيقك طلبًا عبر 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 https://www.googleapis.com/auth/calendar.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 ل التطبيقات الأصلية العديد من أفضل الممارسات الموثَّقة هنا.