שימוש במודל האסימונים

ספריית JavaScript‏ google.accounts.oauth2 עוזרת לכם לבקש הסכמה מהמשתמשים ולקבל אסימון גישה כדי לעבוד עם נתוני משתמשים. הוא מבוסס על תהליך הענקת הרשאה משתמעת של OAuth 2.0 ומיועד לאפשר לכם לקרוא ל-Google APIs ישירות באמצעות REST ו-CORS, או להשתמש בספריית הלקוח של Google APIs ל-JavaScript (שנקראת גם gapi.client) כדי לקבל גישה פשוטה וגמישה ל-APIs המורכבים יותר שלנו.

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

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

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

דרישות מוקדמות

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

אתחול של לקוח טוקן

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

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

הפעלת תהליך יצירת טוקן OAuth 2.0

משתמשים ב-method ‏requestAccessToken() כדי להפעיל את תהליך חוויית המשתמש של האסימון ולקבל אסימון גישה. ‫Google מבקשת מהמשתמש:

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

תנועת משתמש מפעילה את תהליך הטוקן: <button onclick="client.requestAccessToken();">Authorize me</button>

לאחר מכן, Google מחזירה TokenResponse שמכיל טוקן גישה ורשימה של היקפי הרשאות שהמשתמש העניק גישה אליהם, או שגיאה, למטפל בקריאה החוזרת.

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

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

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

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

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

מידע מפורט יותר זמין במאמר איך מטפלים בהרשאות גרנולריות.

הרשאה מצטברת

במקרה של אפליקציות אינטרנט, שני התרחישים הכלליים הבאים מדגימים הרשאת גישה מצטברת באמצעות:

  • אפליקציית Ajax בדף יחיד, שלרוב משתמשת ב-XMLHttpRequest עם גישה דינמית למשאבים.
  • במקרה של כמה דפי אינטרנט, המשאבים מופרדים ומנוהלים על בסיס כל דף בנפרד.

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

Ajax

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

אפליקציית Ajax
מאתחלים את לקוח הטוקן בטעינת הדף: 
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
כדי לבקש הסכמה ולקבל טוקנים לגישה באמצעות תנועות של המשתמש, לוחצים על '+' כדי לפתוח את:

מסמכים לקריאה

הצגת המסמכים האחרונים

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );

אירועים בזמן הקרוב

הצגת פרטי היומן

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );

הצגת תמונות

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );

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

מספר דפי אינטרנט

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

אפליקציה מרובת דפים
דף אינטרנט קוד
עמוד 1. מסמכי Docs לקריאה 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
Page 2. אירועים בזמן הקרוב 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
Page 3. קרוסלת תמונות 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();

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

הרשאות פרטניות

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

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

התשובה תכלול גם מענקים שאושרו בעבר בסשנים או בבקשות קודמים. תיעוד של הסכמת המשתמש נשמר לכל משתמש ומזהה לקוח, והוא נשמר בכמה קריאות ל-initTokenClient() או ל-requestAccessToken(). כברירת מחדל, הסכמת המשתמש נדרשת רק בפעם הראשונה שבה המשתמש נכנס לאתר שלכם ומבקש היקף חדש, אבל אפשר לבקש אותה בכל טעינת דף באמצעות prompt=consent באובייקטים של הגדרות Token Client.

עבודה עם אסימונים

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

שימוש ב-REST וב-CORS עם ממשקי API של Google

אפשר להשתמש באסימון גישה כדי לשלוח בקשות מאומתות ל-Google APIs באמצעות REST ו-CORS. כך המשתמשים יכולים להיכנס לחשבון, להביע הסכמה, Google יכולה להנפיק אסימון גישה והאתר יכול לעבוד עם נתוני המשתמשים.

בדוגמה הזו, מוצגים אירועים קרובים ביומן של המשתמשים המחוברים באמצעות אסימון הגישה שמוחזר על ידי tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

מידע נוסף זמין במאמר איך משתמשים ב-CORS כדי לגשת אל ממשקי API של Google.

בקטע הבא מוסבר איך לשלב בקלות ממשקי API מורכבים יותר.

עבודה עם ספריית JavaScript של Google APIs

לקוח האסימון פועל עם ספריית הלקוח של Google API ל-JavaScript. אפשר לראות את קטע הקוד בהמשך.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

תוקף הטוקן

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

קוראים לשיטה google.accounts.oauth2.revoke כדי להסיר את הסכמת המשתמש ואת הגישה למשאבים לכל היקפי ההרשאות שניתנו לאפליקציה. כדי לבטל את ההרשאה הזו, נדרש אסימון גישה תקין:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });