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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

רצף ההרשאות מתחיל כאשר היישום שלך מפנה דפדפן לכתובת אתר של גוגל; כתובת ה- 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 בתים

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

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

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

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

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