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

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

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

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

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

הגדרה

מוצאים או יוצרים מזהה לקוח לפי השלבים שמפורטים במדריך קבלת מזהה לקוח של Google API. בשלב הבא, מוסיפים את ספריית הלקוח לדפים באתר שבהם יתבצעו הקריאות ל-Google APIs. לבסוף, מפעילים את לקוח האסימונים. בדרך כלל, הפעולה הזו מתבצעת בתוך הטיפול (handler) של onload בספריית הלקוח.

איך מפעילים לקוח של אסימונים

קוראים ל-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) את הערך TokenResponse שמכיל טוקן גישה ורשימת היקפי הגישה שהמשתמש העניק, או שגיאה.

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

איך מטפלים בהסכמה

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

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

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

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

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

הרשאה מצטברת

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

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

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

Ajax

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

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

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

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

  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          

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

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

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

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

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

אפשר להשתמש באסימון גישה כדי לשלוח בקשות מאומתות ל-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 כדי לגשת ל-Google APIs.

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