במסמך הזה מוסבר איך להטמיע הרשאת 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
אם אתם משתמשים בספריית הלקוח של Google APIs ל-JavaScript כדי לבצע קריאות מורשות ל-Google, צריך להשתמש בספריית ה-JavaScript של Google Identity Services כדי לטפל בתהליך OAuth 2.0. מודל האסימון של שירותי הזהויות של Google מבוסס על תהליך הענקת הרשאה משתמע של 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 שרוצים להפעיל ולוחצים על הלחצן Enable (הפעלה).
- 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.
- לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
- בוחרים את סוג האפליקציה 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 |
חובה
מזהה הלקוח באפליקציה שלכם. הערך הזה מופיע ב Credentials page API Console. |
||||||
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 |
אופציונלי
ברירת המחדל היא כש-Google מפעילה הרשאות מפורטות לאפליקציה, לפרמטר הזה לא תהיה יותר השפעה. |
||||||
login_hint |
אופציונלי
אם האפליקציה שלכם יודעת איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות על ידי מילוי מראש של שדה האימייל בטופס הכניסה או בחירה בסשן המתאים עם כניסות מרובות. צריך להגדיר את ערך הפרמטר לכתובת אימייל או למזהה |
||||||
prompt |
אופציונלי
רשימה של הנחיות להצגת המשתמש, שמופרדת ברווחים ותלויות אותיות רישיות. אם לא מציינים את הפרמטר הזה, תוצג למשתמש בקשה רק בפעם הראשונה שהפרויקט יבקש גישה. מידע נוסף זמין במאמר הצגת בקשה להסכמה מחדש. הערכים האפשריים הם:
|
דוגמה של הפניה מחדש לשרת ההרשאות של 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 שמוגדר כברירת מחדל לקישורים של מערכת ההפעלה, שכולל גם את ה-handlers של קישורים לאפליקציות ל-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
כשמשתמשים בהרשאה מצטברת, יכול להיות שהתוקף של האסימון פג או שהוא לא תקף. צריך לאמת שוב את המשתמש ולבקש את הסכמת המשתמש כדי לקבל אסימונים חדשים. אם השגיאה ממשיכה להופיע, צריך לוודא שהאפליקציה שלך הוגדרה כמו שצריך ושנעשה שימוש באסימונים ובפרמטרים הנכונים בבקשה. אחרת, יכול להיות שחשבון המשתמש נמחק או הושבת.
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
או ערך Authorization
של כותרת HTTP Bearer
. כשאפשר, עדיף להשתמש בכותרת ה-HTTP, כי מחרוזות השאילתה מופיעות בדרך כלל ביומני השרת. ברוב המקרים,
אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה,
בקריאה ל-Drive Files API).
אפשר לנסות את כל ממשקי ה-API של Google ולראות את ההיקף שלהם ב-OAuth 2.0 Playground.
דוגמאות GET של HTTP
קריאה לנקודת הקצה
drive.files
(ה-API של Drive Files) באמצעות כותרת ה-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 מפעילה את השיטה
about.get
של Drive API כדי לאחזר מידע על חשבון Google Drive של המשתמש המורשה.- אם הבקשה תתבצע בהצלחה, תגובת ה-API תתועד במסוף ניפוי הבאגים של הדפדפן.
אפשר לבטל את הגישה לאפליקציה דרך הדף הרשאות בחשבון 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'; // Parse query string to see if page request is coming from OAuth 2.0 server. var fragmentString = location.hash.substring(1); var params = {}; var regex = /([^&=]+)=([^&]*)/g, m; while (m = regex.exec(fragmentString)) { params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]); } if (Object.keys(params).length > 0 && params['state']) { if (params['state'] == localStorage.getItem('state')) { localStorage.setItem('oauth2-test-params', JSON.stringify(params) ); trySampleRequest(); } else { console.log('State mismatch. Possible CSRF attack'); } } // Function to generate a random state value function generateCryptoRandomState() { const randomValues = new Uint32Array(2); window.crypto.getRandomValues(randomValues); // Encode as UTF-8 const utf8Encoder = new TextEncoder(); const utf8Array = utf8Encoder.encode( String.fromCharCode.apply(null, randomValues) ); // Base64 encode the UTF-8 data return btoa(String.fromCharCode.apply(null, utf8Array)) .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=+$/, ''); } // 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() { // create random state value and store in local storage var state = generateCryptoRandomState(); localStorage.setItem('state', state); // 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': state, '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 חייבים לעמוד בכללים האלה. ההגדרה של דומיין, מארח וסכימה מופיעה בהמשך בסעיף RFC 3986.
כללי אימות | |
---|---|
סכמה |
מקורות JavaScript חייבים להשתמש בסכמת HTTPS, ולא ב-HTTP פשוט. מזהי URI של מארחים מקומיים (כולל מזהי 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
. לתנאי שגיאה, מוחזר קוד מצב HTTP 400
יחד עם קוד שגיאה.
קטע הקוד הבא של 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(); }