שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs

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

כדי להתחיל, צריך לקבל פרטי כניסה של לקוח OAuth 2.0 מ- Google API Console. לאחר מכן, אפליקציית הלקוח מבקשת אסימון גישה משרת ההרשאות של Google, מחלצת אסימון מהתגובה ושולחת את האסימון ל-Google API שאליו רוצים לגשת. כדי לראות הדגמה אינטראקטיבית של השימוש ב-OAuth 2.0 עם Google (כולל האפשרות להשתמש בפרטי הכניסה של הלקוח שלכם), תוכלו להתנסות ב-OAuth 2.0 Playground.

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

שלבים בסיסיים

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

1. מקבלים את פרטי הכניסה ל-OAuth 2.0 מה- Google API Console.

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

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

2. מקבלים אסימון גישה משרת ההרשאות של Google.

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

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

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

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

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

3. בודקים את היקפי הגישה שהמשתמש העניק.

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

יכול להיות שהיקף שכלול בבקשה לא יתאים להיקף שכלול בתגובה, גם אם המשתמש העניק את כל ההיקפים המבוקשים. במסמכי התיעוד של כל ממשק Google API מפורטים ההיקפים הנדרשים לגישה. ממשק API יכול למפות כמה ערכים של מחרוזת היקף להיקף גישה יחיד, ולהחזיר את אותה מחרוזת היקף לכל הערכים שמותר להשתמש בהם בבקשה. דוגמה: Google People API עשוי להחזיר היקף של https://www.googleapis.com/auth/contacts כשאפליקציה ביקשה מהמשתמש לאשר היקף של https://www.google.com/m8/feeds/. השיטה people.updateContact של Google People API דורשת היקף https://www.googleapis.com/auth/contacts שהוקצה.

4. שולחים את אסימון הגישה ל-API.

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

אסימוני הגישה תקפים רק לקבוצת הפעולות והמשאבים שמתוארים ב-scope של בקשת האסימון. לדוגמה, אם אסימון גישה מונפק ל-Google Calendar API, הוא לא מעניק גישה ל-Google Contacts API. עם זאת, אפשר לשלוח את אסימון הגישה הזה ל-Google Calendar API כמה פעמים לפעולות דומות.

5. אם צריך, מרעננים את אסימון הגישה.

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

תרחישים

אפליקציות בשרת האינטרנט

נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות של שרת אינטרנט שמשתמשות בשפות ובמסגרות כמו PHP,‏ Java,‏ Go,‏ Python,‏ Ruby ו-ASP.NET.

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

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

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

לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות של שרת אינטרנט.

יישומים מותקנים

נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות שמותקנות במכשירים כמו מחשבים, מכשירים ניידים וטאבלטים. כשיוצרים מזהה לקוח דרך Google API Console, מציינים שמדובר באפליקציה מותקנת ובוחרים את סוג האפליקציה: Android,‏ אפליקציית Chrome,‏ iOS,‏ Universal Windows Platform‏ (UWP) או אפליקציה למחשב.

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

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

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

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

לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות מותקנות.

אפליקציות בצד הלקוח (JavaScript)

נקודת הקצה של Google OAuth 2.0 תומכת באפליקציות JavaScript שפועלות בדפדפן.

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

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

אפליקציית ה-JS שולחת בקשה לטוקן לשרת ההרשאות של Google, מקבלת אסימון, מאמתת אותו ומשתמשת בו כדי לבצע קריאה לנקודת קצה של Google API.

לפרטים נוספים, ראו שימוש ב-OAuth 2.0 לאפליקציות בצד הלקוח.

אפליקציות במכשירים מוגבלים לקליטת נתונים

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

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

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

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

המשתמש נכנס לחשבון במכשיר נפרד שיש בו דפדפן

פרטים נוספים זמינים במאמר שימוש ב-OAuth 2.0 למכשירים.

חשבונות שירות

ממשקי Google API כמו Prediction API ו-Google Cloud Storage יכולים לפעול בשם האפליקציה שלכם בלי לגשת למידע על המשתמשים. במקרים כאלה, האפליקציה צריכה להוכיח את הזהות שלה ל-API, אבל לא נדרשת הסכמה מהמשתמש. באופן דומה, בתרחישים ארגוניים, האפליקציה יכולה לבקש גישה להענקה למשאבים מסוימים.

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

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

אפליקציית השרת משתמשת ב-JWT כדי לבקש אסימון משרת ההרשאות של Google, ואז משתמשת באסימון כדי לקרוא לנקודת קצה של Google API. אין מעורבות של משתמש קצה.

פרטים נוספים זמינים במסמכי העזרה של service-account.

גודל הטוקן

האסימונים יכולים להיות בגדלים שונים, עד למגבלות הבאות:

  • קודי הרשאה: 256 בייטים
  • אסימוני גישה: 2048 בייטים
  • אסימוני רענון: 512 בייטים

אסימוני הגישה שמוחזרים על ידי Security Token Service API של Google Cloud דומים במבנה לאסימוני הגישה מסוג OAuth 2.0 של Google API, אבל יש להם מגבלות שונות על גודל האסימון. פרטים נוספים זמינים במסמכי העזרה של ה-API.

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

תאריך התפוגה של טוקן הרענון

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

לפרויקט ב-Google Cloud Platform עם מסך הסכמה ל-OAuth שמוגדר לסוג משתמש חיצוני וסטטוס פרסום 'בדיקה', יונפק אסימון רענון שתוקפו יפוג תוך 7 ימים, אלא אם היקפי הרשאות ה-OAuth היחידים שנדרשו הם קבוצת משנה של שם, כתובת אימייל ופרופיל משתמש (דרך היקפי userinfo.email, userinfo.profile, openid או המקבילים שלהם ב-OpenID Connect).

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

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

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

טיפול במדיניות בקרת סשנים לארגונים ב-Google Cloud Platform ‏ (GCP)

אדמינים של ארגונים ב-GCP עשויים לדרוש אימות חוזר תדיר של משתמשים בזמן שהם ניגשים למשאבים ב-GCP, באמצעות התכונה של בקרת סשנים ב-Google Cloud. המדיניות הזו משפיעה על הגישה למסוף Google Cloud, ל-Google Cloud SDK (שנקרא גם CLI של gcloud) לכל אפליקציית OAuth של צד שלישי שדורשת את ההיקף Cloud Platform. אם למשתמש מוגדרת מדיניות בקרה על סשנים, בתום משך הסשן יתרחשו שגיאות בקריאות ה-API, בדומה למה שקורה אם אסור להשתמש באסימון הרענון – הקריאה תיכשל עם סוג השגיאה invalid_grant. אפשר להשתמש בשדה error_subtype כדי להבדיל בין אסימון שהתוקף שלו בוטל לבין כשל בגלל מדיניות בקרה על סשנים (לדוגמה, "error_subtype": "invalid_rapt"). מכיוון שמשכי הסשנים יכולים להיות מוגבלים מאוד (בין שעה אחת ל-24 שעות), צריך לטפל בתרחיש הזה בצורה חלקה על ידי הפעלה מחדש של סשן האימות.

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

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

ספריות לקוח

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