פרוטוקולים לאימות אינטרנט משתמשים בתכונות HTTP, אבל אפליקציות Chrome פועלות בתוך מאגר האפליקציות. הן לא נטענות ב-HTTP ולא יכולות לבצע הפניות אוטומטיות או להגדיר קובצי cookie.
שימוש ב-Chrome Identity API כדי לאמת משתמשים: getAuthToken עבור משתמשים שמחוברים לחשבון Google שלהם ו-launchWebAuthFlow עבור משתמשים שמחוברים לחשבון שאינו Google. אם האפליקציה משתמשת בשרת משלה לאימות המשתמשים, תצטרכו להשתמש בשרת שלה.
איך זה עובד
למשתמשי Chrome Apps יש חשבון Google המשויך לפרופיל שלהם. אפליקציות יכולות לקבל אסימוני OAuth2 עבור המשתמשים האלה באמצעות ה-API של getAuthToken.
אפליקציות שרוצות לבצע אימות באמצעות ספקי זהויות שאינם של Google חייבות להפעיל את
launchWebAuthFlow. בשיטה הזו נעשה שימוש בחלון קופץ בדפדפן כדי להציג את דפי הספק, ומתעדת הפניות אוטומטיות לתבניות ה-URL הספציפיות. כתובות ה-URL להפניה אוטומטית מועברות לאפליקציה, והאפליקציה שולפת את האסימון מכתובת ה-URL.
אימות חשבון Google
אלה חמשת השלבים שעליך להשלים:
- צריך להוסיף הרשאות למניפסט ולהעלות את האפליקציה.
- צריך להעתיק את המפתח שבקובץ
manifest.jsonהמותקן אל מניפסט המקור, כדי שמזהה האפליקציה יישאר קבוע במהלך הפיתוח. - קבלת מזהה לקוח OAuth2 עבור אפליקציית Chrome שלך.
- צריך לעדכן את המניפסט כך שיכלול את מזהה הלקוח ואת ההיקפים.
- קבלת אסימון האימות.
הוספת הרשאות והעלאת אפליקציה
עליך לוודא שהרשאת הזהות נמצאת במניפסט שלך. לאחר מכן תוכלו להעלות את האפליקציה לדף ניהול האפליקציות והתוספים (עיינו בפרסום).
"permissions": [
"identity"
]
העתקת המפתח למניפסט
כשרושמים את האפליקציה במסוף OAuth של Google, צריך לספק את מזהה האפליקציה, והוא ייבדק במהלך בקשות לאסימונים. לכן חשוב שיהיה לכם מזהה אפליקציה עקבי במהלך הפיתוח.
כדי שמזהה האפליקציה יישאר קבוע, צריך להעתיק את המפתח שבקובץ manifest.json המותקן למניפסט המקור. זו לא המשימה הכי חיננית, אבל ככה זה עובד:
- נכנסים לספריית נתוני המשתמשים. דוגמה ב-MacO:
~/Library/Application\ Support/Google/Chrome/Default/Extensions - יש לרשום את האפליקציות והתוספים שהותקנו ולהתאים את מזהה האפליקציה בדף ניהול האפליקציות והתוספים לאותו מזהה שמופיע כאן.
- עוברים לספריית האפליקציות המותקנות (זו תהיה גרסה במזהה האפליקציה). פותחים את
manifest.jsonהמותקן (דרך Pico אפשר לפתוח את הקובץ במהירות). - מעתיקים את ה'מפתח' מקובץ
manifest.jsonשמותקן ומדביקים אותו בקובץ המניפסט של האפליקציה.
קבלת מזהה הלקוח ב-OAuth2
עליך לרשום את האפליקציה ב-Google APIs Console כדי לקבל את מזהה הלקוח:
- מתחברים אל Google APIs Console באמצעות אותו חשבון Google ששימש להעלאת האפליקציה לחנות האינטרנט של Chrome.
- כדי ליצור פרויקט חדש, צריך להרחיב את התפריט הנפתח בפינה הימנית העליונה ולבחור באפשרות יצירה... בתפריט.
- אחרי שיוצרים את ההגדרה ומעניקים לה שם, נכנסים לתפריט הניווט 'Services' ומפעילים את כל שירותי Google שדרושים לאפליקציה.
- עוברים לתפריט הניווט 'API Access' (גישה ל-API) ולוחצים על הלחצן הכחול Create an OAuth 2.0 client ID... (יצירת מזהה לקוח OAuth 2.0).
- מזינים את פרטי המיתוג המבוקשים ובוחרים בסוג האפליקציה מותקנת.
- בוחרים באפשרות Chrome Application ומזינים את מזהה האפליקציה (אותו מזהה שמוצג בדף הניהול של האפליקציות והתוספים).
עדכון המניפסט באמצעות מזהה לקוח והיקפים של 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 בדוגמה שלמעלה) שמציין אם רוצים להפעיל את ה-API במצב אינטראקטיבי או במצב שקט. אם מפעילים את ה-API במצב אינטראקטיבי, למשתמש מוצג ממשק משתמש לכניסה ו/או אישור במידת הצורך, כפי שאפשר לראות בצילום המסך הבא:
כשמפעילים את ה-API במצב שקט, ה-API יחזיר אסימון רק אם אפשר ליצור אסימון כזה בלי להציג ממשק משתמש כלשהו. האפשרות הזו שימושית במקרים שבהם האפליקציה מבצעת את התהליך בזמן ההפעלה של האפליקציה, למשל, או באופן כללי כשלא נדרשת תנועת משתמש.
השיטה המומלצת היא להשתמש במצב שקט כאשר לא נדרשת תנועת משתמש, ולהשתמש במצב אינטראקטיבי אם מדובר בתנועה ממשתמש (לדוגמה, אם המשתמש לחץ על הלחצן כניסה באפליקציה). שימו לב שאנחנו לא אוכפים אף דרישה לביצוע תנועות.
הופך לקובץ שמור
ב-Chrome יש מטמון של אסימוני גישה בזיכרון, כך שאפשר לקרוא ל-getAuthToken בכל פעם שצריך להשתמש באסימון. תוקף התפוגה של האסימון מטופל באופן אוטומטי במטמון.
ניתן לראות את המצב הנוכחי של מטמון האסימון ב-chrome://identity-internals.
יש מקרים מסוימים, למשל כשהמשתמש משנה את הסיסמה, שבו אסימוני גישה תקפים יפסיקו לפעול. קריאות ל-API שמשתמשות באסימון יתחילו לחזור עם קוד מצב 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 ממקורות שונים לנקודות הקצה של ה-API של הספק, צריך להוסיף לרשימת ההיתרים את הדפוסים המתאימים בהרשאות:
"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 יתעד זאת ויפעיל קריאה חוזרת (callback) של האפליקציה עם כתובת האתר המלאה להפניה מחדש. האפליקציה צריכה לחלץ את האסימון מכתובת ה-URL.
מצב אינטראקטיבי לעומת מצב שקט
כשמבצעים קריאה ל-launchWebAuthFlow, אפשר להעביר סימון ('interactive': true בדוגמה שלמעלה)
שיציין אם רוצים להפעיל את ה-API במצב אינטראקטיבי או לא (נקרא גם מצב שקט). כשמפעילים את ה-API במצב אינטראקטיבי, במקרה הצורך מוצג למשתמש ממשק משתמש כדי לקבל את האסימון (ממשק משתמש לכניסה ו/או ממשק אישור, או עבור העניין הזה ממשק משתמש ספציפי של ספק).
כשמפעילים את ה-API במצב שקט, ה-API יחזיר אסימון רק אם הספק יכול לספק אסימון בלי להציג ממשק משתמש כלשהו. האפשרות הזו שימושית במקרים שבהם האפליקציה מבצעת את התהליך בזמן ההפעלה של האפליקציה, למשל, או באופן כללי כשלא נדרשת תנועת משתמש.
השיטה המומלצת היא להשתמש במצב שקט כאשר לא נדרשת תנועת משתמש, ולהשתמש במצב אינטראקטיבי אם מדובר בתנועה ממשתמש (לדוגמה, אם המשתמש לחץ על הלחצן כניסה באפליקציה). הערה: אנחנו לא אוכפים את דרישת התנועה.