במסמך הזה מוסבר איך להטמיע הרשאה באמצעות OAuth 2.0 כדי לגשת ל-Google APIs מאפליקציית אינטרנט של JavaScript. פרוטוקול OAuth 2.0 מאפשר למשתמשים לשתף נתונים ספציפיים עם אפליקציה, תוך שמירה על הפרטיות של שמות המשתמשים, הסיסמאות ומידע אחר שלהם. לדוגמה, אפליקציה יכולה להשתמש ב-OAuth 2.0 כדי לקבל הרשאה ממשתמשים לאחסן קבצים ב-Google Drive שלהם.
תהליך OAuth 2.0 הזה נקרא תהליך מתן הרשאות משתמע. הוא מיועד לאפליקציות שמקבלות גישה לממשקי API רק כאשר המשתמש נוכח באפליקציה. לאפליקציות האלה אין אפשרות לאחסן מידע סודי.
בתהליך הזה, האפליקציה פותחת כתובת URL של Google שמשתמשת בפרמטרים של שאילתה כדי לזהות את האפליקציה וסוג הגישה ל-API שנדרשת לאפליקציה. אפשר לפתוח את כתובת ה-URL בחלון הדפדפן הנוכחי או בחלון קופץ. המשתמש יכול לבצע אימות מול Google ולהעניק את ההרשאות המבוקשות. אחר כך Google מפנה את המשתמשים חזרה לאפליקציה. ההפניה האוטומטית כוללת אסימון גישה, שהאפליקציה מאמתת ואז משתמשת בו כדי לשלוח בקשות API.
ספריית הלקוח של Google APIs ו-Google Identity Services
אם אתם משתמשים בספריית הלקוח של Google APIs ל-JavaScript כדי לבצע קריאות מורשות ל-Google, תצטרכו להשתמש בספריית ה-JavaScript של Google Identity Services כדי לטפל בתהליך OAuth 2.0. מומלץ לעיין במודל האסימונים של Google Identity Services, המבוסס על תהליך הענקת הרשאה משתמעת של OAuth 2.0.
דרישות מוקדמות
הפעלת ממשקי API בפרויקט
כל אפליקציה שקוראת ל-Google APIs צריכה להפעיל את ממשקי ה-API האלה ב- API Console.
כדי להפעיל API בפרויקט:
- Open the API Library ב Google API Console.
- If prompted, select a project, or create a new one.
- בטבלה API Library מוצגים כל ממשקי ה-API הזמינים, והם מקובצים לפי משפחת המוצרים והפופולריות שלה. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, אפשר להשתמש בחיפוש כדי לחפש אותו או ללחוץ על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
- בוחרים את ה-API שרוצים להפעיל ולוחצים על הלחצן הפעלה.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
יצירת פרטי כניסה להרשאה
לכל אפליקציה שמשתמשת ב-OAuth 2.0 כדי לגשת ל-Google APIs, חייבים להיות פרטי כניסה של הרשאה שמזהים את האפליקציה לשרת OAuth 2.0 של Google. בשלבים הבאים נסביר איך ליצור פרטי כניסה לפרויקט. לאחר מכן האפליקציות יוכלו להשתמש בפרטי הכניסה כדי לגשת לממשקי API שהפעלתם בפרויקט הזה.
- Go to the Credentials page.
- לוחצים על Create credentials > OAuth client ID.
- בוחרים את סוג האפליקציה Web application.
- ממלאים את הטופס. אפליקציות שמשתמשות ב-JavaScript כדי לשלוח בקשות מורשות ל-Google API חייבות לציין מקורות JavaScript מורשים. המקורות מזהים את הדומיינים שמהם האפליקציה יכולה לשלוח בקשות לשרת OAuth 2.0. המקורות האלה חייבים לעמוד בכללי האימות של Google.
זיהוי היקפי גישה
היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים הנדרשים, וגם למשתמשים יכולים לשלוט ברמת הגישה שהם מעניקים לאפליקציה. לכן יכול להיות קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבל את הסכמת המשתמש.
לפני שמתחילים להטמיע את הרשאת OAuth 2.0, מומלץ לזהות את היקפי ההרשאות הנדרשים לאפליקציה כדי לגשת אליהם.
המסמך היקפי API של OAuth 2.0 מכיל רשימה מלאה של היקפים שבהם תוכלו להשתמש כדי לגשת ל-Google APIs.
קבלת אסימוני גישה מסוג OAuth 2.0
בשלבים הבאים מוצגת האינטראקציה של האפליקציה עם שרת OAuth 2.0 של Google כדי לקבל את הסכמת המשתמש לבצע בקשת API בשם המשתמש. האפליקציה שלך חייבת לקבל את ההסכמה הזו כדי שניתן יהיה להריץ בקשת Google API שמחייבת הרשאת משתמש.
שלב 1: הפניה אוטומטית לשרת OAuth 2.0 של Google
כדי לבקש הרשאת גישה לנתונים של משתמש, צריך להפנות את המשתמש לשרת OAuth 2.0 של Google.
נקודות קצה של OAuth 2.0
עליך ליצור כתובת URL כדי לבקש גישה מנקודת הקצה מסוג OAuth 2.0 של Google בכתובת
https://accounts.google.com/o/oauth2/v2/auth. ניתן לגשת לנקודת הקצה הזו באמצעות HTTPS. חיבורי HTTP פשוטים נדחו.
שרת ההרשאות של Google תומך בפרמטרים הבאים של מחרוזת השאילתה לאפליקציות של שרת אינטרנט:
| פרמטרים | |||||||
|---|---|---|---|---|---|---|---|
client_id |
נדרש
מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה בשדה API Console Credentials page. |
||||||
redirect_uri |
נדרש
המדיניות הזו קובעת לאן שרת ה-API יפנה את המשתמש אוטומטית אחרי שהמשתמש ישלים את תהליך ההרשאה. הערך צריך להיות זהה לאחד ממזהי ה-URI המורשים להפניה אוטומטית בלקוח OAuth 2.0 שהגדרת ב- API Console
Credentials pageשל הלקוח. אם הערך הזה לא תואם
ל-URI מורשה להפניה אוטומטית עבור חשוב לשים לב שהסכמה |
||||||
response_type |
נדרש
אפליקציות JavaScript צריכות להגדיר את ערך הפרמטר הזה ל- |
||||||
scope |
נדרש
רשימת היקפים מופרדת ברווחים של המשאבים שמציינים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה מציינים את מסך ההסכמה ש-Google מציגה למשתמש. היקפי הרשאות מאפשרים לאפליקציה לבקש גישה רק למשאבים הנדרשים, וגם מאפשרים למשתמשים לשלוט ברמת הגישה שהם מעניקים לאפליקציה. לכן, יש קשר הפוך בין מספר ההיקפים המבוקשים לבין הסבירות לקבלת הסכמת המשתמש. כשהדבר אפשרי, מומלץ שהאפליקציה תבקש גישה להיקפי הרשאות לפי הקשר. בקשת גישה לנתוני משתמשים בהקשר מסוים, באמצעות הרשאה מצטברת, תעזור למשתמשים להבין בקלות למה האפליקציה צריכה את הגישה שהיא מבקשת. |
||||||
state |
מומלץ
מציינת את כל ערך המחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות.
השרת מחזיר את הערך המדויק ששלחת כצמד אפשר להשתמש בפרמטר הזה לכמה מטרות, כמו להפנות את המשתמש
למשאב הנכון באפליקציה, שליחת נתונים חד-פעמיים (nonces) וצמצום זיוף בקשות בין אתרים. מכיוון שאפשר לנחש את |
||||||
include_granted_scopes |
אופציונלי
מאפשרת לאפליקציות להשתמש בהרשאה מצטברת כדי לבקש גישה להיקפים נוספים בהקשר. אם מגדירים לפרמטר הזה את הערך |
||||||
enable_granular_consent |
אופציונלי
ברירת המחדל היא |
||||||
login_hint |
אופציונלי
אם האפליקציה יודעת איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות, על ידי מילוי מראש של שדה האימייל בטופס הכניסה או על ידי בחירה בסשן המתאים של התחברות עם מספר חשבונות. מגדירים את ערך הפרמטר לכתובת אימייל או למזהה |
||||||
prompt |
אופציונלי
רשימת בקשות להצגת המשתמש מופרדת ברווחים ותלויות אותיות רישיות (case-sensitive). אם לא מציינים את הפרמטר הזה, המשתמש יקבל הודעה רק בפעם הראשונה שהפרויקט יבקש גישה. מידע נוסף זמין בקטע הצגת בקשה להסכמה מחדש. הערכים האפשריים הם:
|
||||||
דוגמה של הפניה אוטומטית לשרת ההרשאות של Google
בהמשך מוצגת כתובת URL לדוגמה, עם מעברי שורה ורווחים כדי להקל את הקריאה.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
אחרי שיוצרים את כתובת ה-URL של הבקשה, יש להפנות את המשתמש אליה.
קוד לדוגמה של JavaScript
קטע הקוד הבא של JavaScript מראה איך להפעיל את תהליך ההרשאה ב-JavaScript בלי להשתמש בספריית הלקוח של Google APIs ל-JavaScript. מכיוון שנקודת הקצה הזו של OAuth 2.0 לא תומכת בשיתוף משאבים בין מקורות (CORS), קטע הקוד יוצר טופס שפותח את הבקשה עבור נקודת הקצה הזאת.
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauthSignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create <form> element to submit parameters to OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': 'YOUR_CLIENT_ID',
'redirect_uri': 'YOUR_REDIRECT_URI',
'response_type': 'token',
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
'include_granted_scopes': 'true',
'state': 'pass-through value'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
שלב 2: Google מבקשת מהמשתמש את הסכמתו
בשלב הזה המשתמש מחליט אם להעניק לאפליקציה את הגישה המבוקשת. בשלב הזה, Google מציגה חלון הסכמה שבו מוצגים שם האפליקציה ושירותי Google API שהיא מבקשת גישה אליהם, עם פרטי הכניסה של המשתמש עם הרשאת המשתמש וסיכום של היקפי הגישה שצריך לקבל. לאחר מכן, המשתמש יוכל להסכים להעניק גישה להיקף הרשאות אחד או יותר שהאפליקציה שלך מבקשת, או לדחות את הבקשה.
בשלב זה, האפליקציה שלך לא צריכה לעשות דבר. היא ממתינה לתשובה משרת OAuth 2.0 של Google, שמציינת אם ניתנה גישה. התשובה הזו מוסברת בשלב הבא.
שגיאות
בבקשות לנקודת הקצה של הרשאת OAuth 2.0 של Google עשויות להופיע הודעות שגיאה שמוצגות למשתמשים במקום תהליכי האימות וההרשאות הצפויים. בהמשך מופיעים קודי שגיאות נפוצים והצעות לפתרונות.
admin_policy_enforced
לחשבון Google אין אפשרות להעניק הרשאה להיקפים מסוימים או יותר בגלל המדיניות של האדמין ב-Google Workspace. במאמר העזרה לאדמינים ב-Google Workspace אפשר לקרוא לקבוע לאילו אפליקציות של צד שלישי ואפליקציות פנימיות יש גישה לנתונים של Google Workspace למידע נוסף על האופן שבו אדמין יכול להגביל את הגישה לכל ההיקפים או להיקפים רגישים ומוגבלים עד שתוענק גישה מפורשת למזהה הלקוח ב-OAuth שלך.
disallowed_useragent
נקודת הקצה להרשאה מוצגת בתוך סוכן משתמש מוטמע שאסור לשימוש לפי מדיניות OAuth 2.0 של Google.
Android
מפתחי Android עשויים לראות את הודעת השגיאה הזו כשפותחים בקשות הרשאה ב-android.webkit.WebView.
במקום זאת, מפתחים צריכים להשתמש בספריות ל-Android, כמו כניסה באמצעות חשבון Google ל-Android או AppAuth ל-Android של OpenID Foundation.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-Android פותחת קישור אינטרנט כללי לסוכן משתמש מוטמע, ומשתמש עובר לנקודת הקצה של הרשאת OAuth 2.0 של Google מהאתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler שמוגדר כברירת מחדל לקישורים של מערכת ההפעלה, שכולל גם את רכיבי ה-handler של קישורים לאפליקציות ל-Android או את אפליקציית ברירת המחדל לדפדפן. גם ספריית הכרטיסיות המותאמות אישית ב-Android נתמכת.
iOS
מפתחים של iOS ו-macOS עשויים להיתקל בשגיאה הזו כשפותחים בקשות הרשאה ב-WKWebView.
במקום זאת, מפתחים צריכים להשתמש בספריות של iOS, כמו כניסה באמצעות חשבון Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.
מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-iOS או ל-macOS פותחת קישור אינטרנט כללי לסוכן משתמש מוטמע, ומשתמש עובר לנקודת הקצה של הרשאת OAuth 2.0 של Google מהאתר שלך. המפתחים צריכים לאפשר פתיחה של קישורים כלליים ב-handler המוגדר כברירת מחדל לקישורים של מערכת ההפעלה, שכוללים את רכיבי ה-handler של הקישורים האוניברסליים או את אפליקציית ברירת המחדל לדפדפן. גם הספרייה SFSafariViewController נתמכת.
org_internal
מזהה הלקוח ב-OAuth שצוין בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google ב ארגון Google Cloud ספציפי. למידע נוסף על אפשרות ההגדרה הזו, אפשר לעיין בקטע סוג המשתמש במאמר העזרה 'הגדרת מסך ההסכמה ל-OAuth'.
invalid_client
המקור שממנו נשלחה הבקשה לא מורשה עבור הלקוח הזה. origin_mismatch.
invalid_grant
כשמשתמשים בהרשאה מצטברת (Incremental authorization), יכול להיות שתוקף האסימון פג או שתוקפו פג. צריך לאמת שוב את המשתמש ולבקש את הסכמתו לקבלת אסימונים חדשים. אם השגיאה הזו ממשיכה להופיע, צריך לוודא שהאפליקציה הוגדרה כראוי ושנעשה שימוש באסימונים ובפרמטרים הנכונים במסגרת הבקשה. אם לא, יכול להיות שחשבון המשתמש נמחק או הושבת.
origin_mismatch
הסכימה, הדומיין ו/או היציאה של ה-JavaScript שיצר את בקשת ההרשאה לא יכולים להתאים ל-URI מורשה של מקור JavaScript שרשום עבור מזהה הלקוח ב-OAuth. ניתן לבדוק מקורות מורשים של JavaScript ב Google API Console Credentials page.
redirect_uri_mismatch
הערך redirect_uri שהועבר בבקשת ההרשאה לא תואם ל-URI מורשה להפניה אוטומטית עבור מזהה הלקוח ב-OAuth. יש לבדוק מזהי URI מורשים להפניה אוטומטית ב- Google API Console Credentials page.
הסכימה, הדומיין ו/או היציאה של ה-JavaScript שיצר את בקשת ההרשאה לא יכולים להתאים ל-URI מורשה של מקור JavaScript שרשום עבור מזהה הלקוח ב-OAuth. ניתן לבדוק מקורות מורשים של JavaScript ב Google API Console Credentials page.
הפרמטר redirect_uri עשוי להתייחס לתהליך OAuth מחוץ למסגרת (OOB) שהוצאה משימוש ואינה נתמכת יותר. ניתן לעיין
במדריך להעברת נתונים כדי לעדכן את
השילוב.
invalid_request
יש בעיה בבקשה ששלחת. יכולות להיות לכך כמה סיבות:
- פורמט הבקשה שגוי
- בבקשה היו חסרים פרמטרים נדרשים
- הבקשה משתמשת בשיטת הרשאה שאינה נתמכת על ידי Google. אימות של שילוב OAuth באמצעות שיטת שילוב מומלצת
שלב 3: טיפול בתגובת השרת של OAuth 2.0
נקודות קצה של OAuth 2.0
שרת OAuth 2.0 שולח תגובה ל-redirect_uri שצוין
בבקשה לאסימון הגישה.
אם המשתמש מאשר את הבקשה, התשובה תכיל אסימון גישה. אם המשתמש לא מאשר את הבקשה, התשובה תכיל הודעת שגיאה. אסימון הגישה או הודעת השגיאה מוחזרים בקטע ה-hash של ה-URI של ההפניה, כפי שמוצג כאן:
התגובה של אסימון הגישה:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
בנוסף לפרמטר
access_token, מחרוזת המקטע מכילה גם את הפרמטרtoken_typeשמוגדר תמיד כ-Bearer, ואת הפרמטרexpires_in, שמציין את משך החיים של האסימון בשניות. אם הפרמטרstateצוין בבקשה לאסימון גישה, הערך שלו ייכלל גם בתגובה.- תגובה עם שגיאה:
https://oauth2.example.com/callback#error=access_denied
דוגמה לתגובה משרת OAuth 2.0
תוכלו לבדוק את התהליך על ידי לחיצה על כתובת ה-URL לדוגמה הבאה, שמבקשת גישת קריאה בלבד להצגת מטא-נתונים של קבצים ב-Google Drive:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
אחרי השלמת התהליך של OAuth 2.0, המערכת תפנה אותך אל
http://localhost/oauth2callback. כתובת ה-URL הזו תניב
שגיאת 404 NOT FOUND, אלא אם המכונה המקומית שלך תציג קובץ
בכתובת הזו. בשלב הבא נספק פרטים נוספים על המידע שמוחזר ב-URI כשהמשתמש מופנה חזרה לאפליקציה.
קריאה ל-Google APIs
נקודות קצה של OAuth 2.0
אחרי שהאפליקציה תקבל אסימון גישה, ניתן יהיה להשתמש באסימון כדי לבצע קריאות ל-Google API מטעם חשבון משתמש מסוים, אם היקפי הגישה הנדרשים ל-API הוענקו. כדי לעשות את זה, צריך לכלול
את אסימון הגישה בבקשה ל-API באמצעות פרמטר שאילתה access_token או ערך Bearer של כותרת HTTP Authorization. כשניתן, כותרת ה-HTTP עדיפה, כי מחרוזות השאילתה מופיעות בדרך כלל ביומני השרתים. ברוב המקרים, תוכלו להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, כשקוראים ל-Drive Files API).
אתם יכולים לנסות את כל ממשקי Google API ולראות את ההיקף שלהם במגרש המשחקים של OAuth 2.0.
דוגמאות ל-HTTP GET
קריאה לנקודת הקצה
drive.files (ה-Drive Files API) באמצעות כותרת ה-HTTP Authorization: Bearer עשויה להיראות כך. שימו לב שעליכם לציין אסימון גישה משלכם:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
הנה קריאה לאותו API עבור המשתמש המאומת באמצעות הפרמטר access_token של מחרוזת השאילתה:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl דוגמאות
אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה לאפשרות של כותרת HTTP (השדה המועדף):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
לחלופין, אפשר לבחור את אפשרות הפרמטר של מחרוזת השאילתה:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
קוד לדוגמה של JavaScript
קטע הקוד הבא מדגים איך להשתמש ב-CORS (שיתוף משאבים ממקורות שונים) כדי לשלוח בקשה ל-Google API. בדוגמה הזו לא נעשה שימוש בספריית הלקוח של Google APIs עבור JavaScript. עם זאת, גם אם אתם לא משתמשים בספריית הלקוח, סביר להניח שמדריך התמיכה ב-CORS במסמכים של הספרייה יעזור לכם להבין טוב יותר את הבקשות האלה.
בקטע הקוד הזה, המשתנה access_token מייצג את האסימון שקיבלת כדי לשלוח בקשות API בשם המשתמש המורשה. הדוגמה המלאה מדגימה איך לאחסן את האסימון באחסון המקומי של הדפדפן ולאחזר אותו כששולחים בקשת API.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
console.log(xhr.response);
};
xhr.send(null);
דוגמה מלאה
נקודות קצה של OAuth 2.0
דוגמת הקוד הזו מדגימה איך להשלים את תהליך OAuth 2.0 ב-JavaScript בלי להשתמש בספריית הלקוח של Google APIs ל-JavaScript. הקוד מיועד לדף HTML עם לחצן לניסיון של בקשת API. כשלוחצים על הלחצן, הקוד בודק אם בדף מאוחסן אסימון גישה של API באחסון המקומי של הדפדפן. אם כן, הוא מריץ את בקשת ה-API. אחרת, הוא יתחיל את תהליך OAuth 2.0.
עבור תהליך OAuth 2.0, הדף פועל לפי השלבים הבאים:
- המערכת מפנה את המשתמשים לשרת OAuth 2.0 של Google, שמבקש גישה להיקף של
https://www.googleapis.com/auth/drive.metadata.readonly. - לאחר מתן גישה (או דחייה) של גישה להיקף מבוקש אחד או יותר, המשתמש מופנה לדף המקורי שמנתח את אסימון הגישה ממחרוזת מזהה המקטע.
הדף משתמש באסימון הגישה כדי לבצע את בקשת ה-API לדוגמה.
בקשת ה-API קוראת ל-method
about.getשל ה-Drive API כדי לאחזר מידע על חשבון Google Drive של המשתמש המורשה.- אם הבקשה תתבצע בהצלחה, תגובת ה-API תתועד במסוף ניפוי הבאגים של הדפדפן.
אפשר לבטל את הגישה לאפליקציה דרך הדף Permissions של חשבון Google. האפליקציה תופיע כהדגמה של OAuth 2.0 ל-Google API Docs.
כדי להריץ את הקוד הזה באופן מקומי, צריך להגדיר ערכים למשתנים YOUR_CLIENT_ID ו-YOUR_REDIRECT_URI שתואמים לפרטי הכניסה להרשאות. צריך להגדיר את המשתנה YOUR_REDIRECT_URI לאותה כתובת URL שבה הדף מוצג. הערך צריך להיות זהה לאחד ממזהי ה-URI המורשים להפניה אוטומטית בלקוח OAuth 2.0 שהגדרת ב- API Console Credentials page. אם
הערך הזה לא תואם ל-URI מורשה, תתקבל השגיאה redirect_uri_mismatch. בנוסף, עליכם להפעיל את ה-API המתאים בפרויקט הזה.
<html><head></head><body>
<script>
var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
var fragmentString = location.hash.substring(1);
// Parse query string to see if page request is coming from OAuth 2.0 server.
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
if (params['state'] && params['state'] == 'try_sample_request') {
trySampleRequest();
}
}
// If there's an access token, try an API request.
// Otherwise, start OAuth 2.0 flow.
function trySampleRequest() {
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
if (params && params['access_token']) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/drive/v3/about?fields=user&' +
'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
if (xhr.readyState === 4 && xhr.status === 200) {
console.log(xhr.response);
} else if (xhr.readyState === 4 && xhr.status === 401) {
// Token invalid, so prompt for user permission.
oauth2SignIn();
}
};
xhr.send(null);
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// Google's OAuth 2.0 endpoint for requesting an access token
var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';
// Create element to open OAuth 2.0 endpoint in new window.
var form = document.createElement('form');
form.setAttribute('method', 'GET'); // Send as a GET request.
form.setAttribute('action', oauth2Endpoint);
// Parameters to pass to OAuth 2.0 endpoint.
var params = {'client_id': YOUR_CLIENT_ID,
'redirect_uri': YOUR_REDIRECT_URI,
'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
'state': 'try_sample_request',
'include_granted_scopes': 'true',
'response_type': 'token'};
// Add form parameters as hidden input values.
for (var p in params) {
var input = document.createElement('input');
input.setAttribute('type', 'hidden');
input.setAttribute('name', p);
input.setAttribute('value', params[p]);
form.appendChild(input);
}
// Add form to page and submit it to open the OAuth 2.0 endpoint.
document.body.appendChild(form);
form.submit();
}
</script>
<button onclick="trySampleRequest();">Try sample request</button>
</body></html>
כללי אימות המקור ב-JavaScript
Google מחילה את כללי האימות הבאים על מקורות של JavaScript כדי לעזור למפתחים לשמור על אבטחת האפליקציות שלהם. מקורות ה-JavaScript חייבים לפעול בהתאם לכללים האלה. ההגדרות של דומיין, מארח וסכימה, מתוארות בהמשך בסעיף 3986 של RFC 3986.
| כללי אימות | |
|---|---|
| סכמה |
מקורות של JavaScript חייבים להשתמש בסכמת HTTPS, ולא ב-HTTP פשוט. מזהי URI של Localhost (כולל מזהי URI של כתובות IP של מארח מקומי) פטורים מהכלל הזה. |
| מארח |
מארחים לא יכולים להיות כתובות IP גולמיות. כתובות IP של מארח מקומי פטורות מהכלל הזה. |
| דומיין |
“googleusercontent.com”.goo.gl),
אלא אם הדומיין בבעלות האפליקציה. |
| פרטי משתמש |
מקורות של JavaScript לא יכולים להכיל את רכיב המשנה של פרטי המשתמש. |
| נתיב |
מקורות JavaScript לא יכולים להכיל את רכיב הנתיב. |
| שאילתה |
מקורות של JavaScript לא יכולים להכיל את רכיב השאילתה. |
| מקטע |
מקורות JavaScript לא יכולים להכיל את רכיב המקטע. |
| תווים |
מקורות של JavaScript לא יכולים להכיל תווים מסוימים, כולל:
|
הרשאה מצטברת
בפרוטוקול OAuth 2.0, האפליקציה מבקשת הרשאה לגשת למשאבים, שמזוהים באמצעות היקפי ההרשאות. החוויה של משתמש היא השיטה המומלצת לבקש הרשאה למשאבים ברגעים שבהם אתם צריכים אותם. כדי להפעיל את השיטה הזו, שרת ההרשאות של Google תומך בהרשאות מצטברות. התכונה הזו מאפשרת לבקש היקפים לפי הצורך, ואם המשתמש מעניק הרשאה להיקף החדש, מחזיר קוד הרשאה שניתן להחליף אותו באסימון שמכיל את כל ההיקפים שהמשתמש העניק לפרויקט.
לדוגמה, לאפליקציה שמאפשרת לאנשים לדגום טראקים של מוזיקה וליצור מיקסים יכול להיות שיהיו מעט מאוד משאבים בזמן הכניסה, למשל שם האדם שנכנס לחשבון. עם זאת, כדי לשמור מיקס שהושלם, תידרש גישה ל-Google Drive שלהם. לרוב האנשים ירגישו שזה טבעי אם הם ביקשו גישה ל-Google Drive שלהם רק בזמן שהאפליקציה הייתה צריכה אותה.
במקרה כזה, בזמן הכניסה האפליקציה עשויה לבקש מההיקפים openid ו-profile לבצע כניסה בסיסית, ואז לבקש את ההיקף https://www.googleapis.com/auth/drive.file בזמן הבקשה הראשונה כדי לשמור שילוב.
הכללים הבאים חלים על אסימון גישה שהתקבל מהרשאה מצטברת:
- ניתן להשתמש באסימון כדי לגשת למשאבים שתואמים לכל אחד מההיקפים שהושקו בהרשאה המשולבת החדשה.
- כשמשתמשים באסימון הרענון עבור ההרשאה המשולבת לקבלת אסימון גישה, אסימון הגישה מייצג את ההרשאה המשולבת ואפשר להשתמש בו עבור כל אחד מערכי
scopeשכלולים בתגובה. - ההרשאה המשולבת כוללת את כל היקפי ההרשאות שהמשתמש העניק לפרויקט ה-API, גם אם בקשות למענקים התבקשו מלקוחות שונים. לדוגמה, אם משתמש העניק גישה להיקף אחד באמצעות לקוח למחשב של אפליקציה, ולאחר מכן העניק היקף אחר לאותה אפליקציה דרך לקוח לנייד, ההרשאה המשולבת תכלול את שני ההיקפים.
- אם מבטלים אסימון שמייצג הרשאה משולבת, בו-זמנית גם תבוטל הגישה לכל ההיקפים של ההרשאה בשם המשתמש המשויך.
דוגמאות הקוד הבאות מראות איך להוסיף היקפים לאסימון גישה קיים. כך לא צריך לנהל כמה אסימוני גישה לאפליקציה.
נקודות קצה של OAuth 2.0
כדי להוסיף היקפים לאסימון גישה קיים, צריך לכלול את הפרמטר include_granted_scopes בבקשה לשרת OAuth 2.0 של Google.
קטע הקוד הבא מדגים כיצד לעשות זאת. קטע הקוד מניח ששמרתם את ההיקפים שעבורם אסימון הגישה תקף באחסון המקומי של הדפדפן. (בקוד הדוגמה המלאה נשמרת רשימה של היקפים שעבורם אסימון הגישה תקף, על ידי הגדרת המאפיין oauth2-test-params.scope באחסון המקומי של הדפדפן).
קטע הקוד משווה בין ההיקפים שבהם אסימון הגישה חוקי לבין ההיקף שבו רוצים להשתמש בשאילתה מסוימת. אם אסימון הגישה לא מכסה את ההיקף הזה, התהליך של OAuth 2.0 מתחיל.
כאן, הפונקציה oauth2SignIn זהה לזו שסופקה בשלב 2 (ומופיעה מאוחר יותר בדוגמה
המלאה).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
var scopes = params['scope'].split(' ');
for (var s = 0; s < scopes.length; s++) {
if (SCOPE == scopes[s]) {
current_scope_granted = true;
}
}
}
if (!current_scope_granted) {
oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
// Since you already have access, you can proceed with the API request.
}
ביטול אסימון
במקרים מסוימים, משתמש יכול לבטל את הגישה שניתנה לאפליקציה. המשתמשים יכולים לבטל את הגישה דרך הגדרות החשבון. לקבלת מידע נוסף, אפשר לעיין במסמך התמיכה הסרת גישה של אתר או אפליקציה מאתרים ואפליקציות של צד שלישי שיש להם גישה לחשבון שלך.
אפליקציה יכולה גם לבטל באופן פרוגרמטי את הגישה שניתנה לה. ביטול פרוגרמטי חשוב במקרים שבהם משתמש מבטל את ההרשמה, מסיר אפליקציה או שמשאבי ה-API הנדרשים לאפליקציה השתנו באופן משמעותי. במילים אחרות, חלק מתהליך ההסרה יכול לכלול בקשת API כדי לוודא שההרשאות שניתנו לאפליקציה בעבר יוסרו.
נקודות קצה של OAuth 2.0
כדי לבטל אסימון באופן פרוגרמטי, האפליקציה שולחת בקשה ל-https://oauth2.googleapis.com/revoke וכוללת את האסימון כפרמטר:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון רענון תואם, גם אסימון הרענון יבוטל.
אם הביטול מעובד בהצלחה, קוד סטטוס ה-HTTP של התשובה הוא 200. במצבי שגיאה, מוחזר קוד המצב 400 של HTTP יחד עם קוד שגיאה.
קטע הקוד הבא של JavaScript מראה איך לבטל אסימון ב-JavaScript בלי להשתמש
בספריית הלקוח של Google APIs עבור JavaScript. מכיוון שנקודת הקצה של OAuth 2.0 של Google לביטול אסימונים לא תומכת בשיתוף משאבים בין מקורות (CORS), הקוד יוצר טופס ושולח את הטופס לנקודת הקצה במקום להשתמש בשיטה XMLHttpRequest() כדי לפרסם את הבקשה.
function revokeAccess(accessToken) {
// Google's OAuth 2.0 endpoint for revoking access tokens.
var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
// Create <form> element to use to POST data to the OAuth 2.0 endpoint.
var form = document.createElement('form');
form.setAttribute('method', 'post');
form.setAttribute('action', revokeTokenEndpoint);
// Add access token to the form so it is set as value of 'token' parameter.
// This corresponds to the sample curl request, where the URL is:
// https://oauth2.googleapis.com/revoke?token={token}
var tokenField = document.createElement('input');
tokenField.setAttribute('type', 'hidden');
tokenField.setAttribute('name', 'token');
tokenField.setAttribute('value', accessToken);
form.appendChild(tokenField);
// Add form to page and submit it to actually revoke the token.
document.body.appendChild(form);
form.submit();
}