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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

תרחישים

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

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

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

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

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

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

אפליקציות מותקנות

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

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

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

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

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

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

יישומים בצד הלקוח (JavaScript).

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

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

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

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

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

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

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

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

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

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

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

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

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

ממשקי API של Google כגון Prediction API ו-Google Cloud Storage יכולים לפעול בשם האפליקציה שלך מבלי לגשת למידע על המשתמש. במצבים אלה האפליקציה שלך צריכה להוכיח את זהותה בפני ה-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 .

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

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

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

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

לפרויקט של Google Cloud Platform עם מסך הסכמה של OAuth המוגדר לסוג משתמש חיצוני וסטטוס פרסום של "בדיקה" מונפק אסימון רענון שיפוג בעוד 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 לפשוטה יותר. תכונות נוספות יתווספו לספריות עם הזמן.