גוגל מחויבת לקידום הון גזעי לקהילות שחורות. תראה איך.

שימוש ב- OAuth 2.0 לגישה לממשקי API של Google

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

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

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

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

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

1. השג אישורי OAuth 2.0 מה- Google API Console.

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

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

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

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

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

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

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

3. בחן את היקפי הגישה שהעניק המשתמש.

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

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

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

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

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

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

תרחישים

יישומי שרת אינטרנט

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

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

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

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

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

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

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

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

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

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

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

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

יישומי צד לקוח (JavaScript)

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

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

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

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

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

יישומים בהתקני קלט מוגבל

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

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

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

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

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

לפרטים, ראה שימוש ב- OAuth 2.0 למכשירים .

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

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

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

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

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

לפרטים, עיין בתיעוד חשבון השירות .

גודל האסימון

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

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

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

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

רענן תפוגת אסימון

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

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

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

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

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

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

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

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

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

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

ספריות לקוחות

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