يشرح هذا المستند طريقة تنفيذ تفويض OAuth 2.0 للوصول إلى Google APIs من تطبيق ويب على JavaScript. يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محدّدة مع أحد التطبيقات والحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن للتطبيق استخدام OAuth 2.0 للحصول على إذن من المستخدمين لتخزين الملفات في Google Drive.
ويُطلق على مسار OAuth 2.0 هذا اسم مسار المنح الضمني. وهي مصممة للتطبيقات التي يمكنها الوصول إلى واجهات برمجة التطبيقات فقط عندما يكون المستخدم حاضرًا في التطبيق. ولا يمكن لهذه التطبيقات تخزين المعلومات السرية.
في هذه العملية، يفتح تطبيقك عنوان URL على Google يستخدم مَعلمات طلب البحث لتحديد تطبيقك ونوع الوصول إلى واجهة برمجة التطبيقات الذي يطلبه التطبيق. يمكنك فتح عنوان URL في نافذة المتصفّح الحالية أو نافذة منبثقة. يمكن للمستخدم المصادقة مع Google ومنح الأذونات المطلوبة. وبعد ذلك، تُعيد Google توجيه المستخدم إلى تطبيقك مرة أخرى. تتضمّن عملية إعادة التوجيه رمز الدخول المميز الذي يتحقّق منه تطبيقك ثم يستخدمه لإجراء طلبات البيانات من واجهة برمجة التطبيقات.
"مكتبة العميل في Google APIs" وخدمات Google Identity
إذا كنت تستخدم مكتبة برامج Google APIs للغة JavaScript لإجراء مكالمات معتمَدة على Google، عليك استخدام مكتبة خدمات Google Identity للتعامل مع مسار OAuth 2.0. يُرجى الاطّلاع على نموذج الرمز المميّز لخدمات "خدمات الهوية" من Google، استنادًا إلى مسار المنح الضمني لبروتوكول OAuth 2.0.
المتطلبات الأساسية
تفعيل واجهات برمجة التطبيقات لمشروعك
وأي تطبيق يستدعي Google APIs يحتاج إلى تفعيل واجهات برمجة التطبيقات هذه في API Console.
لتفعيل واجهة برمجة تطبيقات لمشروعك:
- Open the API Library في Google API Console.
- If prompted, select a project, or create a new one.
- تتضمّن القائمة API Library جميع واجهات برمجة التطبيقات المتاحة، مجمّعةً حسب مجموعة المنتجات ومدى رواجها. إذا كانت واجهة برمجة التطبيقات التي تريد تفعيلها غير مرئية في القائمة، استخدِم البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي ينتمي إليها.
- اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
إنشاء بيانات اعتماد التفويض
يجب أن يحتوي أي تطبيق يستخدم OAuth 2.0 للوصول إلى Google APIs على بيانات اعتماد تفويض تحدد التطبيق إلى خادم OAuth 2.0 من Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. يمكن لتطبيقاتك بعد ذلك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.
- Go to the Credentials page.
- انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
- اختَر نوع التطبيق تطبيق الويب.
- أكمل النموذج. يجب أن تحدّد التطبيقات التي تستخدم JavaScript لإجراء طلبات مُعتمَدة من Google API مصادر JavaScript المعتمدة. تحدد المصادر النطاقات التي يمكن لتطبيقك إرسال طلبات منها إلى خادم OAuth 2.0. ويجب أن تكون هذه المصادر متوافقة مع قواعد التحقّق التي تتّبعها Google.
تحديد نطاقات الوصول
وتتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين في الوقت نفسه بالتحكّم في مقدار الوصول الذي يمنحونه إلى تطبيقك. بالتالي، قد تكون هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمال الحصول على موافقة المستخدم.
قبل بدء تنفيذ تفويض OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.
يحتوي مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 على قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى واجهات Google API.
الحصول على رموز الدخول عبر بروتوكول OAuth 2.0
تعرض الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 من Google للحصول على موافقة المستخدم على تنفيذ طلب البيانات من واجهة برمجة التطبيقات نيابةً عن المستخدم. يجب أن يحصل تطبيقك على هذه الموافقة قبل أن يتمكّن من تنفيذ طلب Google API الذي يتطلّب الحصول على تفويض من المستخدم.
الخطوة 1: إعادة التوجيه إلى خادم OAuth 2.0 من Google
لطلب إذن بالوصول إلى بيانات المستخدم، أعِد توجيه المستخدم إلى خادم OAuth 2.0 من Google.
نقاط نهاية OAuth 2.0
يمكنك إنشاء عنوان URL لطلب إذن الوصول من نقطة نهاية 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 |
مطلوب
تحتاج تطبيقات JavaScript إلى ضبط قيمة المعلّمة على |
||||||
scope |
مطلوب
تمثّل هذه السمة قائمة بالنطاقات التي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. تعرض هذه القيم شاشة الموافقة التي يعرضها محرّك بحث Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاجها فقط مع السماح للمستخدمين في الوقت نفسه بالتحكّم في مقدار الوصول الذي يمنحونه إلى تطبيقك. بالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمال الحصول على موافقة المستخدم. ننصح بأن يطلب طلبك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدمين في السياق، يمكنك مساعدة المستخدمين على فهم سبب حاجة تطبيقك إلى الإذن بالوصول المطلوب من خلال التفويض المتزايد. |
||||||
state |
سمة مقترَحة
تحدِّد هذه السياسة أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض وردّ خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج من ويمكنك استخدام هذه المعلّمة لعدة أغراض، مثل توجيه المستخدم إلى المورد الصحيح في تطبيقك وإرسال رموز مميّزة والحدّ من تزوير الطلبات من مواقع إلكترونية مختلفة. بما أنّه يمكن تخمين |
||||||
include_granted_scopes |
اختياريّ
يتيح هذا الإذن للتطبيقات استخدام التفويض المتزايد لطلب الوصول إلى نطاقات إضافية
في السياق. إذا ضبطت قيمة هذه المَعلمة على |
||||||
login_hint |
اختياريّ
إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المعلّمة لتقديم تلميح إلى خادم المصادقة في Google. يستخدم الخادم تلميحًا لتبسيط عملية تسجيل الدخول إما من خلال ملء حقل البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو من خلال اختيار جلسة تسجيل الدخول المتعدد المناسبة. اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف |
||||||
prompt |
اختياريّ
هي قائمة رسائل مطالبة محدّدة لحالة الأحرف، مع الفصل بينها بمسافات لتقديم المستخدم. وإذا لم تحدِّد هذه المَعلمة، سيُطلب من المستخدم المشاركة في المرة الأولى التي يطلب فيها مشروعك الوصول إليها. اطّلِع على مقالة طلب إعادة الموافقة لمزيد من المعلومات. القيم المحتمَلة هي:
|
||||||
نموذج لإعادة التوجيه إلى خادم تفويض Google
في ما يلي مثال لعنوان URL، مع فواصل الأسطر والمسافات للقراءة.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.
نموذج رمز JavaScript
يعرض مقتطف JavaScript التالي طريقة لبدء مسار التفويض في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. بما أنّ نقطة النهاية OAuth 2.0 هذه لا تتوافق مع ميزة مشاركة الموارد المتعدّدة المصادر (CORS)، ينشئ المقتطف نموذجًا يفتح الطلب لنقطة النهاية هذه.
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauthSignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create <form> element to submit parameters to OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': 'YOUR_CLIENT_ID',
'redirect_uri': 'YOUR_REDIRECT_URI',
'response_type': 'token',
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
'include_granted_scopes': 'true',
'state': 'pass-through value'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
الخطوة 2: طلب Google من المستخدم الموافقة
في هذه الخطوة، يقرِّر المستخدم ما إذا كان سيتم منح تطبيقك إذن الوصول المطلوب. في هذه المرحلة، تعرض Google نافذة موافقة تعرض اسم التطبيق وخدمات Google API التي تطلب إذن الوصول باستخدام بيانات اعتماد التفويض للمستخدم وملخّصًا لنطاقات الوصول التي يتم منحها. ويمكن للمستخدم بعد ذلك الموافقة على منح حق الوصول إلى نطاق واحد أو أكثر من التطبيقات التي يطلبها طلبك أو يرفض الطلب.
لا يحتاج تطبيقك إلى اتخاذ أي إجراء في هذه المرحلة أثناء انتظار الرد من خادم OAuth 2.0 في Google للإشارة إلى ما إذا تم منح أي إذن للوصول. يتم توضيح هذه الإجابة في الخطوة التالية.
الأخطاء
قد تعرض الطلبات الموجّهة إلى نقطة نهاية تفويض OAuth 2.0 في Google رسائل خطأ موجَّهة للمستخدمين بدلاً من مسارات المصادقة والتفويض المتوقّعة. في ما يلي رموز الأخطاء الشائعة ودرجات الدقة المقترحة.
admin_policy_enforced
يتعذّر على حساب Google تفويض نطاق واحد أو أكثر مطلوب بسبب سياسات مشرف Google Workspace. يمكنك الاطّلاع على مقالة مساعدة مشرف Google Workspace التحكُّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace لمزيد من المعلومات حول كيفية تقييد المشرف لإذن الوصول إلى جميع النطاقات أو النطاقات الحساسة والمحظورة إلى أن يتم منح إذن الوصول صراحةً إلى معرِّف عميل OAuth.
disallowed_useragent
يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن ولا تسمح به سياسات OAuth 2.0 في Google.
Android
قد تظهر لمطوّري برامج Android رسالة الخطأ هذه عند فتح طلبات التفويض في android.webkit.WebView.
على مطوّري البرامج استخدام مكتبات Android، مثل تسجيل الدخول بحساب Google لأجهزة Android أو AppAuth لأجهزة Android من مؤسسة OpenID.
قد يواجه مطوّرو البرامج على الويب هذا الخطأ عندما يفتح أحد تطبيقات Android رابط ويب عامًا في وكيل مستخدم مضمّنًا وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google على موقعك الإلكتروني. يجب أن يسمح مطوّرو البرامج باستخدام الروابط العامة بفتحها في معالج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالِجات روابط تطبيقات Android أو تطبيق المتصفّح التلقائي. وتُعدّ مكتبة علامات التبويب المخصّصة على Android أيضًا خيارًا متوافقًا.
iOS
قد يواجه مطوّرو تطبيقات iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في WKWebView.
على المطوّرين استخدام مكتبات iOS، مثل تسجيل الدخول بحساب Google لأجهزة iOS أو AppAuth لأجهزة iOS من مؤسسة OpenID.
قد يواجه مطوّرو البرامج على الويب هذا الخطأ عندما يفتح أحد تطبيقات iOS أو macOS رابط ويب عامًا في
وكيل مستخدم مضمّنًا وينتقل المستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google
من موقعك الإلكتروني. يجب أن يسمح مطوّرو البرامج بعدم فتح الروابط العامة في معالج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالِجات الروابط العامة أو تطبيق المتصفّح التلقائي. إتاحة مكتبة SFSafariViewController أيضًا.
org_internal
معرّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من الوصول إلى حسابات Google في مؤسسة Google Cloud محددة. لمزيد من المعلومات حول خيار الضبط هذا، يمكنك الاطّلاع على قسم نوع المستخدم في مقالة مساعدة إعداد شاشة موافقة OAuth.
invalid_client
المصدر الذي تم تقديم الطلب منه غير مصرَّح به لهذا العميل. يمكنك الاطّلاع على
origin_mismatch.
invalid_grant
عند استخدام التفويض المتزايد، قد تكون الرمز المميّز قد انتهت صلاحيته أو تم إبطاله. عليك مصادقة المستخدم مرة أخرى وطلب موافقة المستخدم للحصول على الرموز المميّزة الجديدة. إذا استمر ظهور هذا الخطأ، تأكّد من ضبط تطبيقك بشكل صحيح ومن استخدام الرموز المميّزة والمَعلمات الصحيحة في طلبك. وإلا، من المحتمل أنه تم حذف حساب المستخدم أو إيقافه.
origin_mismatch
قد لا يتطابق مخطط نطاق JavaScript و/أو نطاقه و/أو منفذه الذي ينشئه طلب التفويض مع معرّف الموارد المنتظم (URI) لمصدر JavaScript المصرّح به المسجّل لمعرّف عميل OAuth. يُرجى مراجعة مصادر JavaScript المسموح بها في Google API Console Credentials page.
redirect_uri_mismatch
لا يتطابق رمز redirect_uri الذي تم تمريره في طلب التفويض مع معرِّف الموارد المنتظم (URI) لإعادة التوجيه المعتمَد لمعرِّف عميل OAuth. يمكنك مراجعة معرِّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في Google API Console Credentials page.
قد لا يتطابق مخطط نطاق JavaScript و/أو نطاقه و/أو منفذه الذي ينشئه طلب التفويض مع معرّف الموارد المنتظم (URI) لمصدر JavaScript المصرّح به المسجّل لمعرّف عميل OAuth. يمكنك مراجعة مصادر JavaScript المسموح بها في Google API Console Credentials page.
قد تشير المعلَمة redirect_uri إلى تدفق بروتوكول OAuth (OOB) الذي تم إيقافه نهائيًا ولم يعد متاحًا. راجِع دليل نقل البيانات لتعديل عملية الدمج.
الخطوة 3: التعامل مع استجابة خادم OAuth 2.0
نقاط نهاية OAuth 2.0
يرسل خادم OAuth 2.0 استجابة إلى redirect_uri المحدّدة في طلب رمز الدخول.
إذا وافق المستخدم على الطلب، ستتضمّن الاستجابة رمز دخول. إذا لم يوافق المستخدم على الطلب، تحتوي الاستجابة على رسالة خطأ. يتم عرض رمز الدخول أو رسالة الخطأ على جزء التجزئة الخاص بمعرّف الموارد المنتظم (URI) لإعادة التوجيه، كما هو موضّح أدناه:
استجابة رمز الدخول:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
بالإضافة إلى المَعلمة
access_token، تحتوي سلسلة الأجزاء أيضًا على المَعلمةtoken_typeالتي يتم ضبطها دائمًا علىBearer، والمَعلمةexpires_inالتي تحدّد بالثواني قيمة الرمز المميّز. إذا تم تحديد المَعلمةstateفي طلب رمز الدخول، يتم أيضًا تضمين قيمتها في الاستجابة.- الردّ على الخطأ:
https://oauth2.example.com/callback#error=access_denied
نموذج استجابة خادم OAuth 2.0
ويمكنك اختبار هذا المسار بالنقر على نموذج عنوان URL التالي الذي يطلب الإذن بالقراءة فقط لعرض البيانات الوصفية للملفات في حسابك على Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
بعد إكمال مسار OAuth 2.0، ستتم إعادة توجيهك إلى
http://localhost/oauth2callback. سيؤدي عنوان URL هذا إلى عرض خطأ 404 NOT FOUND ما لم يعرض جهازك المحلي ملفًا على هذا العنوان. تقدم الخطوة التالية مزيدًا من التفاصيل حول المعلومات التي يتم عرضها في معرّف الموارد المنتظم (URI) عند إعادة توجيه المستخدم إلى تطبيقك.
طلب واجهات برمجة تطبيقات Google
نقاط نهاية OAuth 2.0
بعد أن يحصل تطبيقك على رمز الدخول، يمكنك استخدام الرمز المميّز لإجراء طلبات إلى واجهة برمجة تطبيقات Google بالنيابة عن حساب مستخدم معيّن إذا تم منح نطاقات الوصول المطلوبة من خلال واجهة برمجة التطبيقات. ولإجراء ذلك، يمكنك تضمين رمز الدخول في طلب لواجهة برمجة التطبيقات من خلال تضمين معلَمة طلب البحث access_token أو قيمة Authorization لعنوان HTTP Bearer. عندما يكون ذلك ممكنًا،
من الأفضل استخدام عنوان HTTP، لأن سلاسل طلبات البحث تظهر غالبًا في سجلّات الخادم. في معظم الحالات، يمكنك استخدام مكتبة برامج لإعداد طلباتك من Google APIs (على سبيل المثال، عند استدعاء Drive Files API).
يمكنك تجربة جميع واجهات Google API والاطّلاع على نطاقاتها في مساحة بروتوكول OAuth 2.0.
أمثلة على 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
نموذج رمز JavaScript
يوضح مقتطف الرمز أدناه كيفية استخدام CORS (مشاركة الموارد المشتركة النطاق) لإرسال طلب إلى Google API. ولا يستخدم هذا المثال مكتبة برامج Google APIs للغة JavaScript. ومع ذلك، حتى إذا لم تكن تستخدم "مكتبة العملاء"، يمكن أن يساعدك دليل دعم سياسة مشاركة الموارد متعددة المصادر (CORS) في مستندات تلك المكتبة على فهم هذه الطلبات بشكل أفضل.
في مقتطف الرمز هذا، يمثّل المتغيّر access_token الرمز المميّز الذي حصلت عليه
لإرسال طلبات البيانات من واجهة برمجة التطبيقات بالنيابة عن المستخدم المفوَّض. يوضّح المثال الكامل كيفية تخزين هذا الرمز المميّز في مساحة التخزين المحلية للمتصفّح واسترداده عند تقديم طلب للحصول على واجهة برمجة تطبيقات.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
console.log(xhr.response);
};
xhr.send(null);
مثال كامل
نقاط نهاية OAuth 2.0
يوضح هذا الرمز البرمجي كيفية إكمال تدفق OAuth 2.0 في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. الرمز مخصّص لصفحة HTML تعرض زرًا لتجربة طلب بيانات من واجهة برمجة التطبيقات. إذا نقرت على الزر، سيتحقّق الرمز لمعرفة ما إذا كانت الصفحة قد خزّنت رمز دخول لواجهة برمجة التطبيقات في مساحة التخزين المحلية على المتصفّح. وفي هذه الحالة، يتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات. وبخلاف ذلك، يبدأ تدفق OAuth 2.0.
بالنسبة إلى مسار OAuth 2.0، تتّبع الصفحة الخطوات التالية:
- يوجّه المستخدم إلى خادم OAuth 2.0 من Google، والذي يطلب الوصول إلى نطاق
https://www.googleapis.com/auth/drive.metadata.readonly. - بعد منح (أو رفض) الوصول إلى نطاق واحد أو أكثر من النطاقات المطلوبة، تتم إعادة توجيه المستخدم إلى الصفحة الأصلية التي تحلل رمز الدخول من سلسلة معرّف الجزء.
تستخدم الصفحة رمز الدخول المميز لتقديم نموذج طلب بيانات من واجهة برمجة التطبيقات.
يطلب طلب البيانات من واجهة برمجة التطبيقات طريقة
about.getفي Drive API لاسترداد معلومات حول حساب Google Drive للمستخدم المعتمد.- إذا تم تنفيذ الطلب بنجاح، يتم تسجيل استجابة واجهة برمجة التطبيقات في وحدة تحكّم تصحيح الأخطاء الخاصة بالمتصفِّح.
يمكنك إبطال إمكانية الوصول إلى التطبيق من خلال صفحة الأذونات لحسابك على Google. سيتم إدراج التطبيق بصفته إصدار OAuth 2.0 التجريبي لمستندات Google API.
لتشغيل هذا الرمز محليًا، يجب ضبط القيم لمتغيّرَي YOUR_CLIENT_ID وYOUR_REDIRECT_URI التي تتوافق مع بيانات اعتماد التفويض. يجب ضبط المتغيّر YOUR_REDIRECT_URI على عنوان URL نفسه الذي يتم عرض الصفحة عليه. ويجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المُعتمَدة لإعادة التوجيه لعميل OAuth 2.0، الذي ضبطته في API Console Credentials page. وإذا لم تتطابق هذه القيمة مع معرّف الموارد المنتظم (URI) مفوّض، سيظهر لك الخطأ redirect_uri_mismatch. ويجب أيضًا تفعيل واجهة برمجة التطبيقات المناسبة للمشروع.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
var fragmentString = location.hash.substring(1);
// Parse query string to see if page request is coming from OAuth 2.0 server.
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
if (params['state'] && params['state'] == 'try_sample_request') {
trySampleRequest();
}
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
'state': 'try_sample_request',
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>
قواعد التحقّق من صحة مصدر JavaScript
تُطبِّق Google قواعد التحقّق التالية على مصادر JavaScript لمساعدة المطوّرين في الحفاظ على أمان تطبيقاتهم. يجب أن تلتزم مصادر JavaScript بهذه القواعد. راجِع قسم RFC 3986 للتعرّف على تعريف النطاق والمضيف والمخطط المذكور أدناه.
| قواعد التحقّق | |
|---|---|
| مخطط |
ويجب أن تستخدم مصادر JavaScript نظام HTTPS، وليس نظام HTTP عادي. يتم إعفاء معرّفات الموارد المنتظمة (URI) للمضيف المحلي (بما في ذلك معرّفات الموارد المنتظمة (URI) لعناوين المضيف المحلي) من هذه القاعدة. |
| المضيف |
لا يمكن أن يكون المضيفون عناوين IP أولية. يتم إعفاء عناوين IP للمضيف المحلي من هذه القاعدة. |
| النطاق |
“googleusercontent.com”.goo.gl)
إلا إذا كان التطبيق يمتلك النطاق. |
| معلومات المستخدم |
لا يمكن أن تحتوي مصادر JavaScript على المكوّن الفرعي userinfo. |
| المسار |
لا يمكن أن تحتوي مصادر JavaScript على مكوّن المسار. |
| طلب بحث |
لا يمكن أن تحتوي مصادر JavaScript على مكوّن طلب البحث. |
| Fragment |
لا يمكن أن تحتوي مصادر JavaScript على مكوّن الجزء. |
| الأحرف |
لا يمكن أن تحتوي مصادر JavaScript على أحرف معيّنة تشمل:
|
التفويض المتزايد
في بروتوكول OAuth 2.0، يطلب تطبيقك تفويضًا للوصول إلى الموارد التي يتم تحديدها من خلال النطاقات. إنّ طلب الحصول على إذن للموارد في الوقت الذي تحتاج إليه هو من أفضل الممارسات التي يتّبعها المستخدم، لتفعيل هذه الممارسة، يتيح خادم التفويض في Google التفويض المتزايد. تتيح لك هذه الميزة طلب نطاقات حسب الحاجة. وإذا منح المستخدم الإذن للنطاق الجديد، يعرض رمز تفويض يمكن استبداله برمز مميّز يحتوي على جميع النطاقات التي منحها المستخدم للمشروع.
على سبيل المثال، قد يحتاج التطبيق الذي يتيح للمستخدمين استخدام عيّنات من المقاطع الموسيقية وإنشاء تشكيلات موسيقية عددًا قليلاً جدًا من الموارد عند تسجيل الدخول، وقد لا يكون سوى اسم الشخص الذي يسجّل الدخول. ومع ذلك، يتطلب حفظ تشكيلة مختلطة الوصول إلى ملفها على Google Drive. يجد معظم المستخدمين أنّه من الطبيعي أن يُطلب منهم الوصول إلى Google Drive في الوقت الذي احتاجوا فيه إلى التطبيق فقط.
في هذه الحالة، عندما يطلب التطبيق تسجيل الدخول، قد يطلب من النطاقَين openid وprofile تنفيذ عملية تسجيل الدخول الأساسية، ثم يطلب بعد ذلك استخدام النطاق https://www.googleapis.com/auth/drive.file في وقت الطلب الأول لحفظ تشكيلة.
تنطبق القواعد التالية على رمز الدخول الذي تم الحصول عليه من تفويض متزايد:
- يمكن استخدام الرمز المميّز للوصول إلى الموارد المقابلة لأي من النطاقات المجمّعة في التفويض الجديد والمجمّع.
- عندما تستخدم رمز الدخول المميّز للتفويض المجمّع للحصول على رمز دخول، يمثّل رمز الدخول التفويض المجمّع ويمكن استخدامه لأيٍّ من قيم
scopeالمضمّنة في الاستجابة. - يتضمّن التفويض المُجمَّع جميع النطاقات التي منحها المستخدم لمشروع واجهة برمجة التطبيقات حتى إذا تم طلب مِنح من عملاء مختلفين. على سبيل المثال، إذا منَح مستخدم إذن وصول إلى نطاق واحد باستخدام برنامج متوافق مع أجهزة سطح المكتب، ثم منح مستخدمًا نطاقًا آخر للتطبيق نفسه عبر برنامج متوافق مع الأجهزة الجوّالة، سيشمل التفويض المُجمَّع كلا النطاقين.
- إذا أبطلت رمزًا مميزًا يمثّل تفويضًا مجمّعًا، سيتم إبطال إذن الوصول إلى جميع نطاقات هذا التفويض نيابةً عن المستخدم المرتبط في الوقت نفسه.
تعرض نماذج الرموز أدناه كيفية إضافة النطاقات إلى رمز دخول حالي. ويسمح هذا الأسلوب لتطبيقك بتجنُّب إدارة عدة رموز دخول.
نقاط نهاية OAuth 2.0
لإضافة نطاقات إلى رمز دخول حالي، يمكنك تضمين المَعلمة include_granted_scopes في طلبك إلى خادم OAuth 2.0 في Google.
ويوضّح مقتطف الرمز التالي كيفية إجراء ذلك. يفترض المقتطف أنك خزّنت النطاقات التي يكون رمز الدخول صالحًا لها في مساحة التخزين المحلية للمتصفّح. (يخزّن الرمز مثال كامل قائمة بالنطاقات التي يكون رمز الدخول صالحًا من خلال ضبط السمة oauth2-test-params.scope في مساحة التخزين المحلية على المتصفّح).
يقارن المقتطف بين النطاقات التي يكون رمز الدخول صالحًا للنطاق الذي تريد استخدامه لطلب بحث معيّن. إذا لم يغطي رمز الدخول هذا النطاق، ستبدأ مسار OAuth 2.0.
هنا، تكون الدالة oauth2SignIn هي نفسها التي تم توفيرها في
الخطوة 2 (والتي تم توفيرها لاحقًا في المثال الكامل).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
var scopes = params['scope'].split(' ');
for (var s = 0; s < scopes.length; s++) {
if (SCOPE == scopes[s]) {
current_scope_granted = true;
}
}
}
if (!current_scope_granted) {
oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
// Since you already have access, you can proceed with the API request.
}
إبطال رمز مميز
في بعض الحالات، قد يريد المستخدم إبطال إمكانية الوصول التي تم منحها إلى أحد التطبيقات. يمكن للمستخدم إبطال إمكانية الوصول من خلال الانتقال إلى إعدادات الحساب. يُرجى الاطّلاع على مستند دعم إزالة المواقع الإلكترونية أو التطبيقات من المواقع الإلكترونية والتطبيقات التابعة لجهات خارجية والتي يمكنها الوصول إلى حسابك للحصول على مزيد من المعلومات.
ويمكن أيضًا لأحد التطبيقات إبطال حق الوصول الذي تم منحه له آليًا. ويُعدّ الإلغاء الآلي مهمًا في الحالات التي يلغي فيها المستخدم الاشتراك أو يزيل تطبيقًا أو تتغير موارد واجهة برمجة التطبيقات التي يطلبها التطبيق بشكل كبير. بعبارة أخرى، يمكن أن يتضمّن جزء من عملية الإزالة طلب واجهة برمجة التطبيقات لضمان إزالة الأذونات التي تم منحها في السابق للتطبيق.
نقاط نهاية OAuth 2.0
لإبطال رمز مميّز آليًا، يقدّم تطبيقك طلبًا إلى
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 مع
رمز خطأ.
يعرض مقتطف JavaScript التالي كيفية إبطال رمز مميّز في JavaScript بدون استخدام مكتبة برامج Google APIs للغة JavaScript. بما أنّ نقطة نهاية OAuth 2.0 من Google لإبطال الرموز المميَّزة
غير متوافقة مع ميزة مشاركة الموارد المتعدّدة المصادر (CORS)، تنشئ الرمز نموذجًا وترسل
النموذج إلى نقطة النهاية بدلاً من استخدام طريقة XMLHttpRequest() لنشر
الطلب.
function revokeAccess(accessToken) {
// Google's OAuth 2.0 endpoint for revoking access tokens.
var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
// Create <form> element to use to POST data to the OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'post');
form.setAttribute('action', revokeTokenEndpoint);
// Add access token to the form so it is set as value of 'token' parameter.
// This corresponds to the sample curl request, where the URL is:
// https://oauth2.googleapis.com/revoke?token={token}
var tokenField = document.createElement('input');
tokenField.setAttribute('type', 'hidden');
tokenField.setAttribute('name', 'token');
tokenField.setAttribute('value', accessToken);
form.appendChild(tokenField);
// Add form to page and submit it to actually revoke the token.
document.body.appendChild(form);
form.submit();
}