ממשקי 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.
שלבים בסיסיים
כל האפליקציות בנויות לפי דפוס בסיסי בגישה ל-Google API באמצעות OAuth 2.0. ככלל, עליך לבצע חמישה שלבים:
1. קבלת פרטי כניסה של OAuth 2.0 מ- Google API Console.
בכתובת Google API Console אפשר לקבל את פרטי הכניסה של OAuth 2.0, כמו מזהה הלקוח והסוד של הלקוח, שידועים ל-Google וגם לאפליקציה שלך. קבוצת הערכים משתנה בהתאם לסוג האפליקציה שאתם מפתחים. לדוגמה, אפליקציית JavaScript לא מחייבת סוד, אבל אפליקציית שרת אינטרנט כן דורשת סוד.
צריך ליצור לקוח OAuth המתאים לפלטפורמה שבה האפליקציה תפעל, לדוגמה:
- כשמדובר באפליקציות אינטרנט בצד השרת או באפליקציות אינטרנט של JavaScript, יש להשתמש בסוג הלקוח 'אינטרנט'. אין להשתמש בסוג הלקוח הזה עבור כל אפליקציה אחרת, כגון אפליקציות מקוריות או לנייד.
- לאפליקציות ל-Android, צריך להשתמש בסוג הלקוח 'Android'.
- לאפליקציות ל-iOS ול-macOS, צריך להשתמש בסוג הלקוח 'iOS'.
- לאפליקציות Universal Windows Platform, צריך להשתמש בסוג הלקוח "Universal Windows Platform".
- עבור מכשירים עם קלט מוגבל, כמו טלוויזיה או מכשירים מוטמעים, יש להשתמש בסוג הלקוח 'טלוויזיות ומכשירים עם קלט מוגבל'.
- לאינטראקציות בין שרתים, השתמשו בחשבונות שירות.
2. קבלת אסימון גישה משרת ההרשאות של Google.
כדי שהאפליקציה שלך תוכל לגשת לנתונים פרטיים באמצעות Google API, היא צריכה לקבל
אסימון גישה שמעניק גישה לממשק ה-API הזה. אסימון גישה יחיד יכול להעניק רמות גישה שונות למספר ממשקי API. פרמטר משתנה שנקרא scope קובע את קבוצת
המשאבים והפעולות שאסימון הגישה מעניק. בזמן הבקשה לאסימון גישה, האפליקציה שולחת ערך אחד או יותר בפרמטר scope.
יש כמה דרכים לשלוח את הבקשה, והן משתנות בהתאם לסוג האפליקציה שאתם יוצרים. לדוגמה, אפליקציית JavaScript עשויה לבקש אסימון גישה באמצעות הפניה אוטומטית של דפדפן ל-Google, ואפליקציה שמותקנת במכשיר ללא דפדפן משתמשת בבקשות לשירותי אינטרנט.
בחלק מהבקשות נדרש שלב אימות שבו המשתמש מתחבר לחשבון Google שלו. לאחר ההתחברות, נשאל המשתמש אם הוא מוכן להעניק הרשאה אחת או יותר שהאפליקציה שלך מבקשת. התהליך הזה נקרא הסכמת משתמשים.
אם המשתמש מעניק לפחות הרשאה אחת, שרת ההרשאות של Google ישלח לאפליקציה שלך אסימון גישה (או קוד הרשאה שבו האפליקציה שלך יכולה להשתמש כדי לקבל אסימון גישה), ורשימה של היקפי הרשאות שהוענקו על ידי האסימון הזה. אם המשתמש לא יעניק את ההרשאה, השרת יחזיר שגיאה.
באופן כללי, מומלץ לשלוח בקשה להיקפים באופן מצטבר, ולא רק בהתחלה. לדוגמה, אפליקציה מסוימת שתומכת בשמירת אירועים ביומן אינה יכולה לבקש גישה ליומן Google עד שהמשתמש ילחץ על הלחצן 'הוספה ליומן', אלא במאמר הרשאה מצטברת.
3. לבדוק את היקפי הגישה שהוענקו על ידי המשתמש.
השוואה של היקפי ההרשאות הכלולים בתגובה של אסימון הגישה להיקפי ההרשאות הנדרשים לצורך גישה לתכונות ולפונקציונליות של האפליקציה, בהתאם לגישה ל-API קשור של Google. משביתים את כל התכונות של האפליקציה שלא יכולות לתפקד בלי גישה ל-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 יכולים להגיע לקובצי יומן לא מאובטחים לחלוטין. כמו כן, מומלץ לא ליצור שמות מיותרים של פרמטרים של 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. אחרי שיפוג התוקף של אסימון הגישה, האפליקציה תשתמש באסימון הרענון כדי לקבל אסימון חדש.
אפשר לקרוא פרטים נוספים במאמר שימוש ב-OAuth 2.0 לאפליקציות שרת אינטרנט.
אפליקציות מותקנות
נקודת הקצה Google OAuth 2.0 תומכת באפליקציות שמותקנות במכשירים כמו מחשבים, מכשירים ניידים וטאבלטים. כשיוצרים מזהה לקוח דרך Google API Console, צריך לציין שמדובר באפליקציה מותקנת, ואז לבחור את סוג האפליקציה: Android, אפליקציית Chrome, iOS, Universal Windows Platform (UWP) או אפליקציית Desktop.
התהליך גורם לזיהוי לקוח, ובמקרים מסוימים, לסוד לקוח, שמוטמע בקוד המקור של האפליקציה. (בהקשר הזה, סוד הלקוח לא נחשב כסוד).
רצף ההרשאות מתחיל כשהאפליקציה מעבירה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשנים ובהסכמת המשתמשים. כתוצאה מכך מתקבל קוד הרשאה, והאפליקציה יכולה להחליף אותו באסימון גישה ובאסימון רענון.
האפליקציה צריכה לאחסן את אסימון הרענון לשימוש עתידי ולהשתמש באסימון הגישה כדי לגשת ל-Google API. אחרי שיפוג התוקף של אסימון הגישה, האפליקציה תשתמש באסימון הרענון כדי לקבל אסימון חדש.
אפשר לקרוא פרטים נוספים במאמר שימוש ב-OAuth 2.0 לאפליקציות מותקנות.
אפליקציות (JavaScript) בצד הלקוח
נקודת הקצה Google OAuth 2.0 תומכת באפליקציות JavaScript שפועלות בדפדפן.
רצף ההרשאות מתחיל כשהאפליקציה מעבירה דפדפן לכתובת URL של Google. כתובת ה-URL כוללת פרמטרים של שאילתה שמציינים את סוג הגישה המבוקשת. Google מטפלת באימות המשתמשים, בבחירת הסשנים ובהסכמת המשתמשים.
התוצאה היא אסימון גישה שהלקוח צריך לאמת לפני שהוא כולל אותו בבקשת Google API. כשתוקף האסימון יפוג, האפליקציה תחזור על התהליך.
לפרטים, ראו שימוש ב-OAuth 2.0 לאפליקציות בצד הלקוח.
אפליקציות במכשירים עם קלט מוגבל
נקודת הקצה Google OAuth 2.0 תומכת באפליקציות שפועלות במכשירים עם קלט מוגבל, כמו קונסולות משחקים, מצלמות וידאו ומדפסות.
רצף ההרשאות מתחיל בבקשה ששולחת בקשה לשירותי אינטרנט אל כתובת URL של Google לקבלת קוד הרשאה. התגובה כוללת מספר פרמטרים, כולל כתובת URL וקוד שהאפליקציה מציגה למשתמש.
המשתמש מקבל את כתובת ה-URL והקוד מהמכשיר, ולאחר מכן עובר למכשיר או למחשב נפרדים עם יכולות קלט עשירות יותר. המשתמש מפעיל דפדפן, מנווט לכתובת האתר שצוינה, מתחבר ומזין את הקוד.
בינתיים, האפליקציה בודקת כתובת URL של 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, שמחזיר אסימון גישה. האפליקציה משתמשת באסימון כדי לגשת ל-Google API. כשפג התוקף של האסימון, האפליקציה חוזרת על התהליך.
פרטים נוספים זמינים במסמכי התיעוד של חשבון השירות.
גודל אסימון
האסימונים עשויים להשתנות בהתאם למגבלות הבאות:
- קודי אישור: 256 בייט
- אסימוני גישה: 2,048 בייטים
- רענון האסימונים: 512 בייטים
אסימוני הגישה שמוחזרים על ידי Security Token API API של Google Cloud בנויים בצורה דומה לאסימוני הגישה מסוג OAuth 2.0 של Google API, אבל יש להם מגבלות שונות של גודל האסימון. פרטים נוספים זמינים במסמכי התיעוד של ה-API.
Google שומרת לעצמה את הזכות לשנות את גודל האסימון במסגרת המגבלות האלה, והאפליקציה שלך חייבת לתמוך בגודלי אסימון משתנים בהתאם.
רענון של תוקף האסימון
עליך לכתוב את הקוד כדי לחזות אם האפשרות של אסימון רענון שכבר פועל לא תפעל. אסימון רענון עשוי להפסיק לפעול עקב אחת מהסיבות הבאות:
- המשתמש ביטל את הגישה של האפליקציה שלך.
- אסימון הרענון לא היה בשימוש במשך שישה חודשים.
- המשתמש שינה את הסיסמאות ואסימון הרענון מכיל היקפי הרשאות של Gmail.
- חשבון המשתמש חרג מהמספר המקסימלי של אסימוני רענון (חיים).
- אם מנהל מערכת
הגדיר אחד או יותר מהשירותים שביקשת בהיקף ההרשאות של האפליקציה כ'מוגבל' (השגיאה
היא
admin_policy_enforced). - בממשקי Google Cloud Platform API – ייתכן חריגה ממשך הסשן שהוגדר על ידי האדמין.
לפרויקט ב-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 Console, ל-Google Cloud SDK (שנקרא גם gcloud CLI) ולכל אפליקציית OAuth של צד שלישי שדורשת את ההיקף של Cloud Platform. אם למשתמשים יש מדיניות לבקרה על סשן, ותוקף התפוגה של הסשנים יסתיים, הקריאות ל-API יכללו שגיאה דומה לזו שקורה אם אסימון הרענון יבוטל – הקריאה תיכשל וסוג השגיאה יהיה invalid_grant. אפשר להשתמש בשדה error_subtype כדי להבדיל בין אסימון שנכשל לכשל עקב מדיניות של בקרת סשנים (למשל, "error_subtype": "invalid_rapt"). משך הסשנים יכול להיות מוגבל מאוד (בין שעה ל-2 אלפיות השנייה, 24 שעות) בין 1 ל-4 ימים, בין 1
באותה מידה, אין להשתמש בפרטי כניסה של משתמש לפריסת שרת לשרת או לעודד אותם. אם פרטי הכניסה של המשתמשים פרוסים בשרת למשך משימות או פעולות ממושכות ולקוח מחיל מדיניות לבקרת סשנים לגבי המשתמשים האלה, אפליקציית השרת תיכשל כי לא תהיה דרך לאמת מחדש את המשתמש כאשר משך הסשן יסתיים.
למידע נוסף על האופן שבו ניתן לעזור ללקוחות לפרוס את התכונה הזו, מומלץ לקרוא את מאמר העזרה הזה שמתמקד במנהלי מערכת.
ספריות לקוח
ספריות הלקוח הבאות משתלבות עם מסגרות פופולריות, מה שהופך את ההטמעה של OAuth 2.0 לפשוטה יותר. עם הזמן, נוסיף לספריות תכונות נוספות.