אימות משתמשים

פרוטוקולים לאימות באינטרנט משתמשים בתכונות של HTTP, אבל אפליקציות Chrome פועלות בתוך מאגר האפליקציות. הן לא נטענות דרך HTTP ולא יכולות לבצע הפניות או להגדיר קובצי cookie.

משתמשים ב-Chrome Identity API כדי לאמת משתמשים: ה-getAuthToken למשתמשים שמחוברים לחשבון Google שלהם, וה-launchWebAuthFlow למשתמשים שמחוברים לחשבון שאינו של Google. אם האפליקציה שלכם משתמשת בשרת משלה לאימות משתמשים, תצטרכו להשתמש באפשרות השנייה.

איך זה עובד

למשתמשים באפליקציות ל-Chrome יש חשבון Google שמשויך לפרופיל שלהם. אפליקציות יכולות לקבל אסימוני OAuth2 למשתמשים האלה באמצעות ה-API של getAuthToken.

אפליקציות שרוצות לבצע אימות באמצעות ספקי זהויות שאינם Google צריכות לבצע קריאה ל-launchWebAuthFlow. בשיטה הזו נעשה שימוש בחלון קופץ בדפדפן כדי להציג את דפי הספק, ומתבצעת תיעוד של הפניות אוטומטיות לתבניות כתובות ה-URL הספציפיות. כתובות ה-URL להפניה אוטומטית מועברות לאפליקציה והאפליקציה מחלצת את האסימון מכתובת ה-URL.

אימות של חשבון Google

אלה חמשת השלבים שצריך לבצע:

  1. מוסיפים הרשאות למניפסט ומעלים את האפליקציה.
  2. מעתיקים את המפתח מ-manifest.json המותקן למניפסט המקור, כדי שמזהה האפליקציה יישאר קבוע במהלך הפיתוח.
  3. מקבלים מזהה לקוח OAuth2 לאפליקציית Chrome.
  4. מעדכנים את המניפסט כך שיכלול את מזהה הלקוח ואת ההיקפים.
  5. מקבלים את טוקן האימות.

הוספת הרשאות והעלאת האפליקציה

עליך לוודא שהרשאת הזהות נמצאת במניפסט. לאחר מכן תוכלו להעלות את האפליקציה לדף ניהול האפליקציות והתוספים (ראו פרסום).

"permissions": [
  "identity"
]

העתקת המפתח למניפסט

כשמגדירים את האפליקציה במסוף Google OAuth, צריך לספק את מזהה האפליקציה, שייבדק במהלך בקשות האסימונים. לכן חשוב שיהיה מזהה אפליקציה עקבי במהלך הפיתוח.

כדי שהמזהה של האפליקציה יישאר קבוע, צריך להעתיק את המפתח ב-manifest.json שהותקן למניפסט המקור. זה לא הכי פשוט, אבל זה מה שצריך לעשות:

  1. עוברים אל ספריית נתוני המשתמש. דוגמה ב-MacOs: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. בדף הניהול של האפליקציות והתוספים, צריך לציין את האפליקציות והתוספים המותקנים ולהתאים את מזהה האפליקציה לאותו המזהה.
  3. עוברים לספריית האפליקציות המותקנות (זו תהיה גרסה בתוך מזהה האפליקציה). פותחים את הקובץ manifest.json שהותקן (pico היא דרך מהירה לפתוח את הקובץ).
  4. מעתיקים את ה'מפתח' ב-manifest.json שמותקן ומדביקים אותו בקובץ מניפסט המקור של האפליקציה.

אחזור של מזהה הלקוח ב-OAuth2

כדי לקבל את מזהה הלקוח, צריך לרשום את האפליקציה במסוף Google APIs:

  1. מתחברים ל-Google APIs Console באמצעות אותו חשבון Google שמשמש להעלאת האפליקציה לחנות האינטרנט של Chrome.
  2. כדי ליצור פרויקט חדש, מרחיבים את התפריט הנפתח בפינה הימנית העליונה ובוחרים באפשרות Create (יצירה).
  3. אחרי שיוצרים את השירותים ונותנים להם שם, עוברים לפריט בתפריט הניווט 'שירותים' ומפעילים את כל שירותי Google שהאפליקציה צריכה.
  4. עוברים לפריט 'גישה ל-API' בתפריט הניווט ולוחצים על הלחצן הכחול Create an OAuth 2.0 client ID….
  5. מזינים את פרטי המיתוג המבוקשים ובוחרים באפשרות אפליקציה מותקנת.
  6. בוחרים באפשרות אפליקציית 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 בדוגמה שלמעלה) שמציין אם רוצים להפעיל את ה-API במצב אינטראקטיבי או במצב שקט. אם מפעילים את ה-API במצב אינטראקטיבי, המשתמש מקבל ממשק משתמש לכניסה ו/או לאישור לפי הצורך, כפי שמוצג בצילום המסך הבא:

צילום מסך שבו מוצג ממשק המשתמש כשאפליקציה משתמשת ב-Identity API כדי לאמת חשבון Google

אם מפעילים את ה-API במצב שקט, ה-API יחזיר אסימון רק אם אפשר ליצור אותו בלי להציג ממשק משתמש. האפשרות הזו שימושית במקרים שבהם האפליקציה מבצעת את התהליך בזמן ההפעלה, או באופן כללי במקרים שבהם אין תנועה של משתמש.

השיטה המומלצת היא להשתמש במצב שקט כשאין תנועת משתמש, ולהשתמש במצב אינטראקטיבי אם יש תנועת משתמש (לדוגמה, המשתמש לחץ על לחצן הכניסה באפליקציה). לתשומת ליבך, אנחנו לא אוכפים דרישות כלשהן לגבי תנועות.

שמירה במטמון

ב-Chrome יש מטמון בזיכרון של אסימוני גישה, כך שאפשר להפעיל את getAuthToken בכל פעם שצריך להשתמש באסימון. תפוגת התוקף של הטוקן מטופלת באופן אוטומטי על ידי המטמון.

אפשר לראות את המצב הנוכחי של מטמון האסימונים ב-chrome://identity-internals.

יש מקרים שבהם אסימוני גישה שלא פג תוקפם יפסיקו לפעול, למשל כשהמשתמש משנה את הסיסמה. קריאות ל-API באמצעות האסימון יתחילו להחזיר את קוד הסטטוס 401 של HTTP. אם תזהו שזה קרה, תוכלו להסיר את האסימון הלא חוקי מהמטמון של 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

אלה שלושת השלבים שצריך לבצע:

  1. נרשמים אצל הספק.
  2. מוסיפים הרשאות למשאבי הספק שהאפליקציה תקבל אליהם גישה.
  3. מקבלים את טוקן האימות.

רישום אצל הספק

צריך לרשום מזהה לקוח OAuth2 אצל הספק ולהגדיר את מזהה הלקוח כאתר. כדי שה-URI להפניה אוטומטית ייכנס במהלך הרישום, צריך להשתמש בכתובת ה-URL בפורמט הבא: https://<extension-id>.chromiumapp.org/<anything-here>

לדוגמה, אם מזהה האפליקציה הוא abcdefghijklmnopqrstuvwxyzabcdef ואתם רוצים שהנתיב יהיה provider_cb, כדי להבדיל אותו ממזהי URI להפניה אוטומטית של ספקים אחרים, צריך להשתמש ב-https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb: 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 יתעד את הפעולה הזו ויפעיל את הקריאה החוזרת של האפליקציה עם כתובת ה-URL המלאה להפניה אוטומטית. האפליקציה צריכה לחלץ את האסימון מכתובת ה-URL.

מצב אינטראקטיבי לעומת מצב שקט

כשקוראים ל-launchWebAuthFlow, אפשר להעביר דגל ('interactive': true בדוגמה שלמעלה) שמציין אם רוצים לקרוא ל-API במצב אינטראקטיבי או לא (כלומר במצב שקט). אם מפעילים את ה-API במצב אינטראקטיבי, המשתמש מקבל ממשק משתמש, אם יש צורך, כדי לקבל את האסימון (ממשק משתמש לכניסה ו/או ממשק משתמש לאישור, או כל ממשק משתמש ספציפי לספק).

אם מפעילים את ה-API במצב שקט, ה-API מחזיר אסימון רק אם הספק יכול לספק אסימון בלי להציג ממשק משתמש. האפשרות הזו שימושית במקרים שבהם האפליקציה מבצעת את התהליך בזמן ההפעלה, או באופן כללי במקרים שבהם אין תנועה של המשתמש.

השיטה המומלצת היא להשתמש במצב שקט כשלא מתבצעת תנועת משתמש, ולהשתמש במצב אינטראקטיבי אם מבצעים תנועת משתמש (למשל, המשתמש לחץ על לחצן הכניסה באפליקציה). חשוב לדעת שאנחנו לא אוכפים את הדרישה לתנועות.