يوضّح هذا المستند آلية استخدام تطبيقات خادم الويب لمكتبات برامج Google API أو نقاط نهاية Google OAuth 2.0 لتنفيذ تفويض OAuth 2.0 للوصول إلى Google APIs.
يسمح OAuth 2.0 للمستخدمين بمشاركة بيانات محدَّدة مع تطبيق مع الحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن للتطبيق استخدام OAuth 2.0 للحصول على إذن من المستخدمين لتخزين الملفات في Google Drive.
تهدف مسار OAuth 2.0 هذه تحديدًا إلى تفويض المستخدم. فهي مصممة للتطبيقات التي يمكنها تخزين المعلومات السرية والحفاظ على الحالة. يمكن لتطبيق خادم الويب المصرح له بشكل صحيح الوصول إلى واجهة برمجة التطبيقات أثناء تفاعل المستخدم مع التطبيق أو بعد مغادرة المستخدم للتطبيق.
تستخدم تطبيقات خادم الويب أيضًا حسابات الخدمة بشكل متكرر لتفويض طلبات واجهة برمجة التطبيقات، خاصةً عند طلب Cloud APIs للوصول إلى البيانات المستندة إلى المشروع بدلاً من البيانات الخاصة بالمستخدم. يمكن لتطبيقات خادم الويب استخدام حسابات الخدمة مع تفويض المستخدم.
مكتبات العملاء
تستخدِم الأمثلة بلغات معيّنة في هذه الصفحة مكتبات برامج Google API لتنفيذ تفويض OAuth 2.0. لتشغيل نماذج التعليمات البرمجية، يجب أولاً تثبيت مكتبة العميل للغتك.
عند استخدام مكتبة عميل Google API لمعالجة تدفق OAuth 2.0 في تطبيقك، ستجري مكتبة العميل العديد من الإجراءات التي سيحتاج التطبيق إلى معالجتها بنفسه. على سبيل المثال، يحدِّد هذا الإعداد الحالات التي يمكن أن يستخدم فيها التطبيق الرموز المميزة للوصول المخزَّن أو يعيد تحميلها، وكذلك الوقت الذي يجب أن يستقبل فيه التطبيق الموافقة. تنشئ مكتبة العميل أيضًا عناوين URL لإعادة التوجيه صحيحة وتساعد في تنفيذ معالجات إعادة التوجيه التي تتبادل رموز التفويض مع رموز الدخول.
تتوفّر "مكتبات عميل Google API" للتطبيقات من جهة الخادم باللغات التالية:
المتطلّبات الأساسية
تفعيل واجهات برمجة التطبيقات لمشروعك
ويجب على أي تطبيق يطلب 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 API، يجب أن يكون لديه بيانات اعتماد تفويض تحدِّد التطبيق في خادم OAuth 2.0 من Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن للتطبيقات بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد >؛ معرّف عميل OAuth.
- اختَر نوع تطبيق تطبيق الويب.
- املأ النموذج وانقر على إنشاء. يجب أن تحدّد التطبيقات التي تستخدم لغات وأُطر عمل
مثل PHP وJava وPython وRuby و .NET معرّفات الموارد المنتظمة (URI) المُعتمَدة. معرّفات الموارد المنتظمة (URI) هي نقاط النهاية التي يمكن لخادم OAuth 2.0 إرسال استجابات إليها. يجب أن تتوافق نقاط النهاية هذه مع قواعد التحقّق من Google.
لأغراض الاختبار، يمكنك تحديد معرّفات الموارد المنتظمة (URI) التي تشير إلى الجهاز المحلي، مثل
http://localhost:8080
. من هذا المنطلق، يُرجى العِلم أنّ جميع الأمثلة الواردة في هذا المستند تستخدمhttp://localhost:8080
كمعرّف موارد منتظم (URI) لإعادة التوجيه.نقترح تصميم نقاط نهاية المصادقة لتطبيقك حتى لا يعرض تطبيقك رموز التفويض لموارد أخرى على الصفحة.
بعد إنشاء بيانات الاعتماد، نزِّل ملف client_secret.json من API Console. خزِّن الملف بأمان في مكان يمكن لتطبيقك فقط الوصول إليه.
تحديد نطاقات الوصول
تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين أيضًا بالتحكّم في مقدار الوصول الذي تمنحه لهم. وبالتالي، قد تكون هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم.
قبل البدء في تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.
نقترح أيضًا أن يطلب طلبك الوصول إلى نطاقات التفويض من خلال عملية التفويض المتزايد، التي يطلب فيها تطبيقك الوصول إلى بيانات المستخدم في السياق. تساعد أفضل ممارسة هذه المستخدمين على فهم سبب حاجة تطبيقك إلى الوصول الذي يطلبه بسهولة أكبر.
يحتوي مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 على قائمة كاملة بالنطاقات التي قد تستخدمها للوصول إلى Google APIs.
المتطلبات المتعلّقة بلغات معيّنة
لتشغيل أي من نماذج التعليمات البرمجية في هذا المستند، ستحتاج إلى حساب Google وإذن بالوصول إلى الإنترنت ومتصفّح الويب. إذا كنت تستخدم إحدى مكتبات برامج واجهة برمجة التطبيقات، يمكنك أيضًا الاطّلاع على المتطلبات الخاصة بكل لغة أدناه.
PHP
لتشغيل نماذج رمز PHP في هذا المستند، ستحتاج إلى ما يلي:
- الإصدار 5.6 من لغة PHP أو الإصدارات الأحدث مع تثبيت واجهة سطر الأوامر (CLI) وإضافة JSON.
- أداة إدارة الاعتماد على الملحّن
-
مكتبة برامج Google APIs للغة PHP:
composer require google/apiclient:^2.10
Python
لتشغيل نماذج رمز Python في هذا المستند، ستحتاج إلى ما يلي:
- Python 2.6 أو إصدار أحدث
- أداة إدارة الحزمة pip.
- مكتبة برامج Google APIs لبرنامج Python:
pip install --upgrade google-api-python-client
google-auth
وgoogle-auth-oauthlib
وgoogle-auth-httplib2
لتفويض المستخدم.pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
- إطار عمل تطبيق الويب Flask Python.
pip install --upgrade flask
- مكتبة HTTP
requests
.pip install --upgrade requests
لغة Ruby
لتشغيل عيّنات رموز Ruby في هذا المستند، ستحتاج إلى ما يلي:
- لغة Ruby 2.2.2 أو أكثر
-
مكتبة عميل Google APIs لخدمة Ruby:
gem install google-api-client
-
إطار عمل تطبيق ويب Senatra Ruby.
gem install sinatra
Node.js
لتشغيل عيّنات رموز Node.js في هذا المستند، ستحتاج إلى ما يلي:
- الصيانة LTS أو LTS النشطة أو الإصدار الحالي من Node.js.
-
عميل Node.js في Google APIs:
npm install googleapis
HTTP/REST
وليس عليك تثبيت أي مكتبات لتتمكّن من استدعاء نقاط نهاية OAuth 2.0 مباشرةً.
الحصول على رموز الدخول عبر OAuth 2.0
توضّح الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 في Google للحصول على موافقة المستخدم على تنفيذ طلب بيانات من واجهة برمجة التطبيقات نيابةً عن المستخدم. ويجب أن يحصل تطبيقك على هذه الموافقة قبل أن يتمكّن من تنفيذ طلب واجهة برمجة تطبيقات في Google يتطلّب تفويض المستخدم.
وتلخِّص القائمة التالية الخطوات بسرعة:
- يحدِّد تطبيقك الأذونات التي يحتاج إليها.
- يعيد تطبيقك توجيه المستخدم إلى Google بالإضافة إلى قائمة الأذونات المطلوبة.
- يقرِّر المستخدم ما إذا كان سيمنح الأذونات لتطبيقك.
- ويكتشف التطبيق ما اتخذه المستخدم من قرار.
- إذا منَح المستخدم الأذونات المطلوبة، يسترد تطبيقك الرموز المميّزة اللازمة لإجراء طلبات البيانات من واجهة برمجة التطبيقات نيابةً عن المستخدم.
الخطوة 1: ضبط معلّمات التفويض
تتمثل الخطوة الأولى في إنشاء طلب التفويض. ويحدّد هذا الطلب المعلّمات التي تحدِّد تطبيقك وتحدِّد الأذونات التي سيُطلب من المستخدم منحها لتطبيقك.
- وإذا كنت تستخدم مكتبة عميل في Google لمصادقة OAuth 2.0 وتفويضها، يمكنك إنشاء عنصر يحدّد هذه المعلّمات وضبطه.
- إذا طلبت نقطة نهاية Google OAuth 2.0 مباشرةً، ستنشئ عنوان URL وستضبط المعلمات على عنوان URL هذا.
تحدد علامات التبويب أدناه معلمات التفويض المعتمدة لتطبيقات خادم الويب. وتوضّح الأمثلة المتعلقة باللغة أيضًا كيفية استخدام مكتبة عميل أو مكتبة تفويض لضبط عنصر يضبط هذه المعلّمات.
PHP
ينشئ مقتطف الرمز أدناه كائن Google\Client()
، والذي يحدد المعلمات في طلب التفويض.
يستخدم هذا العنصر معلومات من ملف client_secret.json لتحديد
تطبيقك. (يمكنك الاطّلاع على إنشاء بيانات اعتماد التفويض لمعرفة مزيد من المعلومات عن هذا الملف.) يحدد العنصر أيضًا النطاقات التي يطلبها تطبيقك الإذن
للدخول وعنوان URL لنقطة نهاية المصادقة في تطبيقك، والتي ستتعامل مع
الاستجابة من خادم OAuth 2.0 من Google. وأخيرًا، يحدّد الرمز المَعلمتَين الاختياريتَين access_type
وinclude_granted_scopes
.
على سبيل المثال، يتطلب هذا الرمز حق الوصول للقراءة فقط بلا اتصال بالإنترنت إلى مستخدم Google Drive:
$client = new Google\Client(); $client->setAuthConfig('client_secret.json'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); // offline access will give you both an access and refresh token so that // your app can refresh the access token without user interaction. $client->setAccessType('offline'); // Using "consent" ensures that your application always receives a refresh token. // If you are not using offline access, you can omit this. $client->setApprovalPrompt('consent'); $client->setIncludeGrantedScopes(true); // incremental auth
ويحدّد الطلب المعلومات التالية:
المعلَمات | |||||||
---|---|---|---|---|---|---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. ويمكنك العثور على هذه القيمة في API Console Credentials page. في لغة PHP، استدعاء الدالة $client = new Google\Client(); $client->setAuthConfig('client_secret.json'); |
||||||
redirect_uri |
مطلوب
يحدِّد هذا الإعداد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل
عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبرنامج OAuth 2.0، والتي تم ضبطها في برنامج العميل API Console
Credentials page
الخاص بك. وإذا لم تتطابق هذه القيمة مع معرِّف الموارد المنتظم (URI) المُعتمَد لإعادة التوجيه للسمة يُرجى العِلم أنّ المخطط لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setRedirectUri('https://oauth2.example.com/code'); |
||||||
scope |
مطلوب
قائمة النطاقات المحدَّدة بمسافات والتي تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتحدّد هذه القيم شاشة طلب الموافقة التي يعرضها محرّك البحث Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين بالتحكّم في مقدار الوصول الذي تمنحه لهم للتطبيق. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); ننصحك بأن يطلب طلبك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدم في السياق، من خلال التفويض المتزايد، أنت تساعد المستخدمين على فهم سبب حاجة التطبيق إلى الوصول الذي يطلبه بسهولة أكبر. |
||||||
access_type |
سمة مقترَحة
تشير هذه الخاصية إلى ما إذا كان بإمكان تطبيقك إعادة تحميل رموز الدخول عند عدم توفّر المستخدم بالمتصفّح. قيم المعلّمات الصالحة هي يمكنك ضبط القيمة على لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setAccessType('offline'); |
||||||
state |
سمة مقترَحة
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على حالتها بين طلب التفويض وردّ خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلّمة لأغراض متعدّدة، مثل توجيه المستخدم إلى المورد الصحيح في تطبيقك وإرسال الأرقام الخاصة والحد من التزوير على الطلبات من مواقع إلكترونية مختلفة. بما أنّه يمكن تخمين قيمة لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setState($sample_passthrough_value); |
||||||
include_granted_scopes |
اختياريّ
يسمح هذا الإعداد للتطبيقات باستخدام تفويض متزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة المعلَمة هذه على لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setIncludeGrantedScopes(true); |
||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المعلّمة لتقديم تلميح إلى "خادم مصادقة Google". ويستخدم الخادم التلميح لتبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني في نموذج تسجيل الدخول أو من خلال اختيار الجلسة المناسبة لتسجيل الدخول المتعدد. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setLoginHint('None'); |
||||||
prompt |
اختياريّ
قائمة برسائل المطالبة الحساسة لحالة الأحرف والمفصولة بمسافات لتقديم المستخدم. وإذا لم تحدّد هذه المعلّمة، ستتم مطالبة المستخدم فقط في المرة الأولى التي يطلب فيها مشروعك الوصول. يمكنك الاطّلاع على طلب إعادة الموافقة لمزيد من المعلومات. لإعداد هذه القيمة بالPHP، يجب استدعاء الدالة $client->setApprovalPrompt('consent'); القيم المحتمَلة هي:
|
Python
يستخدم مقتطف الرمز التالي الوحدة google-auth-oauthlib.flow
لإنشاء طلب التفويض.
تنشئ الرمز كائن Flow
، الذي يحدّد تطبيقك باستخدام
معلومات من ملف client_secret.json الذي نزّلته بعد
إنشاء بيانات اعتماد التفويض. ويحدد هذا الكائن أيضًا النطاقات التي يطلب فيها تطبيقك إذن الوصول وعنوان URL لنقطة نهاية المصادقة الخاصة بتطبيقك، وسيعالج هذا الإجراء الاستجابة من خادم OAuth 2.0 من Google. وأخيرًا،
يحدّد الرمز المَعلمتَين الاختياريتَين access_type
وinclude_granted_scopes
.
على سبيل المثال، يتطلب هذا الرمز حق الوصول للقراءة فقط بلا اتصال بالإنترنت إلى مستخدم Google Drive:
import google.oauth2.credentials import google_auth_oauthlib.flow # Use the client_secret.json file to identify the application requesting # authorization. The client ID (from that file) and access scopes are required. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) # Indicate where the API server will redirect the user after the user completes # the authorization flow. The redirect URI is required. The value must exactly # match one of the authorized redirect URIs for the OAuth 2.0 client, which you # configured in the API Console. If this value doesn't match an authorized URI, # you will get a 'redirect_uri_mismatch' error. flow.redirect_uri = 'https://www.example.com/oauth2callback' # Generate URL for request to Google's OAuth 2.0 server. # Use kwargs to set optional request parameters. authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
ويحدّد الطلب المعلومات التالية:
المعلَمات | |||||||
---|---|---|---|---|---|---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. ويمكنك العثور على هذه القيمة في API Console Credentials page. في Python، يجب استدعاء الطريقة flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) |
||||||
redirect_uri |
مطلوب
يحدِّد هذا الإعداد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل
عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبرنامج OAuth 2.0، والتي تم ضبطها في برنامج العميل API Console
Credentials page
الخاص بك. وإذا لم تتطابق هذه القيمة مع معرِّف الموارد المنتظم (URI) المُعتمَد لإعادة التوجيه للسمة يُرجى العِلم أنّ المخطط لضبط هذه القيمة في Python، يجب ضبط السمة flow.redirect_uri = 'https://oauth2.example.com/code' |
||||||
scope |
مطلوب
قائمة للنطاقات تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتحدّد هذه القيم شاشة طلب الموافقة التي يعرضها محرّك البحث Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين بالتحكّم في مقدار الوصول الذي تمنحه لهم للتطبيق. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. في Python، استخدِم الطريقة نفسها التي تستخدمها لضبط
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly']) ننصحك بأن يطلب طلبك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدم في السياق، من خلال التفويض المتزايد، أنت تساعد المستخدمين على فهم سبب حاجة التطبيق إلى الوصول الذي يطلبه بسهولة أكبر. |
||||||
access_type |
سمة مقترَحة
تشير هذه الخاصية إلى ما إذا كان بإمكان تطبيقك إعادة تحميل رموز الدخول عند عدم توفّر المستخدم بالمتصفّح. قيم المعلّمات الصالحة هي يمكنك ضبط القيمة على في Python، يمكنك ضبط المعلَمة authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
state |
سمة مقترَحة
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على حالتها بين طلب التفويض وردّ خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلّمة لأغراض متعدّدة، مثل توجيه المستخدم إلى المورد الصحيح في تطبيقك وإرسال الأرقام الخاصة والحد من التزوير على الطلبات من مواقع إلكترونية مختلفة. بما أنّه يمكن تخمين قيمة في Python، يمكنك ضبط المعلَمة authorization_url, state = flow.authorization_url( access_type='offline', state=sample_passthrough_value, include_granted_scopes='true') |
||||||
include_granted_scopes |
اختياريّ
يسمح هذا الإعداد للتطبيقات باستخدام تفويض متزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة المعلَمة هذه على في Python، يمكنك ضبط المعلَمة authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المعلّمة لتقديم تلميح إلى "خادم مصادقة Google". ويستخدم الخادم التلميح لتبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني في نموذج تسجيل الدخول أو من خلال اختيار الجلسة المناسبة لتسجيل الدخول المتعدد. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف في Python، يمكنك ضبط المعلَمة authorization_url, state = flow.authorization_url( access_type='offline', login_hint='None', include_granted_scopes='true') |
||||||
prompt |
اختياريّ
قائمة برسائل المطالبة الحساسة لحالة الأحرف والمفصولة بمسافات لتقديم المستخدم. وإذا لم تحدّد هذه المعلّمة، ستتم مطالبة المستخدم فقط في المرة الأولى التي يطلب فيها مشروعك الوصول. يمكنك الاطّلاع على طلب إعادة الموافقة لمزيد من المعلومات. في Python، يمكنك ضبط المعلَمة authorization_url, state = flow.authorization_url( access_type='offline', prompt='consent', include_granted_scopes='true') القيم المحتمَلة هي:
|
لغة Ruby
استخدِم الملف client_secrets.json الذي أنشأته لضبط كائن عميل في تطبيقك. عند إعداد كائن عميل، عليك تحديد النطاقات التي يحتاج التطبيق إلى الوصول إليها، بالإضافة إلى عنوان URL لنقطة نهاية المصادقة الخاصة بتطبيقك، والتي ستتعامل مع الاستجابة من خادم OAuth 2.0.
على سبيل المثال، يتطلب هذا الرمز حق الوصول للقراءة فقط بلا اتصال بالإنترنت إلى مستخدم Google Drive:
require 'google/apis/drive_v2' require 'google/api_client/client_secrets' client_secrets = Google::APIClient::ClientSecrets.load auth_client = client_secrets.to_authorization auth_client.update!( :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly', :redirect_uri => 'http://www.example.com/oauth2callback', :additional_parameters => { "access_type" => "offline", # offline access "include_granted_scopes" => "true" # incremental auth } )
يستخدم تطبيقك كائن العميل لإجراء عمليات OAuth 2.0، مثل إنشاء عناوين URL لطلب التفويض وتطبيق رموز الدخول على طلبات HTTP.
Node.js
ينشئ مقتطف الرمز أدناه كائن google.auth.OAuth2
، والذي يحدد المعلمات في طلب التفويض.
يستخدم هذا العنصر معلومات من ملف client_secret.json لتحديد تطبيقك. لطلب أذونات من مستخدم لاسترداد رمز الدخول، يمكنك إعادة توجيهه إلى صفحة موافقة. لإنشاء عنوان URL لصفحة الموافقة:
const {google} = require('googleapis'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI * from the client_secret.json file. To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
ملاحظة مهمة - يتم عرض refresh_token
فقط عند التفويض الأول. يمكنك الاطّلاع على المزيد من التفاصيل هنا.
HTTP/REST
نقطة نهاية OAuth 2.0 التابعة لشركة Google في https://accounts.google.com/o/oauth2/v2/auth
. ويمكن الوصول إلى نقطة النهاية هذه عبر بروتوكول HTTPS فقط. ويتم رفض اتصالات HTTP العادية.
يتيح خادم تفويض Google معلَمات سلسلة طلب البحث التالية لتطبيقات خادم الويب:
المعلَمات | |||||||
---|---|---|---|---|---|---|---|
client_id |
مطلوب
معرِّف العميل لتطبيقك. ويمكنك العثور على هذه القيمة في API Console Credentials page. |
||||||
redirect_uri |
مطلوب
يحدِّد هذا الإعداد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل
عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لبرنامج OAuth 2.0، والتي تم ضبطها في برنامج العميل API Console
Credentials page
الخاص بك. وإذا لم تتطابق هذه القيمة مع معرِّف الموارد المنتظم (URI) المُعتمَد لإعادة التوجيه للسمة يُرجى العِلم أنّ المخطط |
||||||
response_type |
مطلوب
تحدِّد هذه السياسة ما إذا كانت نقطة نهاية Google OAuth 2.0 تعرض رمز تفويض. اضبط قيمة المعلّمة على |
||||||
scope |
مطلوب
قائمة النطاقات المحدَّدة بمسافات والتي تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتحدّد هذه القيم شاشة طلب الموافقة التي يعرضها محرّك البحث Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين بالتحكّم في مقدار الوصول الذي تمنحه لهم للتطبيق. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. ننصحك بأن يطلب طلبك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدم في السياق، من خلال التفويض المتزايد، أنت تساعد المستخدمين على فهم سبب حاجة التطبيق إلى الوصول الذي يطلبه بسهولة أكبر. |
||||||
access_type |
سمة مقترَحة
تشير هذه الخاصية إلى ما إذا كان بإمكان تطبيقك إعادة تحميل رموز الدخول عند عدم توفّر المستخدم بالمتصفّح. قيم المعلّمات الصالحة هي يمكنك ضبط القيمة على |
||||||
state |
سمة مقترَحة
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على حالتها بين طلب التفويض وردّ خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج ويمكنك استخدام هذه المعلّمة لأغراض متعدّدة، مثل توجيه المستخدم إلى المورد الصحيح في تطبيقك وإرسال الأرقام الخاصة والحد من التزوير على الطلبات من مواقع إلكترونية مختلفة. بما أنّه يمكن تخمين قيمة |
||||||
include_granted_scopes |
اختياريّ
يسمح هذا الإعداد للتطبيقات باستخدام تفويض متزايد لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة المعلَمة هذه على |
||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المعلّمة لتقديم تلميح إلى "خادم مصادقة Google". ويستخدم الخادم التلميح لتبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني في نموذج تسجيل الدخول أو من خلال اختيار الجلسة المناسبة لتسجيل الدخول المتعدد. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف |
||||||
prompt |
اختياريّ
قائمة برسائل المطالبة الحساسة لحالة الأحرف والمفصولة بمسافات لتقديم المستخدم. وإذا لم تحدّد هذه المعلّمة، ستتم مطالبة المستخدم فقط في المرة الأولى التي يطلب فيها مشروعك الوصول. يمكنك الاطّلاع على طلب إعادة الموافقة لمزيد من المعلومات. القيم المحتمَلة هي:
|
الخطوة 2: إعادة التوجيه إلى خادم OAuth 2.0 في Google
أعِد توجيه المستخدم إلى خادم OAuth 2.0 في Google لبدء عملية المصادقة والتفويض. ويحدث ذلك عادةً عندما يحتاج تطبيقك إلى الوصول أولاً إلى بيانات المستخدم. في حال الحصول على تفويض متزايد، تحدث هذه الخطوة أيضًا عندما يحتاج طلبك إلى الوصول إلى مراجع إضافية لم يتم منحه الإذن بالوصول إليها بعد.
PHP
- يمكنك إنشاء عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:
$auth_url = $client->createAuthUrl();
- إعادة توجيه المستخدم إلى
$auth_url
:header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
Python
يعرض هذا المثال كيفية إعادة توجيه المستخدم إلى عنوان URL للتفويض باستخدام إطار عمل تطبيق Flask على الويب:
return flask.redirect(authorization_url)
لغة Ruby
- يمكنك إنشاء عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:
auth_uri = auth_client.authorization_uri.to_s
- إعادة توجيه المستخدم إلى
auth_uri
.
Node.js
-
استخدِم عنوان URL الذي تم إنشاؤه
authorizationUrl
من طريقة الخطوة 1generateAuthUrl
لطلب الوصول من خادم OAuth 2.0 في Google. -
إعادة توجيه المستخدم إلى
authorizationUrl
.res.writeHead(301, { "Location": authorizationUrl });
HTTP/REST
Sample redirect to Google's authorization server
An example URL is shown below, with line breaks and spaces for readability.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.
يصادق خادم OAuth 2.0 من Google المستخدم ويحصل على موافقة من المستخدم للوصول إلى النطاقات المطلوبة. سيتم إرسال الرد إلى تطبيقك باستخدام عنوان URL الذي حددته لإعادة التوجيه.
الخطوة 3: تطلب Google من المستخدم الموافقة على موافقته
في هذه الخطوة، يقرِّر المستخدم ما إذا كان سيمنح تطبيقك حق الوصول المطلوب. وفي هذه المرحلة، تعرض Google نافذة موافقة تعرض اسم التطبيق وخدمات Google API التي تطلب إذنًا للوصول إليها باستخدام بيانات اعتماد التفويض الخاصة بالمستخدم، وملخّصًا لنطاقات الوصول المطلوب منحها. ويمكن للمستخدم بعد ذلك الموافقة على منح حق الوصول إلى نطاق واحد أو أكثر من التطبيقات التي طلبها تطبيقك أو رفض الطلب.
لا يحتاج تطبيقك إلى اتخاذ أي إجراء في هذه المرحلة أثناء انتظار الردّ من خادم OAuth 2.0 في Google للإشارة إلى ما إذا كان قد تم منح أي إذن بالوصول. يتم شرح هذه الإجابة في الخطوة التالية.
الأخطاء
قد تعرض الطلبات إلى نقطة نهاية تفويض OAuth 2.0 في Google’s رسائل الخطأ التي تظهر للمستخدم، بدلاً من مسارات المصادقة والمصادقة المتوقعة. في ما يلي رموز الأخطاء الشائعة وحلولها المقترَحة.
admin_policy_enforced
يتعذّر على حساب Google تفويض نطاق واحد أو أكثر مطلوب بسبب سياسات مشرف Google Workspace. يُرجى الاطّلاع على مقالة مساعدة مشرف Google Workspace. التحكُّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace لمعرفة مزيد من المعلومات حول آلية المشرف في فرض قيود على الوصول إلى جميع النطاقات أو النطاقات الحساسة والمشروطة إلى أن يتم منح إذن الوصول صراحةً إلى معرِّف عميل OAuth
disallowed_useragent
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن تحظرها سياسات OAuth 2.0.
Android
قد تظهر رسالة خطأ لمطوّري برامج Android عند فتح طلبات التفويض في android.webkit.WebView
.
وبدلاً من ذلك، على مطوّري البرامج استخدام مكتبات Android، مثل
تسجيل الدخول بحساب Google لنظام التشغيل Android أو OpenID Foundation's
AppAuth for Android.
قد يواجه مطوّرو البرامج على الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من موقعك الإلكتروني. ويجب أن يسمح مطوّرو البرامج بفتح الروابط العامة في معالج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالِج روابط تطبيقات Android أو تطبيق المتصفّح التلقائي. وتُعدّ مكتبة علامات التبويب المخصّصة لنظام التشغيل Android أيضًا خيارًا متوافقًا.
iOS
قد يظهر لمطوّري برامج iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في
WKWebView
.
وبدلاً من ذلك، على مطوّري البرامج استخدام مكتبات iOS، مثل
تسجيل الدخول بحساب Google لنظام التشغيل iOS أو OpenID Foundation's
AppAuth لنظام التشغيل iOS.
قد يواجه مطوّرو البرامج على الويب هذا الخطأ عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من موقعك الإلكتروني. ويجب أن يسمح مطوّرو البرامج بفتح الروابط العامة في معالج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالجات الروابط العامة أو تطبيق المتصفّح التلقائي. وتُعدّ مكتبة SFSafariViewController
خيارًا متوافقًا أيضًا.
org_internal
معرّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من الوصول إلى حسابات Google في مؤسسة Google Cloud محدّدة. لمزيد من المعلومات حول خيار الضبط هذا، يُرجى الاطّلاع على القسم نوع المستخدم في مقالة مساعدة "إعداد شاشة موافقة OAuth".
redirect_uri_mismatch
لا يتطابق العنوان redirect_uri
الذي تم تمريره في طلب التفويض مع معرِّف الموارد المنتظم (URI) المُعتمَد لإعادة التوجيه لمعرِّف عميل OAuth. مراجعة معرفات الموارد المنتظمة (URI) المسموح بها في
Google API Console Credentials page
الخطوة 4: معالجة استجابة خادم OAuth 2.0
يستجيب لخادم OAuth 2.0 لطلب الوصول إلى التطبيق باستخدام عنوان URL المحدَّد في الطلب.
إذا وافق المستخدم على طلب الوصول، ستتضمّن الاستجابة رمز تفويض. إذا لم يوافق المستخدم على الطلب، ستحتوي الاستجابة على رسالة خطأ. تظهر رمز التفويض أو رسالة الخطأ التي يتم عرضها على خادم الويب في سلسلة طلب البحث، كما هو موضّح أدناه:
استجابة الخطأ:
https://oauth2.example.com/auth?error=access_denied
استجابة رمز التفويض:
https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
نموذج استجابة خادم OAuth 2.0
ويمكنك اختبار هذه العملية بالنقر على نموذج عنوان URL التالي، والذي يطلب إذنًا بالقراءة فقط لعرض البيانات الوصفية للملفات في حسابك على Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& access_type=offline& include_granted_scopes=true& response_type=code& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
بعد إكمال مسار OAuth 2.0، يجب إعادة توجيهك إلى
http://localhost/oauth2callback
، ومن المحتمل أن يؤدي ذلك إلى حدوث
خطأ 404 NOT FOUND
ما لم يعرِض جهازك المحلي ملفًا على ذلك العنوان. توفّر
الخطوة التالية المزيد من التفاصيل حول المعلومات الواردة في معرّف الموارد المنتظم (URI) عندما تتم إعادة توجيه
المستخدم إلى تطبيقك.
الخطوة 5: رمز تفويض Exchange للرموز المميزة لإعادة التحميل والوصول
بعد أن يتلقّى خادم الويب رمز التفويض، يمكنه استبدال رمز التفويض برمز الدخول.
PHP
لاستخدام رمز تفويض لرمز مميّز للوصول، استخدِم الطريقة authenticate
:
$client->authenticate($_GET['code']);
يمكنك استرداد رمز الدخول باستخدام طريقة getAccessToken
:
$access_token = $client->getAccessToken();
Python
في صفحة رد الاتصال، استخدِم مكتبة google-auth
للتحقّق من استجابة الخادم
للمصادقة. بعد ذلك، استخدِم الطريقة flow.fetch_token
لتبادل رمز التفويض
في هذه الاستجابة لرمز الدخول المميّز:
state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'], state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store the credentials in the session. # ACTION ITEM for developers: # Store user's access and refresh tokens in your data store if # incorporating this code into your real app. credentials = flow.credentials flask.session['credentials'] = { 'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes}
لغة Ruby
لاستخدام رمز تفويض لرمز مميّز للوصول، استخدِم الطريقة fetch_access_token!
:
auth_client.code = auth_code auth_client.fetch_access_token!
Node.js
لاستخدام رمز تفويض لرمز مميّز للوصول، استخدِم الطريقة getToken
:
const url = require('url'); // Receive the callback from Google's OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the OAuth 2.0 server response let q = url.parse(req.url, true).query; // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); }
HTTP/REST
لتبديل رمز التفويض لرمز الدخول، يمكنك استدعاء نقطة نهاية https://oauth2.googleapis.com/token
وضبط المعلمات التالية:
الحقول | |
---|---|
client_id |
معرّف العميل الذي تم الحصول عليه من API Console Credentials page. |
client_secret |
سرّ العميل الذي تمّ الحصول عليه من API Console Credentials page. |
code |
رمز التفويض الذي تم إرجاعه من الطلب المبدئي. |
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=https%3A//oauth2.example.com/code& grant_type=authorization_code
يستجيب Google لهذا الطلب من خلال عرض كائن JSON يحتوي على رمز دخول قصير الأجل ورمز مميز لإعادة التحميل.
يُرجى العلم بأنّ الرمز المميّز لإعادة التحميل لا يظهر إلا إذا ضبط تطبيقك المعلَمة access_type
على offline
في الطلب المبدئي إلى خادم التفويض في Google.
تحتوي الإجابة على الحقول التالية:
الحقول | |
---|---|
access_token |
الرمز المميز الذي يرسله تطبيقك لتفويض طلب Google API. |
expires_in |
القيمة المتبقية لرمز الدخول بالثواني. |
refresh_token |
رمز مميز يمكنك استخدامه للحصول على رمز دخول جديد. وتكون الرموز المميّزة لإعادة التحميل صالحة إلى أن يُبطِل المستخدم إذن الوصول.
مرة أخرى، لا يتوفّر هذا الحقل إلا في هذه الاستجابة إذا ضبطت المعلَمة access_type على offline في الطلب المبدئي على خادم التفويض من Google.
|
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
PHP
استخدم رمز الدخول لاستدعاء Google APIs بإكمال الخطوات التالية:
- إذا كنت بحاجة إلى تطبيق رمز الدخول على عنصر
Google\Client
جديد، على سبيل المثال، إذا خزّنت رمز الدخول في جلسة مستخدم، استخدِم الطريقةsetAccessToken
:$client->setAccessToken($access_token);
- يمكنك إنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد طلبها. يمكنك إنشاء عنصر خدمة من خلال توفير عنصر
Google\Client
مُصرَّح به لمنشئ واجهة برمجة التطبيقات الذي تريد طلبه. على سبيل المثال، لطلب واجهة برمجة تطبيقات Drive:$drive = new Google\Service\Drive($client);
- يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام
الواجهة التي يوفّرها عنصر الخدمة.
مثلاً، لإدراج الملفات في حساب المستخدم على Google Drive الذي تمت المصادقة عليه:
$files = $drive->files->listFiles(array())->getItems();
Python
بعد الحصول على رمز الدخول، يمكن لتطبيقك استخدام هذا الرمز المميز لمصادقة طلبات واجهة برمجة التطبيقات نيابةً عن حساب مستخدم أو حساب خدمة معيّن. استخدِم بيانات اعتماد التفويض الخاصة بالمستخدم لإنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد طلبها، ثم استخدِم هذا العنصر لإجراء طلبات واجهة برمجة تطبيقات مفوّضة.
- يمكنك إنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد طلبها. يمكنك إنشاء كائن خدمة من خلال
استدعاء الطريقة
build
في المكتبةgoogleapiclient.discovery
مع اسم إصدار واجهة برمجة التطبيقات وإصداره وبيانات اعتماد المستخدم: على سبيل المثال، لطلب الإصدار 2 من واجهة برمجة تطبيقات Drive:from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials)
- يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام
الواجهة التي يوفّرها عنصر الخدمة.
مثلاً، لإدراج الملفات في حساب المستخدم على Google Drive الذي تمت المصادقة عليه:
files = drive.files().list().execute()
لغة Ruby
استخدِم الكائن auth_client
لاستدعاء واجهات Google API من خلال إكمال الخطوات التالية:
- يمكنك إنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد طلبها.
مثلاً، لطلب الإصدار 2 من Drive API:
drive = Google::Apis::DriveV2::DriveService.new
- اضبط بيانات الاعتماد في الخدمة:
drive.authorization = auth_client
- تقديم طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام الواجهة
التي أدخلها عنصر الخدمة
على سبيل المثال، لإدراج الملفات في حساب المستخدم على Google الذي تمت المصادقة عليه:
files = drive.list_files
يمكن أيضًا توفير التفويض على أساس كل طريقة عن طريق توفير المعلَمة options
إلى الطريقة التالية:
files = drive.list_files(options: { authorization: auth_client })
Node.js
بعد الحصول على رمز الدخول وضبطه على الكائن OAuth2
، يمكنك استخدام الكائن لاستدعاء واجهات Google API. يمكن للتطبيق استخدام هذا الرمز المميز لتفويض طلبات البيانات من واجهة برمجة التطبيقات نيابةً عن
حساب مستخدم أو حساب خدمة معيّن. يمكنك إنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد طلبها.
const { google } = require('googleapis'); // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } });
HTTP/REST
بعد أن يحصل تطبيقك على رمز الدخول، يمكنك استخدام الرمز المميز لإجراء طلبات لواجهة Google API نيابةً عن حساب مستخدم معيّن إذا تم منح نطاقات الوصول المطلوبة من خلال واجهة برمجة التطبيقات. ولإجراء ذلك، يمكنك تضمين
رمز الدخول في طلب لواجهة برمجة التطبيقات من خلال تضمين إما معلمة طلب البحث access_token
أو قيمة Authorization
لعنوان HTTP Bearer
. ويُفضّل أن يكون عنوان HTTP إن أمكن، لأن سلاسل طلبات البحث تكون مرئية في سجلّات الخادم. وفي معظم
الحالات، يمكنك استخدام مكتبة برامج لإعداد طلباتك من أجل Google APIs (على سبيل المثال، عند
استدعاء واجهة برمجة تطبيقات ملفات Drive).
يمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها على مساحة المرح 2.0 OAuth.
أمثلة على 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
مثال كامل
يطبع المثال التالي قائمة بملفات بتنسيق JSON في Google Drive للمستخدم بعد مصادقة المستخدم والموافقة على وصول التطبيق إلى البيانات الوصفية على Drive للمستخدم.
PHP
لتشغيل هذا المثال:
- في السمة API Console، أضِف عنوان URL للجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف
http://localhost:8080
. - إنشاء دليل جديد والتغيير إليه. مثلاً:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- ثبِّت مكتبة عميل Google API للغة PHP باستخدام الملحّن:
composer require google/apiclient:^2.10
- أنشِئ الملفَين
index.php
وoauth2callback.php
باستخدام المحتوى أدناه. - نفِّذ المثال باستخدام خادم ويب تم إعداده لعرض لغة PHP. إذا كنت تستخدم الإصدار 5.6 أو إصدارًا أحدث من لغة PHP، يمكنك
استخدام خادم ويب تجريبي بلغة PHP's:
php -S localhost:8080 ~/php-oauth2-example
index.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfig('client_secrets.json'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); if (isset($_SESSION['access_token']) && $_SESSION['access_token']) { $client->setAccessToken($_SESSION['access_token']); $drive = new Google\Service\Drive($client); $files = $drive->files->listFiles(array())->getItems(); echo json_encode($files); } else { $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
oauth2callback.php
<?php require_once __DIR__.'/vendor/autoload.php'; session_start(); $client = new Google\Client(); $client->setAuthConfigFile('client_secrets.json'); $client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'); $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); if (! isset($_GET['code'])) { $auth_url = $client->createAuthUrl(); header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL)); } else { $client->authenticate($_GET['code']); $_SESSION['access_token'] = $client->getAccessToken(); $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL)); }
Python
يستخدم هذا المثال إطار عمل Flask. يشغّل
تطبيق الويب على http://localhost:8080
الذي يسمح لك باختبار تدفق OAuth 2.0. عند الانتقال إلى عنوان URL هذا، من المفترض أن تظهر لك أربعة روابط:
- اختبار طلب البيانات من واجهة برمجة التطبيقات: يوجّه هذا الرابط إلى صفحة تحاول تنفيذ نموذج لطلب واجهة برمجة التطبيقات. يؤدي هذا الأمر إلى بدء تدفق التفويض، إذا لزم الأمر. في حال نجاح ذلك، ستعرض الصفحة استجابة واجهة برمجة التطبيقات.
- اختبار تدفق المصادقة مباشرةً: يوجّه هذا الرابط إلى صفحة تحاول إرسال المستخدم من خلال تدفق التفويض. يطلب التطبيق إذنًا لإرسال طلبات مُعتمَدة من واجهة برمجة التطبيقات نيابةً عن المستخدم.
- إبطال بيانات الاعتماد الحالية: يوجّه هذا الرابط إلى صفحة تبطل الأذونات التي سبق أن منحها المستخدم للتطبيق.
- محو بيانات اعتماد جلسة Flask: يؤدي هذا الرابط إلى محو بيانات اعتماد التفويض المخزّنة في جلسة Flask. ويتيح لك هذا معرفة ما سيحدث إذا حاول مستخدم سبق له منح الإذن بتنفيذ تطبيقك تنفيذ طلب بيانات من واجهة برمجة التطبيقات في جلسة جديدة. وتتيح لك أيضًا الاطّلاع على استجابة واجهة برمجة التطبيقات التي يتلقّاها تطبيقك إذا أبطل المستخدم الأذونات التي تم منحها لتطبيقك، ولا يزال تطبيقك يحاول المصادقة على طلب باستخدام رمز دخول تم إبطاله.
# -*- coding: utf-8 -*- import os import flask import requests import google.oauth2.credentials import google_auth_oauthlib.flow import googleapiclient.discovery # This variable specifies the name of a file that contains the OAuth 2.0 # information for this application, including its client_id and client_secret. CLIENT_SECRETS_FILE = "client_secret.json" # This OAuth 2.0 access scope allows for full read/write access to the # authenticated user's account and requires requests to use an SSL connection. SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly'] API_SERVICE_NAME = 'drive' API_VERSION = 'v2' app = flask.Flask(__name__) # Note: A secret key is included in the sample so that it works. # If you use this code in your application, replace this with a truly secret # key. See https://flask.palletsprojects.com/quickstart/#sessions. app.secret_key = 'REPLACE ME - this value is here as a placeholder.' @app.route('/') def index(): return print_index_table() @app.route('/test') def test_api_request(): if 'credentials' not in flask.session: return flask.redirect('authorize') # Load credentials from the session. credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) drive = googleapiclient.discovery.build( API_SERVICE_NAME, API_VERSION, credentials=credentials) files = drive.files().list().execute() # Save credentials back to session in case access token was refreshed. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. flask.session['credentials'] = credentials_to_dict(credentials) return flask.jsonify(**files) @app.route('/authorize') def authorize(): # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES) # The URI created here must exactly match one of the authorized redirect URIs # for the OAuth 2.0 client, which you configured in the API Console. If this # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch' # error. flow.redirect_uri = flask.url_for('oauth2callback', _external=True) authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true') # Store the state so the callback can verify the auth server response. flask.session['state'] = state return flask.redirect(authorization_url) @app.route('/oauth2callback') def oauth2callback(): # Specify the state when creating the flow in the callback so that it can # verified in the authorization server response. state = flask.session['state'] flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( CLIENT_SECRETS_FILE, scopes=SCOPES, state=state) flow.redirect_uri = flask.url_for('oauth2callback', _external=True) # Use the authorization server's response to fetch the OAuth 2.0 tokens. authorization_response = flask.request.url flow.fetch_token(authorization_response=authorization_response) # Store credentials in the session. # ACTION ITEM: In a production app, you likely want to save these # credentials in a persistent database instead. credentials = flow.credentials flask.session['credentials'] = credentials_to_dict(credentials) return flask.redirect(flask.url_for('test_api_request')) @app.route('/revoke') def revoke(): if 'credentials' not in flask.session: return ('You need to <a href="/authorize">authorize</a> before ' + 'testing the code to revoke credentials.') credentials = google.oauth2.credentials.Credentials( **flask.session['credentials']) revoke = requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'}) status_code = getattr(revoke, 'status_code') if status_code == 200: return('Credentials successfully revoked.' + print_index_table()) else: return('An error occurred.' + print_index_table()) @app.route('/clear') def clear_credentials(): if 'credentials' in flask.session: del flask.session['credentials'] return ('Credentials have been cleared.<br><br>' + print_index_table()) def credentials_to_dict(credentials): return {'token': credentials.token, 'refresh_token': credentials.refresh_token, 'token_uri': credentials.token_uri, 'client_id': credentials.client_id, 'client_secret': credentials.client_secret, 'scopes': credentials.scopes} def print_index_table(): return ('<table>' + '<tr><td><a href="/test">Test an API request</a></td>' + '<td>Submit an API request and see a formatted JSON response. ' + ' Go through the authorization flow if there are no stored ' + ' credentials for the user.</td></tr>' + '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' + '<td>Go directly to the authorization flow. If there are stored ' + ' credentials, you still might not be prompted to reauthorize ' + ' the application.</td></tr>' + '<tr><td><a href="/revoke">Revoke current credentials</a></td>' + '<td>Revoke the access token associated with the current user ' + ' session. After revoking credentials, if you go to the test ' + ' page, you should see an <code>invalid_grant</code> error.' + '</td></tr>' + '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' + '<td>Clear the access token currently stored in the user session. ' + ' After clearing the token, if you <a href="/test">test the ' + ' API request</a> again, you should go back to the auth flow.' + '</td></tr></table>') if __name__ == '__main__': # When running locally, disable OAuthlib's HTTPs verification. # ACTION ITEM for developers: # When running in production *do not* leave this option enabled. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' # Specify a hostname and port that are set as a valid redirect URI # for your API project in the Google API Console. app.run('localhost', 8080, debug=True)
لغة Ruby
يستخدم هذا المثال إطار عمل Sinatra.
require 'google/apis/drive_v2' require 'google/api_client/client_secrets' require 'json' require 'sinatra' enable :sessions set :session_secret, 'setme' get '/' do unless session.has_key?(:credentials) redirect to('/oauth2callback') end client_opts = JSON.parse(session[:credentials]) auth_client = Signet::OAuth2::Client.new(client_opts) drive = Google::Apis::DriveV2::DriveService.new files = drive.list_files(options: { authorization: auth_client }) "<pre>#{JSON.pretty_generate(files.to_h)}</pre>" end get '/oauth2callback' do client_secrets = Google::APIClient::ClientSecrets.load auth_client = client_secrets.to_authorization auth_client.update!( :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly', :redirect_uri => url('/oauth2callback')) if request['code'] == nil auth_uri = auth_client.authorization_uri.to_s redirect to(auth_uri) else auth_client.code = request['code'] auth_client.fetch_access_token! auth_client.client_secret = nil session[:credentials] = auth_client.to_json redirect to('/') end end
Node.js
لتشغيل هذا المثال:
-
في الحقل API Console، أضِف عنوان URL للجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف
http://localhost
. - تأكَّد من تثبيت LTS أو LTS النشطة أو الإصدار الحالي من Node.js.
-
إنشاء دليل جديد والتغيير إليه. مثلاً:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
أنشئ الملفات
main.js
التي تتضمن المحتوى أدناه. -
تنفيذ المثال:
node .\main.js
Main.js
const http = require('http'); const https = require('https'); const url = require('url'); const { google } = require('googleapis'); /** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI. * To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */ const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for read-only Drive activity. const scopes = [ 'https://www.googleapis.com/auth/drive.metadata.readonly' ]; // Generate a url that asks permissions for the Drive activity scope const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true }); /* Global variable that stores user credential in this code example. * ACTION ITEM for developers: * Store user's refresh token in your data store if * incorporating this code into your real app. * For more information on handling refresh tokens, * see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens */ let userCredential = null; async function main() { const server = http.createServer(async function (req, res) { // Example on redirecting user to Google's OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google's OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // An error response e.g. error=access_denied console.log('Error:' + q.error); } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); /** Save credential to the global variable in case access token was refreshed. * ACTION ITEM: In a production app, you likely want to save the refresh token * in a secure persistent database instead. */ userCredential = tokens; // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { if (err1) return console.log('The API returned an error: ' + err1); const files = res1.data.files; if (files.length) { console.log('Files:'); files.map((file) => { console.log(`${file.name} (${file.id})`); }); } else { console.log('No files found.'); } }); } } // Example on revoking a token if (req.url == '/revoke') { // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end(); } res.end(); }).listen(80); } main().catch(console.error);
HTTP/REST
يستخدم مثال Python هذا إطار عمل Flask ومكتبة الطلبات لتوضيح تدفق الويب OAuth 2.0. ننصح باستخدام "مكتبة برامج Google API" للغة Python لهذا المسار. (يستخدم المثال في علامة التبويب Python مكتبة العميل.)
import json import flask import requests app = flask.Flask(__name__) CLIENT_ID = '123456789.apps.googleusercontent.com' CLIENT_SECRET = 'abc123' # Read from a file or environmental variable in a real app SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly' REDIRECT_URI = 'http://example.com/oauth2callback' @app.route('/') def index(): if 'credentials' not in flask.session: return flask.redirect(flask.url_for('oauth2callback')) credentials = json.loads(flask.session['credentials']) if credentials['expires_in'] <= 0: return flask.redirect(flask.url_for('oauth2callback')) else: headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])} req_uri = 'https://www.googleapis.com/drive/v2/files' r = requests.get(req_uri, headers=headers) return r.text @app.route('/oauth2callback') def oauth2callback(): if 'code' not in flask.request.args: auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code' '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE) return flask.redirect(auth_uri) else: auth_code = flask.request.args.get('code') data = {'code': auth_code, 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'redirect_uri': REDIRECT_URI, 'grant_type': 'authorization_code'} r = requests.post('https://oauth2.googleapis.com/token', data=data) flask.session['credentials'] = r.text return flask.redirect(flask.url_for('index')) if __name__ == '__main__': import uuid app.secret_key = str(uuid.uuid4()) app.debug = False app.run()
قواعد التحقق من معرف الموارد المنتظم (URI) لإعادة التوجيه
وتطبّق Google قواعد التحقّق التالية لإعادة توجيه معرّفات الموارد المنتظمة (URI) من أجل مساعدة مطوّري البرامج في الحفاظ على أمان تطبيقاتهم. يجب أن تلتزم معرفات الموارد المنتظمة (URI) بالقواعد هذه. يمكنك الاطّلاع على القسم 3 3986 من معايير RFC 3 للحصول على تعريف النطاق والمضيف والمسار وطلب البحث والمخطط ومعلومات المستخدم، كما هو موضّح أدناه.
قواعد التحقّق | |
---|---|
المخطط |
يجب أن تستخدم معرفات الموارد المنتظمة (URI) إعادة التوجيه مخطط HTTPS، وليس HTTP العادي. يتم إعفاء معرّفات الموارد المنتظمة (URI) للمضيف localhost (بما في ذلك معرّفات الموارد المنتظمة (URI) لعناوين IP للمضيف localhost) من هذه القاعدة. |
المضيف |
لا يمكن للمضيفين أن يكونوا عناوين IP أولية. يتم إعفاء عناوين IP للمضيف localhost من هذه القاعدة. |
النطاق |
“googleusercontent.com” .goo.gl ) إلا إذا كان التطبيق يمتلك النطاق. بالإضافة إلى ذلك، إذا اختار تطبيق يملك نطاقًا مختصرًا إعادة التوجيه إلى ذلك النطاق، يجب أن يحتوي معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه على “/google-callback/” في مساره أو ينتهي بـ “/google-callback” . |
معلومات المستخدم |
لا يمكن أن تحتوي معرفات الموارد المنتظمة (URI) الخاصة بإعادة التوجيه على المكوِّن الفرعي userinfo. |
المسار |
لا يمكن أن تحتوي معرّفات الموارد المنتظمة (URI) على إعادة توجيه مسار (تُسمّى أيضًا "الرجوع إلى الدليل السابق")،
ويتم تمثيلها من خلال |
طلب بحث |
لا يمكن أن تحتوي معرفات الموارد المنتظمة (URI) على إعادة التوجيه على عمليات إعادة توجيه مفتوحة. |
الجزء |
لا يمكن أن تحتوي معرفات الموارد المنتظمة (URI) على إعادة توجيه المكوِّن. |
الأحرف |
لا يمكن أن تحتوي معرفات الموارد المنتظمة (URI) على عمليات إعادة توجيه على أحرف معيّنة، بما في ذلك:
|
التفويض المتزايد
في بروتوكول OAuth 2.0، يطلب تطبيقك إذنًا للوصول إلى الموارد، التي يتم تحديدها من خلال النطاقات. من المفيد طلب الحصول على إذن للموارد في الوقت الذي تحتاج إليه عند استخدامها. ولتفعيل هذه الممارسة، يتيح خادم تفويض Google تفويضًا متزايدًا. تتيح لك هذه الميزة طلب النطاقات حسب الحاجة، وإذا منحت المستخدم الإذن للنطاق الجديد، تعرض رمز تفويض يمكن استبداله برمز مميز يحتوي على جميع النطاقات التي منحها المستخدم المشروع.
على سبيل المثال، قد يحتاج التطبيق الذي يسمح للمستخدمين بجمع عيّنة من المقاطع الموسيقية وإنشاء تشكيلات الألعاب إلى عدد قليل جدًا من الموارد عند تسجيل الدخول، وقد لا يكون هناك أكثر من اسم الشخص الذي يسجّل الدخول. ومع ذلك، سيتطلب حفظ التشكيلة المكتملة الوصول إلى Google Drive. يجد معظم المستخدمين أنّه من الطبيعي أن يُطلب منهم فقط الوصول إلى حساباتهم على Google Drive في الوقت الذي كان التطبيق فيه بحاجة إليها.
في هذه الحالة، قد يطلب التطبيق في وقت تسجيل الدخول النطاقَين openid
وprofile
لإجراء تسجيل الدخول الأساسي، ثم يطلب لاحقًا النطاق https://www.googleapis.com/auth/drive.file
في وقت تقديم الطلب الأول لحفظ مزيج.
لتنفيذ التفويض المتزايد، عليك إكمال العملية العادية لطلب رمز دخول، ولكن تأكّد من أن طلب التفويض يتضمن نطاقات سبق منحها. وتتيح هذه الطريقة لتطبيقك تجنُّب إدارة رموز دخول متعددة.
تنطبق القواعد التالية على رمز الدخول الذي تم الحصول عليه من تفويض متزايد:
- يمكن استخدام الرمز المميّز للوصول إلى الموارد المقابلة لأي من النطاقات المدرَجة في التفويض الجديد والمجمّع.
- عند استخدام الرمز المميز لإعادة التحميل للتفويض المُجمَّع للحصول على رمز الدخول، يمثل رمز الدخول التفويض المُجمَّع ويمكن استخدامه لأي من قيم
scope
المضمّنة في الاستجابة. - يتضمّن التفويض المجمّع جميع النطاقات التي منحها المستخدم إلى مشروع واجهة برمجة التطبيقات حتى إذا تمّ طلب الحصول على المنح من برامج مختلفة. على سبيل المثال، إذا منَح المستخدم إمكانية الوصول إلى نطاق واحد باستخدام تطبيق متوافق مع أجهزة سطح المكتب، ثم منح نطاقًا آخر للتطبيق نفسه من خلال برنامج متوافق مع الأجهزة الجوّالة، سيتضمن التفويض المجمّع كلا النطاقَين.
- إذا أبطلت رمزًا مميزًا يمثّل تفويضًا مجمّعًا، سيتم إبطال إمكانية الوصول إلى جميع نطاقات التفويض هذه نيابةً عن المستخدم المرتبط في الوقت نفسه.
تستخدم عيّنات الرموز بلغات معيّنة في الخطوة 1: ضبط معلّمات التفويض وعيّنة عنوان URL لإعادة التوجيه HTTP/REST في الخطوة 2: إعادة التوجيه إلى خادم OAuth 2.0 من Google تستخدم جميعها تفويضًا متزايدًا. تُظهر عيّنات التعليمات البرمجية أيضًا الرمز الذي يجب إضافته لاستخدام التفويض المتزايد.
PHP
$client->setIncludeGrantedScopes(true);
Python
في Python، يمكنك ضبط وسيطة الكلمة الرئيسية include_granted_scopes
على true
للتأكّد من أنّ طلب التفويض يتضمن نطاقات سبق منحها. من المحتمل جدًا ألا تكون
include_granted_scopes
وسيطة الكلمة الرئيسية فقط التي أعددتها، كما هو موضّح في المثال أدناه.
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
لغة Ruby
auth_client.update!( :additional_parameters => {"include_granted_scopes" => "true"} )
Node.js
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
HTTP/REST
GET https://accounts.google.com/o/oauth2/v2/auth? client_id=your_client_id& response_type=code& state=state_parameter_passthrough_value& scope=https%3A//www.googleapis.com/auth/drive.file& redirect_uri=https%3A//oauth2.example.com/code& prompt=consent& include_granted_scopes=true
إعادة تحميل رمز الدخول (التشغيل بلا إنترنت)
تنتهي صلاحية رموز الدخول بشكل دوري وتصبح بيانات اعتماد غير صالحة لطلب واجهة برمجة التطبيقات ذي الصلة. يمكنك إعادة تحميل رمز الدخول بدون طلب إذن من المستخدم (بما في ذلك ما إذا كان المستخدم غير موجود) إذا طلبت الوصول بلا اتصال بالإنترنت إلى النطاقات المرتبطة بالرمز المميز.
- إذا كنت تستخدم مكتبة برامج Google API، سيعيد كائن العميل تحميل رمز الدخول حسب الحاجة طالما أنك ضبط هذا العنصر للوصول بلا اتصال بالإنترنت.
- إذا كنت لا تستخدم مكتبة عميل، يجب ضبط معلَمة طلب HTTP
access_type
علىoffline
عند إعادة توجيه المستخدم إلى خادم OAuth 2.0 من Google. في هذه الحالة، يعرض خادم التفويض من Google رمزًا مميّزًا لإعادة التحميل عند تبديل رمز التفويض برمز مميّز للوصول. وبعد ذلك، إذا انتهت صلاحية رمز الدخول (أو في أي وقت آخر)، يمكنك استخدام رمز مميز لإعادة التحميل للحصول على رمز دخول جديد.
يجب توفّر إمكانية الوصول بلا إنترنت إلى أي تطبيق يحتاج إلى الوصول إلى Google API في حال عدم توفّر المستخدم. على سبيل المثال، يجب أن يتمكن التطبيق الذي يُجري خدمات النسخ الاحتياطي أو
تنفيذ الإجراءات في أوقات محدّدة مسبقًا من إعادة تحميل رمز الدخول الخاص به عند
عدم توفّر المستخدم. يُسمى نمط الوصول التلقائي online
.
تحصل جميع تطبيقات الويب من جانب الخادم والتطبيقات والأجهزة المثبّتة على رمز مميّز لإعادة التحميل أثناء عملية التفويض. لا تُستخدَم الرموز المميّزة لإعادة التحميل عادةً في تطبيقات الويب من جهة العميل (JavaScript).
PHP
إذا كان تطبيقك يحتاج إلى الوصول إلى Google API بلا اتصال بالإنترنت، اضبط نوع وصول عميل واجهة برمجة التطبيقات على offline
:
$client->setAccessType("offline");
بعد أن يمنح المستخدم حق الوصول بلا اتصال بالإنترنت إلى النطاقات المطلوبة، يمكنك مواصلة استخدام برنامج واجهة برمجة التطبيقات (API) للوصول إلى Google APIs نيابةً عن المستخدم بلا اتصال بالإنترنت. سيؤدي كائن العميل إلى إعادة تحميل رمز الدخول حسب الحاجة.
Python
في Python، يمكنك ضبط وسيطة الكلمة الرئيسية access_type
على offline
للتأكّد من أنّه سيكون بإمكانك إعادة تحميل رمز الدخول بدون الحاجة إلى إعادة إرسال طلب إلى المستخدم للحصول على إذن. ومن المحتمل جدًا أن تكون access_type
لن تكون وسيطة الكلمة الرئيسية فقط التي أعددتها، كما هو موضّح في المثال أدناه.
authorization_url, state = flow.authorization_url( # Enable offline access so that you can refresh an access token without # re-prompting the user for permission. Recommended for web server apps. access_type='offline', # Enable incremental authorization. Recommended as a best practice. include_granted_scopes='true')
بعد أن يمنح المستخدم حق الوصول بلا اتصال بالإنترنت إلى النطاقات المطلوبة، يمكنك مواصلة استخدام برنامج واجهة برمجة التطبيقات (API) للوصول إلى Google APIs نيابةً عن المستخدم بلا اتصال بالإنترنت. سيؤدي كائن العميل إلى إعادة تحميل رمز الدخول حسب الحاجة.
لغة Ruby
إذا كان تطبيقك يحتاج إلى الوصول إلى Google API بلا اتصال بالإنترنت، اضبط نوع وصول عميل واجهة برمجة التطبيقات على offline
:
auth_client.update!( :additional_parameters => {"access_type" => "offline"} )
بعد أن يمنح المستخدم حق الوصول بلا اتصال بالإنترنت إلى النطاقات المطلوبة، يمكنك مواصلة استخدام برنامج واجهة برمجة التطبيقات (API) للوصول إلى Google APIs نيابةً عن المستخدم بلا اتصال بالإنترنت. سيؤدي كائن العميل إلى إعادة تحميل رمز الدخول حسب الحاجة.
Node.js
إذا كان تطبيقك يحتاج إلى الوصول إلى Google API بلا اتصال بالإنترنت، اضبط نوع وصول عميل واجهة برمجة التطبيقات على offline
:
const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', /** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */ scope: scopes, // Enable incremental authorization. Recommended as a best practice. include_granted_scopes: true });
بعد أن يمنح المستخدم حق الوصول بلا اتصال بالإنترنت إلى النطاقات المطلوبة، يمكنك مواصلة استخدام برنامج واجهة برمجة التطبيقات (API) للوصول إلى Google APIs نيابةً عن المستخدم بلا اتصال بالإنترنت. سيؤدي كائن العميل إلى إعادة تحميل رمز الدخول حسب الحاجة.
تنتهي صلاحية رموز الدخول. ستستخدم هذه المكتبة تلقائيًا رمزًا مميزًا لإعادة التحميل للحصول على رمز دخول جديد إذا كانت على وشك الانتهاء. للتأكّد من تخزين أحدث الرموز المميزة دائمًا، يمكنك استخدام حدث الرموز المميزة:
oauth2Client.on('tokens', (tokens) => { if (tokens.refresh_token) { // store the refresh_token in your secure persistent database console.log(tokens.refresh_token); } console.log(tokens.access_token); });
يتم تنفيذ حدث الرمز المميز هذا فقط في التفويض الأول، وعليك ضبط السمة access_type
على offline
عند استدعاء الطريقة generateAuthUrl
لتلقّي الرمز المميّز لإعادة التحميل. إذا كنت قد منحت تطبيقك الأذونات المطلوبة بدون ضبط القيود المناسبة لتلقّي رمز مميّز لإعادة التحميل، عليك إعادة تفويض التطبيق لتلقّي رمز مميّز جديد لإعادة التحميل.
لضبط refresh_token
في وقت لاحق، يمكنك استخدام الطريقة setCredentials
:
oauth2Client.setCredentials({ refresh_token: `STORED_REFRESH_TOKEN` });
بعد حصول العميل على رمز مميّز لإعادة التحميل، سيتم الحصول على رموز الدخول وإعادة تحميلها تلقائيًا في الاستدعاء التالي لواجهة برمجة التطبيقات.
HTTP/REST
لإعادة تحميل رمز الدخول، يرسل تطبيقك طلب HTTPS POST
إلى خادم تفويض Google (https://oauth2.googleapis.com/token
) الذي يتضمّن المعلمات التالية:
الحقول | |
---|---|
client_id |
معرّف العميل الذي تم الحصول عليه من API Console |
client_secret |
سرّ العميل الذي تمّ الحصول عليه من API Console |
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" }
تذكَّر أنّه يتم فرض حدود على عدد الرموز المميّزة لإعادة التحميل التي سيتم إصدارها، أي حدّ أقصى لكل مجموعة تتضمّن عميلاً أو مستخدمًا وقيودًا لكل مستخدم في كل البرامج. يجب حفظ الرموز المميزة لإعادة التحميل في مساحة تخزين طويلة الأجل ومواصلة استخدامها طالما أنها صالحة. إذا طلب التطبيق عددًا كبيرًا جدًا من الرموز المميّزة لإعادة التحميل، قد يرجع ذلك إلى هذه الحدود، وفي هذه الحالة سيتوقّف عمل الرموز المميزة لإعادة التحميل.
إبطال رمز مميز
في بعض الحالات، قد يريد المستخدم إبطال حق الوصول الذي تم منحه إلى تطبيق. يمكن للمستخدم إبطال حق الوصول من خلال الانتقال إلى إعدادات الحساب. يمكنك الاطّلاع على إزالة قسم"الدخول إلى الموقع الإلكتروني"أو"التطبيقات"من المواقع الإلكترونية التابعة لجهات خارجية والتطبيقات التي يمكنها الوصول إلى حسابك للحصول على المزيد من المعلومات
ومن الممكن أيضًا أن يلغي تطبيق إذن الوصول المقدَّم إليه آليًا. يعد الإبطال الآلي مهمًا في الحالات التي يلغي فيها المستخدم الاشتراك أو يزيل تطبيقًا أو تتغير موارد واجهة برمجة التطبيقات التي تتطلبها التطبيق بشكل كبير. بعبارة أخرى، يمكن أن يتضمّن جزء من عملية الإزالة طلبًا من واجهة برمجة التطبيقات للتأكّد من إزالة الأذونات التي تم منحها في السابق للتطبيق.
PHP
لإبطال رمز مميز آليًا، اطلب revokeToken()
:
$client->revokeToken();
Python
لإبطال رمز مميّز آليًا، يمكنك إرسال طلب إلى
https://oauth2.googleapis.com/revoke
الذي يتضمّن الرمز المميّز كمعلّمة وضبط
عنوان Content-Type
:
requests.post('https://oauth2.googleapis.com/revoke', params={'token': credentials.token}, headers = {'content-type': 'application/x-www-form-urlencoded'})
لغة Ruby
لإبطال رمز مميّز آليًا، يمكنك إرسال طلب HTTP إلى نقطة نهاية oauth2.revoke
:
uri = URI('https://oauth2.googleapis.com/revoke') response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)
يمكن أن يكون الرمز المميز رمز دخول أو رمز تحديث. إذا كان الرمز المميّز للوصول هو رمز مميّز مخصّص للوصول إليه، ويتضمّن رمز مميّز آخر لإعادة التحميل، سيتم إبطال الرمز المميّز لإعادة التحميل.
إذا تمت معالجة عملية الإبطال بنجاح، يكون رمز حالة الاستجابة هو 200
. بالنسبة إلى حالات الخطأ، يتم عرض رمز الحالة 400
مع رمز خطأ.
Node.js
لإبطال رمز مميّز آليًا، يمكنك إرسال طلب HTTPS POST إلى نقطة نهاية /revoke
:
const https = require('https'); // Build the string for the POST request let postData = "token=" + userCredential.access_token; // Options for POST request to Google's OAuth 2.0 server to revoke a token let postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/revoke', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; // Set up the request const postReq = https.request(postOptions, function (res) { res.setEncoding('utf8'); res.on('data', d => { console.log('Response: ' + d); }); }); postReq.on('error', error => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end();
يمكن أن تكون معلمة الرمز المميز رمز دخول أو رمز تحديث لإعادة التحميل. إذا كان الرمز المميّز للوصول هو رمز مميّز مخصّص للوصول إليه، ويتضمّن رمز مميّز آخر لإعادة التحميل، سيتم إبطال الرمز المميّز لإعادة التحميل.
إذا تمت معالجة عملية الإبطال بنجاح، يكون رمز حالة الاستجابة هو 200
. بالنسبة إلى حالات الخطأ، يتم عرض رمز الحالة 400
مع رمز خطأ.
HTTP/REST
لإبطال رمز مميّز آليًا، يرسل طلبك طلبًا إلى
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
مع رمز خطأ.