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

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

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

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

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

כל האפליקציות פועלות לפי דפוס בסיסי בעת גישה לממשק API של Google באמצעות 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. לבדוק את היקפי הגישה שהוענקו על ידי המשתמש.

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

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

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

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

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

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

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

תרחישים

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

נקודת הקצה של OAuth 2.0 של Google תומכת באפליקציות של שרתי אינטרנט שמשתמשות בשפות ובמסגרות כמו 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 app, 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 APIs מטעם חשבון השירות ולא נדרשת הסכמה מהמשתמשים. (בתרחישים שאינם חשבונות שירות, האפליקציה מפעילה את Google APIs מטעם משתמשי קצה, ולפעמים נדרשת הסכמה מהמשתמשים).

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

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

מידע נוסף זמין ב משאבי העזרה בנושא חשבון שירות.

גודל האסימון

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

  • קודי הרשאות: 256 בייטים
  • אסימוני גישה: 2,048 בייטים
  • אסימוני רענון: 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)

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

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

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

ספריות לקוח

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