يشرح هذا المستند طريقة تنفيذ تفويض 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
إذا كنت تستخدم مكتبة برامج Google APIs لـ JavaScript لإجراء استدعاءات مصرّح بها إلى Google، عليك استخدام مكتبة JavaScript لخدمات Google Identity Services للتعامل مع تدفق 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.
الحصول على رموز الدخول عبر 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 |
مطلوب
معرِّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في Credentials page API Console. |
||||||
redirect_uri |
مطلوب
تحدد هذه السمة المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد أن يُكمل المستخدم
عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه لعميل OAuth 2.0، والتي تم ضبطها في API Console
Credentials pageللبرنامج. وإذا لم تتطابق هذه القيمة مع
معرّف الموارد المنتظم (URI) الموافَق عليه لإعادة التوجيه للسمة يجب أن يتطابق المخطط |
||||||
response_type |
مطلوب
تحتاج تطبيقات JavaScript إلى ضبط قيمة المَعلمة على |
||||||
scope |
مطلوب
تمثّل هذه السمة قائمة النطاقات المفصولة بمسافات والتي تحدّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم. وتحدِّد هذه القيم شاشة طلب الموافقة التي يعرضها محرّك بحث Google للمستخدم. وتمكّن النطاقات تطبيقك من طلب الوصول إلى الموارد التي يحتاجها فقط، مع السماح للمستخدمين في الوقت نفسه بالتحكم في مستوى الوصول الذي يمنحونه لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمال الحصول على موافقة المستخدم. ننصحك بأن يطلب تطبيقك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. إنّ طلب الوصول إلى بيانات المستخدمين في السياق المناسب من خلال التفويض الإضافي يساعد المستخدمين على فهم سبب حاجة تطبيقك للوصول إلى البيانات التي يطلبها بسهولة أكبر. |
||||||
state |
سمة مقترَحة
يحدّد هذا الحقل أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض.
يعرض الخادم القيمة الدقيقة التي ترسلها كزوج يمكنك استخدام هذه المَعلمة لأغراض متعدّدة، مثل توجيه المستخدم إلى
المورد الصحيح في تطبيقك، وإرسال أرقام خاصة، والحدّ من عمليات تزوير الطلبات من مواقع إلكترونية متعددة. بما أنّه يمكن تخمين |
||||||
include_granted_scopes |
اختياريّ
للسماح للتطبيقات باستخدام التفويض المتزايد لطلب الوصول إلى نطاقات إضافية في السياق. إذا ضبطت قيمة هذه المَعلمة على |
||||||
enable_granular_consent |
اختياريّ
يكون الإعداد التلقائي هو |
||||||
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 for Android من OpenID Foundation.
قد يظهر هذا الخطأ لمطوّري البرامج على الويب عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل مستخدم إلى نقطة نهاية تفويض OAuth 2.0 من Google من موقعك الإلكتروني. على المطوّرين أن يسمحوا بفتح الروابط العامة في معالِج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالِجات Android App Links أو تطبيق المتصفّح التلقائي. ويمكن أيضًا استخدام مكتبة علامات تبويب Android المخصّصة.
iOS
قد يظهر هذا الخطأ لمطوّري تطبيقات iOS وmacOS عند فتح طلبات التفويض في WKWebView.
على المطوّرين بدلاً من ذلك استخدام مكتبات iOS، مثل Google Sign-In for iOS أو AppAuth for iOS من OpenID Foundation.
قد يظهر هذا الخطأ لمطوّري البرامج على الويب عندما يفتح أحد تطبيقات 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) الذي
تم إيقافه نهائيًا ولم يعُد متوافقًا. يُرجى مراجعة
دليل نقل البيانات لتعديل
عملية الدمج.
invalid_request
حدث خطأ في الطلب الذي قدّمته. قد يرجع ذلك إلى عدة أسباب:
- لم يتم تنسيق الطلب بشكلٍ صحيح
- كان الطلب يفتقد إلى المَعلمات المطلوبة
- يستخدم الطلب طريقة تفويض لا تعتمدها Google. التحقّق من أنّ عملية دمج OAuth تستخدم طريقة دمج مُقترَحة
الخطوة 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 APIs
نقاط نهاية OAuth 2.0
بعد أن يحصل تطبيقك على رمز دخول، يمكنك استخدامه لإجراء استدعاءات لواجهة برمجة تطبيقات Google بالنيابة عن حساب مستخدم معيَّن إذا تم منح نطاقات الوصول التي تطلبها واجهة برمجة التطبيقات. لإجراء ذلك، يمكنك تضمين
رمز الدخول في طلب لواجهة برمجة التطبيقات من خلال تضمين مَعلمة طلب بحث access_token
أو قيمة Bearer لعنوان HTTP Authorization. ويفضَّل استخدام عنوان HTTP عندما يكون ذلك ممكنًا، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. وفي معظم
الحالات، يمكنك استخدام مكتبة برامج لإعداد طلبات البيانات من Google APIs (على سبيل المثال، عند
طلب البيانات من Drive Files API).
يمكنك تجربة جميع واجهات برمجة تطبيقات Google وعرض نطاقاتها في ملعب 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. لا يستخدم هذا المثال مكتبة برامج 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 بهذه القواعد. راجِع القسم 3 من RFC 3986 للتعرّف على تعريف النطاق والمضيف والمخطط المذكورة أدناه.
| قواعد التحقّق من الصحة | |
|---|---|
| المخطط |
يجب أن تستخدم مصادر JavaScript المخطط HTTPS، وليس HTTP عاديًا. يتم استثناء معرّفات الموارد المنتظمة (URI) للمضيف المحلي (بما في ذلك معرّفات الموارد المنتظمة (URI) لعناوين IP للمضيف المحلي) من هذه القاعدة. |
| المضيف |
لا يمكن للمضيفين أن يكونوا عناوين IP أولية. تُستثنى عناوين IP للمضيف المحلي من هذه القاعدة. |
| النطاق |
“googleusercontent.com”.goo.gl)
ما لم يكن التطبيق يملك النطاق. |
| معلومات المستخدم |
لا يمكن أن تحتوي أصول JavaScript على المكوِّن الفرعي userinfo. |
| المسار |
لا يمكن أن تحتوي أصول JavaScript على مكوّن المسار. |
| طلب بحث |
لا يمكن أن تحتوي أصول JavaScript على مكوّن طلب البحث. |
| جزء |
لا يمكن أن تحتوي أصول 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();
}