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

ממשקי API של Google משתמשים ב פרוטוקול 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

להגדרת חשבונות השירות

ממשקי API של Google, כמו ממשק 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 בייטים

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

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

רענון של תוקף האסימון

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

  • המשתמש ביטל את הגישה של האפליקציה שלך.
  • לא נעשה שימוש באסימון הרענון למשך שישה חודשים.
  • המשתמש שינה את הסיסמאות ואסימון הרענון מכיל היקפי הרשאות של Gmail.
  • חשבון המשתמש חרג מהמספר המקסימלי של אסימוני רענון (פעילים) שניתנו.
  • המשתמש שייך לארגון ב-Google Cloud Platform שיש לו מדיניות בנושא אמצעי בקרה על פעילות.

לפרויקט ב-Google Cloud Platform יש מסך הסכמה מסוג OAuth המוגדר לסוג משתמש חיצוני וסטטוס פרסום של "Testing"

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

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

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

התמודדות עם מדיניות בנושא בקרת סשנים בארגונים של Google Cloud Platform (GCP)

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

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

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

ספריות לקוח

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