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

ספריית 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 מחזירה ל-callback handler שלכם 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();
דף 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.

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

במודל Token, מערכת ההפעלה או הדפדפן לא שומרים את טוקן הגישה. במקום זאת, הטוקן החדש מתקבל קודם בזמן טעינת הדף, או לאחר מכן על ידי הפעלת קריאה ל-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();

‫Google APIs תומך ב-CORS כברירת מחדל. שליחת אסימון גישה בבקשת XMLHttpRequest או fetch מפעילה בדיקת קדם-הפעלה של CORS, כלומר בקשת OPTIONS לפני בקשת GET או POST.

בקטע הבא מוסבר איך לשלב בקלות ממשקי 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);
  });