تستخدم بروتوكولات مصادقة الويب ميزات HTTP، إلا أن تطبيقات Chrome تعمل داخل حاوية التطبيق، ولا يتم تحميلها عبر HTTP ولا يمكنها إجراء عمليات إعادة توجيه أو ضبط ملفات تعريف الارتباط.
استخدم Chrome Identity API لمصادقة المستخدمين: getAuthToken للمستخدمين الذين سجّلوا الدخول إلى حساباتهم على Google وlaunchWebAuthFlow للمستخدمين الذين سجَّلوا الدخول إلى حساب غير تابع لشركة Google. إذا كان تطبيقك يستخدم خادمه الخاص لمصادقة المستخدمين، عليك استخدام التطبيق الثاني.
آلية العمل
لدى مستخدمي تطبيقات Chrome حساب Google مرتبط بملفاتهم الشخصية. يمكن للتطبيقات الحصول على رموز OAuth2
الخاصة بهؤلاء المستخدمين باستخدام واجهة برمجة التطبيقات getAuthToken API.
على التطبيقات التي تريد إجراء مصادقة باستخدام موفّري هوية غير تابعين لشركة Google الاتصال بالرقم
launchWebAuthFlow. تستخدم هذه الطريقة نافذة منبثقة في المتصفح لعرض صفحات الموفر وتلتقط عمليات إعادة التوجيه إلى أنماط عناوين URL المحددة. يتم تمرير عناوين URL لإعادة التوجيه إلى التطبيق ويستخرج التطبيق الرمز المميز من عنوان URL.
مصادقة حساب Google
في ما يلي الخطوات الخمس التي عليك إكمالها:
- عليك إضافة الأذونات إلى ملف البيان وتحميل تطبيقك.
- انسخ المفتاح في
manifest.jsonالمثبَّت إلى بيان المصدر، بحيث يظل رقم تعريف التطبيق ثابتًا أثناء التطوير. - احصل على معرِّف عميل OAuth2 لتطبيق Chrome.
- يُرجى تعديل ملف البيان لتضمين معرِّف العميل والنطاقات.
- احصل على الرمز المميّز للمصادقة.
إضافة الأذونات وتحميل التطبيق
عليك التأكّد من أنّ إذن الهوية في ملف البيان. يمكنك بعد ذلك تحميل تطبيقك إلى صفحة إدارة التطبيقات والإضافات (راجِع نشر).
"permissions": [
"identity"
]
نسخ المفتاح إلى البيان
عند تسجيل تطبيقك في وحدة تحكم Google OAuth، ستقدِّم معرف التطبيق الذي سيتم التحقق منه أثناء طلبات الرمز المميز. لذلك من المهم أن يكون لديك معرّف تطبيق متسق أثناء عملية التطوير.
للحفاظ على ثبات معرّف التطبيق، عليك نسخ المفتاح في manifest.json المثبَّت إلى
بيان المصدر. إنها ليست المهمة الأكثر رشاقة، ولكن إليك كيفية سيرها:
- انتقِل إلى دليل بيانات المستخدم. مثال على أجهزة MacO:
~/Library/Application\ Support/Google/Chrome/Default/Extensions - أدرج التطبيقات والإضافات المثبتة وطابق رقم تعريف تطبيقك على صفحة إدارة التطبيقات والإضافات برقم التعريف نفسه هنا.
- انتقِل إلى دليل التطبيق المثبَّت (الذي سيكون إصدارًا ضمن رقم تعريف التطبيق). افتح ملف
manifest.jsonالمثبَّت (pico هي طريقة سريعة لفتح الملف). - انسخ "المفتاح" في
manifest.jsonالمثبَّت والصقه في ملف بيان مصدر التطبيق.
الحصول على معرِّف عميل OAuth2
يجب تسجيل تطبيقك في وحدة تحكُّم Google APIs للحصول على معرِّف العميل:
- سجِّل الدخول إلى وحدة تحكم Google APIs باستخدام حساب Google نفسه المستخدَم لتحميل تطبيقك إلى "سوق Chrome الإلكتروني".
- يمكنك إنشاء مشروع جديد عن طريق توسيع القائمة المنسدلة في أعلى اليمين وتحديد عنصر القائمة إنشاء....
- بعد إنشاء التطبيق وتسميته، انتقل إلى عنصر قائمة التنقل "الخدمات" وشغِّل أي من خدمات Google التي يحتاجها تطبيقك.
- انتقِل إلى عنصر قائمة التنقّل "الوصول إلى واجهة برمجة التطبيقات" وانقر على الزر الأزرق إنشاء معرِّف عميل OAuth 2.0....
- أدخِل معلومات العلامة التجارية المطلوبة، واختَر النوع تطبيق مثبّت.
- اختَر تطبيق Chrome وأدخِل معرّف التطبيق (رقم التعريف نفسه المعروض في صفحة إدارة التطبيقات والإضافات).
تعديل البيان باستخدام معرِّف عميل OAuth2 ونطاقاته
يجب تعديل ملف البيان لتضمين معرِّف العميل والنطاقات. في ما يلي نموذج "oauth2" لنموذج gdrive:
"oauth2": {
"client_id": "665859454684.apps.googleusercontent.com",
"scopes": [
"https://www.googleapis.com/auth/drive"
]
}
الحصول على رموز الدخول
أصبحت جاهزًا الآن للحصول على الرمز المميّز للمصادقة من خلال طلب identity.getAuthToken.
chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
// Use the token.
});
تفاعل المستخدم
عند استدعاء الرقم getAuthToken، يمكنك وضع علامة ('interactive': true في المثال أعلاه) تشير إلى ما إذا كنت تريد استخدام واجهة برمجة التطبيقات في الوضع التفاعلي أو الوضع الصامت. إذا استدعيت واجهة برمجة التطبيقات في الوضع التفاعلي، ستظهر للمستخدم واجهة مستخدم لتسجيل الدخول و/أو الموافقة عند الضرورة، كما هو موضّح في لقطة الشاشة أدناه:
إذا استدعت واجهة برمجة التطبيقات في الوضع الصامت، لن تعرض واجهة برمجة التطبيقات رمزًا مميزًا إلا إذا كان من الممكن إنتاج رمز بدون عرض أي رمز مميّز. ويكون هذا مفيدًا في الحالات التي يبدأ فيها التطبيق عند بدء تشغيله، على سبيل المثال، أو بشكل عام في الحالات التي لا تتضمّن فيها إيماءة المستخدم.
من أفضل الممارسات التي ننصح بها هي استخدام الوضع الصامت عندما لا تكون هناك إيماءة مستخدم، واستخدام الوضع التفاعلي إذا كانت هناك إيماءة مستخدم (على سبيل المثال، نقر المستخدم على زر "تسجيل الدخول" في تطبيقك). يُرجى العِلم أنّنا لا نفرض أي متطلبات مرتبطة بالإيماءات.
التخزين المؤقت
يتضمّن Chrome ذاكرة تخزين مؤقت في الذاكرة تحتوي على رموز الدخول، وبالتالي يمكنك طلب رمز الدخول getAuthToken في أي وقت تحتاج فيه إلى
استخدام رمز مميّز. تتم معالجة انتهاء صلاحية الرمز المميز تلقائيًا من خلال ذاكرة التخزين المؤقت.
يمكنك الاطّلاع على الحالة الحالية لذاكرة التخزين المؤقت للرمز المميّز على الرابط chrome://identity-internals.
هناك بعض الحالات، مثل تغيير المستخدم لكلمة المرور التي تتوقف فيها رموز الدخول غير المنتهية الصلاحية عن العمل. ستبدأ طلبات البيانات من واجهة برمجة التطبيقات التي تستخدم الرمز المميز برمز حالة HTTP 401. إذا اكتشفت حدوث ذلك، يمكنك إزالة الرمز المميز غير الصالح من ذاكرة التخزين المؤقت في Chrome عن طريق استدعاء identity.removeCachedAuthToken.
مثال على استخدام ميزة "removeCachedAuthToken":
// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
var retry = true;
function getTokenAndXhr() {
chrome.identity.getAuthToken({/* details */},
function (access_token) {
if (chrome.runtime.lastError) {
callback(chrome.runtime.lastError);
return;
}
var xhr = new XMLHttpRequest();
xhr.open(method, url);
xhr.setRequestHeader('Authorization',
'Bearer ' + access_token);
xhr.onload = function () {
if (this.status === 401 && retry) {
// This status may indicate that the cached
// access token was invalid. Retry once with
// a fresh token.
retry = false;
chrome.identity.removeCachedAuthToken(
{ 'token': access_token },
getTokenAndXhr);
return;
}
callback(null, this.status, this.responseText);
}
});
}
}
مصادقة حسابات غير تابعة لشركة Google
في ما يلي الخطوات الثلاث التي يجب إكمالها:
- التسجيل لدى مقدّم الخدمة
- أضِف أذونات لموارد الموفّرين التي سيتمكن تطبيقك من الوصول إليها.
- احصل على الرمز المميّز للمصادقة.
التسجيل لدى مقدّم الخدمة
يجب تسجيل معرِّف عميل OAuth2 مع مقدِّم الخدمة وضبط معرِّف العميل كموقع إلكتروني.
لإدخال معرّف الموارد المنتظم (URI) لإعادة التوجيه أثناء التسجيل، استخدِم عنوان URL الخاص بالنموذج:
https://<extension-id>.chromiumapp.org/<anything-here>
على سبيل المثال، إذا كان رقم تعريف التطبيق هو abcdefghijklmnopqrstuvwxyzabcdef وأردت أن يكون provider_cb هو المسار، يجب استخدام ما يلي لتمييزه عن طريق معرّفات الموارد المنتظمة (URI) لإعادة التوجيه من مزوّدي الخدمات الآخرين: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb
إضافة أذونات للموفّر
لإرسال طلبات XHR متعددة المصادر إلى نقاط نهاية واجهة برمجة التطبيقات الخاصة بالموفِّر، عليك إضافة الأنماط المناسبة في الأذونات إلى القائمة المسموح بها:
"permissions": [
...
"https://www.website-of-provider-with-user-photos.com/photos/*"
]
الحصول على الرمز المميّز
للحصول على الرمز المميّز، يُرجى اتّباع الخطوات التالية:
chrome.identity.launchWebAuthFlow(
{'url': '<url-to-do-auth>', 'interactive': true},
function(redirect_url) { /* Extract token from redirect_url */ });
إنّ <url-to-do-auth> هو أي عنوان URL يهدف إلى المصادقة على مقدّم الخدمة من موقع إلكتروني. على سبيل المثال،
لنفترض أنك تنفّذ مسار OAuth2 مع أحد موفّري الخدمات وسجّلت تطبيقك بمعرّف العميل 123456789012345 وتريد الوصول إلى صور المستخدم على الموقع الإلكتروني لمقدّم الخدمة:
https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos
سيُجري مقدّم الخدمة عملية المصادقة، وإذا كان ذلك مناسبًا، سيعرض واجهة المستخدم الخاصة بتسجيل الدخول و/أو الموافقة. ستتم إعادة التوجيه بعد ذلك إلى
https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>.
سيسجّل Chrome ذلك ويستدعي معاودة الاتصال بالتطبيق باستخدام عنوان URL الكامل لإعادة التوجيه. يجب على التطبيق استخراج الرمز المميّز من عنوان URL.
الوضع التفاعلي مقابل الوضع الصامت
عند استدعاء launchWebAuthFlow، يمكنك وضع علامة ('interactive': true في المثال أعلاه) تشير إلى ما إذا كنت تريد طلب واجهة برمجة التطبيقات في الوضع التفاعلي أم لا (المعروف أيضًا بالوضع الصامت). إذا استدعيت واجهة برمجة التطبيقات في الوضع التفاعلي، سيظهر للمستخدم واجهة المستخدم، إذا لزم الأمر، للحصول على الرمز المميز (واجهة مستخدم تسجيل الدخول و/أو واجهة مستخدم الموافقة، أو أي واجهة مستخدم خاصة بموفِّر خدمة في هذا الشأن).
في حال استدعاء واجهة برمجة التطبيقات في الوضع الصامت، لن تعرض واجهة برمجة التطبيقات رمزًا مميزًا إلا إذا تمكّن موفّر الخدمة من توفير رمز مميّز بدون عرض أي واجهة مستخدم. ويكون هذا مفيدًا في الحالات التي يقوم فيها التطبيق بالتدفق عند بدء تشغيل التطبيق مثلاً، أو بشكل عام في الحالات التي لا تتضمّن فيها إيماءة المستخدم.
من أفضل الممارسات التي ننصح بها هي استخدام الوضع الصامت عندما لا تكون هناك إيماءة مستخدم، واستخدام الوضع التفاعلي إذا كانت هناك إيماءة مستخدم (على سبيل المثال، نقر المستخدم على زر "تسجيل الدخول" في تطبيقك). يُرجى العِلم أنّنا لا نفرض شرط الإيماءات.