‫OAuth 2.0 לאפליקציות למחשב

במסמך הזה מוסבר איך אפליקציות למחשב (כמו אפליקציות שפועלות ב-Windows, ב-macOS או ב-Linux, או כלים של ממשק שורת הפקודה (CLI)) משתמשות בנקודות הקצה (endpoints) של Google ל-OAuth 2.0 כדי לאשר גישה לממשקי Google API.

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

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

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

ספריות ודוגמאות

כשמטמיעים את OAuth 2.0 באפליקציות למחשב, מומלץ להשתמש בספריות הלקוח של Google API בשפת התכנות שלכם (למשל Python, ‏ Java, ‏ Node.js, ‏ Go,‏ NET.‏). ספריות הלקוח מטפלות בהרשאות המשתמשים ובניהול האסימונים, וכך מפשטות את ההטמעה ומפחיתות את הסיכוי לשגיאות בהשוואה לשימוש ישיר בנקודות הקצה של HTTP/REST ברמה נמוכה יותר.

אם מדובר באפליקציות לנייד, עיינו במדריכי ההרשאות ל-Android ול-iOS.

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

דרישות מוקדמות

הפעלת ממשקי API בפרויקט

בכל אפליקציה ששולחת קריאות ל-Google APIs צריך להפעיל את ממשקי ה-API האלה בקונסולה לממשקי API.

כדי להפעיל API בפרויקט:

  1. פותחים את ספריית ה-API ב-Google API Console.
  2. אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.
  3. בספריית ה-API מופיעים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת מוצרים ופופולריות. אם ה-API שרוצים להפעיל לא מופיע ברשימה, מחפשים אותו או לוחצים על View All במשפחת המוצרים שאליה הוא שייך.
  4. בוחרים את ה-API שרוצים להפעיל ולוחצים על הכפתור Enable.
  5. אם מוצגת בקשה, מפעילים את החיוב.
  6. אם מוצגת בקשה, קוראים את התנאים וההגבלות של ה-API ומאשרים אותם.

יצירת פרטי כניסה לאימות

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

  1. נכנסים לדף Clients.
  2. לוחצים על Create client.
  3. בוחרים בסוג האפליקציה אפליקציה למחשב.
  4. בשדה Name, מזינים שם ללקוח OAuth. השם הזה מוצג בדף Clients של הפרויקט כדי לזהות את הלקוח.
  5. לוחצים על יצירה.

מזהה הלקוח וסוד הלקוח נוצרים ומוצגים במסוף Google Cloud. אפליקציות למחשב הן לקוחות ציבוריים ולא יכולות לשמור על סודיות. תמיד צריך להשתמש ב-PKCE (Proof Key for Code Exchange) כשמבקשים קודי הרשאה.

זיהוי היקפי הגישה

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

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

במסמך היקפי ההרשאות של OAuth 2.0 API מפורטת רשימה מלאה של היקפי ההרשאות שבהם אפשר להשתמש כדי לגשת לממשקי Google API.

איך מקבלים טוקני גישה מסוג OAuth 2.0

השלבים הבאים מראים איך האפליקציה יוצרת אינטראקציה עם שרת OAuth 2.0 של Google כדי לקבל את הסכמת המשתמש לביצוע בקשת API בשמו. האפליקציה צריכה לקבל את ההסכמה הזו לפני שהיא יכולה לבצע בקשת Google API שדורשת הרשאת משתמש.

שלב 1: יצירת מאמת קוד ואתגר

‫Google תומכת בפרוטוקול Proof Key for Code Exchange (PKCE) כדי להפוך את תהליך ההתקנה של האפליקציה למאובטח יותר. לכל בקשת הרשאה נוצר מאמת קוד ייחודי, והערך שעבר טרנספורמציה, שנקרא code_challenge, נשלח לשרת ההרשאות כדי לקבל את קוד ההרשאה.

יצירת מאמת הקוד

‫code_verifier הוא מחרוזת אקראית קריפטוגרפית עם אנטרופיה גבוהה, שמשתמשת בתווים הלא שמורים [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", באורך מינימלי של 43 תווים ובאורך מקסימלי של 128 תווים.

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

יצירת אתגר הקוד

יש שתי שיטות נתמכות ליצירת אתגר הקוד.

שיטות ליצירת אתגר קוד
S256 (מומלץ) ה-code challenge הוא גיבוב SHA256 של ה-code verifier, שמקודד בפורמט Base64URL (ללא ריפוד).
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain הערך של אתגר הקוד זהה לערך של מאמת הקוד שנוצר למעלה.
code_challenge = code_verifier

שלב 2: שליחת בקשה לשרת OAuth 2.0 של Google

כדי לקבל הרשאה מהמשתמש, שולחים בקשה לשרת ההרשאות של Google בכתובת https://accounts.google.com/o/oauth2/v2/auth. נקודת הקצה הזו מטפלת בחיפוש סשן פעיל, מאמתת את המשתמש ומקבלת את הסכמת המשתמש. אפשר לגשת לנקודת הקצה רק באמצעות SSL, והיא דוחה חיבורי HTTP (ללא SSL).

שרת ההרשאות תומך בפרמטרים הבאים של מחרוזת השאילתה לאפליקציות מותקנות:

פרמטרים
client_id חובה

מזהה הלקוח של האפליקציה. הערך הזה מופיע בדף Clients במסוף Cloud.

redirect_uri חובה

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

הערך חייב להיות זהה לאחד ממזהי ה-URI המורשים להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם בדף Clients במסוף Cloud של הלקוח. אם הערך הזה לא תואם ל-URI מורשה, תופיע השגיאה redirect_uri_mismatch.

בטבלה מוצג ערך הפרמטר redirect_uri המתאים לכל שיטה:

‫redirect_uri ערכים
סכמת URI בהתאמה אישית com.example.app:redirect_uri_path

או

com.googleusercontent.apps.123:redirect_uri_path
  • ‫com.example.app הוא סימון ה-DNS ההפוך של דומיין שבשליטתכם. הסכימה בהתאמה אישית חייבת להכיל נקודה כדי להיות תקינה.
  • ‫com.googleusercontent.apps.123 הוא הסימון ההפוך של ה-DNS של מזהה הלקוח.
  • ‫redirect_uri_path הוא רכיב נתיב אופציונלי, כמו /oauth2redirect. שימו לב שהנתיב צריך להתחיל בלוכסן אחד, בניגוד לכתובות URL רגילות מסוג HTTP.
כתובת IP של לולאה חוזרת ‫http://127.0.0.1:port או http://[::1]:port

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

שימו לב שהתמיכה באפשרות ההפניה לכתובת ה-IP של הלולאה החוזרת (loopback) באפליקציות לנייד הוצאה משימוש.

response_type חובה

קובע אם נקודת הקצה של Google OAuth 2.0 מחזירה קוד הרשאה.

מגדירים את ערך הפרמטר ל-code באפליקציות מותקנות.

scope חובה

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

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

code_challenge מומלץ

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

code_challenge_method מומלץ

מציין באיזו שיטה השתמשו כדי לקודד code_verifier שישמש במהלך החלפת קוד ההרשאה. חובה להשתמש בפרמטר הזה עם הפרמטר code_challenge. ערך ברירת המחדל של code_challenge_method הוא plain אם הוא לא קיים בבקשה שכוללת code_challenge. הערכים הנתמכים היחידים עבור פרמטר זה הם S256 או plain.

state מומלץ

מציין ערך מחרוזת כלשהו שהאפליקציה משתמשת בו כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות. השרת מחזיר את הערך המדויק ששלחתם כצמד name=value במזהה הפרגמנט של כתובת ה-URL‏ (#) של redirect_uri אחרי שהמשתמש מאשר או דוחה את בקשת הגישה של האפליקציה.

אפשר להשתמש בפרמטר הזה למספר מטרות, כמו הפניית המשתמש למשאב הנכון באפליקציה, שליחת מספרים חד-פעמיים (nonce) והפחתת הסיכון לזיוף בקשות בין אתרים. מכיוון שאפשר לנחש את redirect_uri, שימוש בערך state יכול להגביר את הוודאות שהחיבור הנכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים את ה-hash של קובץ cookie או ערך אחר שמתעד את מצב הלקוח, אפשר לאמת את התגובה כדי לוודא שהבקשה והתגובה הגיעו מאותו דפדפן, וכך להגן מפני התקפות כמו זיוף בקשות בין אתרים. במסמכי התיעוד של OpenID Connect מופיעה דוגמה ליצירה ולאימות של אסימון state.

login_hint אופציונלי

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

מגדירים את ערך הפרמטר לכתובת אימייל או למזהה sub, ששווה ערך למזהה Google של המשתמש.

דוגמאות לכתובות URL להרשאה

בכרטיסיות שבהמשך מוצגות כתובות URL לדוגמה להרשאה, לאפשרויות השונות של כתובות URI להפניה אוטומטית.

כתובות ה-URL זהות, מלבד הערך של הפרמטר redirect_uri. כתובות ה-URL מכילות גם את הפרמטרים הנדרשים response_type ו-client_id, וגם את הפרמטר האופציונלי state. כל כתובת URL מכילה מעברי שורה ורווחים כדי שיהיה קל יותר לקרוא אותה.

סכמת URI מותאמת אישית

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

כתובת IP של לולאה חוזרת (loopback)

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

שלב 3: 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

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

מפתחים ב-iOS וב-macOS עלולים להיתקל בשגיאה הזו כשהם פותחים בקשות הרשאה ב-WKWebView. במקום זאת, המפתחים צריכים להשתמש בספריות iOS כמו כניסה באמצעות חשבון Google ל-iOS או AppAuth ל-iOS של OpenID Foundation.

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

org_internal

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

deleted_client

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

invalid_grant

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

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

redirect_uri_mismatch

הערך של redirect_uri שהועבר בבקשת ההרשאה לא תואם לכתובת URI מורשית להפניה אוטומטית של מזהה הלקוח ב-OAuth. בודקים את כתובות ה-URI המורשות להפניה אוטומטית בדף Clients במסוף Google Cloud.

יכול להיות שהערך של redirect_uri שהועבר לא תקין לסוג הלקוח.

יכול להיות שהפרמטר redirect_uri מתייחס לתהליך OAuth מחוץ לתחום (OOB) שהוצא משימוש ולא נתמך יותר. כדי לעדכן את השילוב, צריך לפעול לפי המדריך להעברת נתונים (מיגרציה).

invalid_request

הייתה בעיה בבקשה ששלחת. יכולות להיות לכך כמה סיבות:

  • הפורמט של הבקשה לא תקין
  • בבקשה חסרים פרמטרים נדרשים
  • הבקשה משתמשת בשיטת הרשאה ש-Google לא תומכת בה. מוודאים ששילוב ה-OAuth משתמש בשיטת שילוב מומלצת
  • נעשה שימוש בסכימה מותאמת אישית שלא נתמכת בכתובת ה-URI להפניה אוטומטית. אם מוצגת הודעת השגיאה סכימת URI בהתאמה אישית לא נתמכת באפליקציות ל-Android או ל-Chrome, כאן אפשר לקרוא מידע נוסף על חלופות לסכימת URI בהתאמה אישית.

שלב 4: טיפול בתגובה של שרת OAuth 2.0

האופן שבו האפליקציה מקבלת את תגובת ההרשאה תלוי בסכמת ה-URI להפניה אוטומטית שבה היא משתמשת. לא משנה מה הסכימה, התשובה תכלול קוד הרשאה (code) או שגיאה (error). לדוגמה, error=access_denied מציין שהמשתמש דחה את הבקשה.

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

שלב 5: החלפת קוד ההרשאה בטוקנים לרענון ולגישה

כדי להחליף קוד הרשאה בטוקן גישה, צריך לשלוח קריאה לנקודת הקצה https://oauth2.googleapis.com/token ולהגדיר את הפרמטרים הבאים:

שדות
client_id מזהה הלקוח שהתקבל מדף הלקוחות במסוף Cloud.
client_secret אופציונלי

סוד הלקוח שהתקבל מדף הלקוחות במסוף Cloud.

code קוד ההרשאה שהוחזר מהבקשה הראשונית.
code_verifier ‫code verifier שיצרתם בשלב 1.
grant_type כפי שמוגדר במפרט של OAuth 2.0, הערך של השדה הזה חייב להיות authorization_code.
redirect_uri אחד ממזהי ה-URI להפניה אוטומטית שרשומים לפרויקט שלכם בדף הלקוחות במסוף Cloud, עבור client_id נתון.

השימוש ב-DPoP הוא אופציונלי, אבל מומלץ להשתמש בו כדי לשפר את האבטחה. האבטחה של DPoP מסתמכת על כך שהמפתח הפרטי מוגבל למכשיר אחד. מומלץ לאחסן אותו באופן שלא מאפשר להעתיק אותו מהמכשיר, למשל באמצעות TPM,‏ Secure Enclave או מאגרי מפתחות אחרים שמגובים בחומרה. כדי להשתמש ב-DPoP, האפליקציה צריכה ליצור אסימון JWT חדש וייחודי להוכחת DPoP לכל בקשה לנקודת הקצה של האסימון, ולהוסיף אותו ככותרת של בקשת HTTP.

כותרת חובה תיאור
DPoP אופציונלי הוכחת DPoP היא JWT שמוכיח את הבעלות על מפתח פרטי. זו כותרת, לא פרמטר. אם הוא מסופק, האסימונים שמוחזרים קשורים למפתח הזה. צריך ליצור הוכחה חדשה וייחודית לכל בקשה, והיא צריכה לכלול הצהרות htm (שיטת HTTP) ו-htu (מזהה URI של HTTP) שתואמות לבקשה.

בקטע הקוד הבא יש בקשה לדוגמה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiVkM5MXk5WllkZlNXYUR2OEphSTZneDVpZk93MnJuM1lkcWtBQjUxVXU2RSIsInkiOiJpa1BqT3RlYTRrN2ZXUFZyUll3YUE0V3c2aVZZM3BPT0lDb3RId3dHVjNvIn19.eyJqdGkiOiJvMjlDTjhMSVkwbF9OOGl5NS1pbG9uMWd1YWQ5TkZRSEZPZFhUenJCTmNrIiwiaHRtIjoiUE9TVCIsImh0dSI6Imh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwiaWF0IjoxNzg0ODIyMDI1fQ.OSdQCmqTng_uZmGK5UXf8hcEMtoOu7ucmYtl5mx4901RXnj6fJRJQmIeTqfhprRBTG_RSJv2fPcWDqvQbDW7YA

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

יצירת הוכחת DPoP

השלבים הבאים מראים איך ליצור הוכחת DPoP באמצעות OpenSSL משורת הפקודה:

  1. יצירת זוג מפתחות EC P-256:
    openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
    openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
  2. יוצרים את הכותרת של ה-DPoP:

    הכותרת חייבת לכלול את ההצהרות typ,‏ alg ו-jwk (מפתח ציבורי). הערכים x ו-y הם הקואורדינטות בקידוד Base64Url של המפתח הציבורי של ה-EC. מקודדים את ה-JSON הזה ב-Base64Url:

    {
      "typ":"dpop+jwt",
      "alg":"ES256",
      "jwk": {
        "kty":"EC",
        "x":"YOUR_PUBLIC_KEY_X",
        "y":"YOUR_PUBLIC_KEY_Y",
        "crv":"P-256"
      }
    }
  3. יוצרים את המטען הייעודי (payload) של ה-DPoP:

    המטען הייעודי (payload) חייב לכלול את jti (מזהה ייחודי של הבקשה), htm (שיטת HTTP, למשל POST), htu (HTTP URI, למשל https://oauth2.googleapis.com/token) ו- iat (הונפק בזמן). אם קיבלתם צופן חד-פעמי (nonce) מהשרת בכותרת DPoP-Nonce בתגובה לבקשה קודמת, אתם צריכים לכלול את ערך הצופן החד-פעמי (nonce) הזה בהצהרה nonce. הצהרת ה-nonce היא אופציונלית להחלפות של קודי הרשאה, ומשתמשים בה רק אם הכותרת DPoP-Nonce התקבלה בעבר. מקודדים את ה-JSON הזה ב-Base64Url:

    {
      "jti":"JTI_VALUE",
      "htm":"POST",
      "htu":"https://oauth2.googleapis.com/token",
      "iat":YOUR_JWT_ISSUED_TIME,
      "nonce":"SERVER_PROVIDED_NONCE"
    }

    הערך של jti תלוי בסוג ההחלפה:

    • בהחלפות של קודי הרשאה, הערך של jti צריך להיות הגיבוב (hash) של קוד ההרשאה בקידוד Base64Url לפי SHA256: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
    • בהחלפות של טוקן רענון, הערך של jti חייב להיות מזהה ייחודי לכל בקשה: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
  4. חותמים על ההוכחה:

    משרשרים את הכותרת המקודדת ואת המטען הייעודי (payload) עם נקודה (.), ואז חותמים על התוצאה באמצעות המפתח הפרטי באמצעות ES256. שימו לב שב-JWS החתימה צריכה להיות בפורמט משורשר גולמי של R | S (64 בייטים ל-P-256). אם משתמשים ב-OpenSSL ישירות, צריך להמיר את החתימה שקודדה ב-ASN.1 DER כברירת מחדל לפורמט הגולמי הזה.

החלפה מוצלחת מסומנת בתגובה 200 OK שמכילה את האסימונים. אם משתמשים בהוכחת DPoP תקינה במהלך ההחלפה, טוקן הרענון ש-Google מחזירה יהיה קשור ל-DPoP למפתח שלכם, אבל טוקני הגישה לא יהיו קשורים ל-DPoP. טוקני הגישה ישמרו על הערך token_type של Bearer במקום DPoP. בנוסף, Google מחזירה כותרת HTTP מסוג DPoP-Nonce בתגובה. הלקוח צריך לשמור את ה-nonce הזה במטמון ולכלול אותו בטענת הנכוֹנוּת (claim) של nonce בהוכחת ה-DPoP בבקשות הבאות (למשל, כשמחליפים טוקן רענון בטוקן גישה חדש, או כששולחים קריאה לממשקי API שמוגנים באמצעות DPoP). שימוש ב-nonce שהונפק מוקדם מאפשר להימנע משגיאה נוספת של הלוך ושוב (use_dpop_nonce) בבקשה הבאה.

צריך לכלול הוכחות DPoP בבקשות להחלפת טוקנים שבוצעו עם טוקני רענון שקשורים ל-DPoP.

החלפה נכשלת אם הכותרת DPoP חסרה כשהיא צפויה, לא חוקית או אם ההוכחה משתמשת במפתח שונה מזה שקשור לאסימון. במקרים כאלה, השרת מחזיר שגיאת 400 Bad Request. אם בהוכחת ה-DPoP יש טענות נכוֹנוּת (claims) לא תואמות של htm או htu, iat שפג תוקפו, jti לא תקין או חתימה לא תקינה, Google מחזירה קוד שגיאה invalid_dpop_proof. אם נדרש מספר חד-פעמי (nonce) של DPoP, למשל במהלך החלפה של טוקן רענון, ובאימות ה-DPoP חסרה הצהרה מסוג nonce, או שערך המספר החד-פעמי לא מקובל על השרת (לדוגמה, אם הוא פג תוקף או לא תקין), Google מחזירה קוד שגיאה use_dpop_nonce יחד עם כותרת HTTP מסוג DPoP-Nonce שמכילה מספר חד-פעמי חדש שאפשר להשתמש בו בבקשה הבאה. במקרים אחרים של כשל, יכול להיות שיוחזר הערך invalid_grant.

‫Google מגיבה לבקשה הזו ומחזירה אובייקט JSON שמכיל טוקן גישה לטווח קצר וטוקן רענון.

התשובה מכילה את השדות הבאים:

שדות
access_token האסימון שהאפליקציה שולחת כדי לאשר בקשת Google API.
expires_in משך החיים שנותר לאסימון הגישה, בשניות.
id_token הערה: המאפיין הזה מוחזר רק אם הבקשה כללה היקף זהות, כמו openid,‏ profile או email. הערך הוא אסימון JWT ‏(JSON Web Token) שמכיל פרטי זהות של המשתמש עם חתימה דיגיטלית.
refresh_token טוקן שמאפשר לקבל טוקן גישה חדש. טוקני הרענון תקפים עד שהמשתמש מבטל את הגישה או עד שתוקף הטוקן פג. אם נעשה שימוש ב-DPoP, טוקן הרענון מקושר למפתח הפרטי ששימש לחתימה על הוכחת ה-DPoP. שימו לב שתמיד מוחזרים טוקנים לרענון של אפליקציות מותקנות.
refresh_token_expires_in משך החיים שנותר לטוקן הרענון, בשניות. הערך הזה מוגדר רק כשהמשתמש מעניק גישה מבוססת-זמן.
scope היקפי הגישה שניתנו על ידי access_token, מבוטאים כרשימה של מחרוזות תלויות אותיות רישיות, שמופרדות ברווחים.
token_type סוג הטוקן שהוחזר. הערך הזה הוא תמיד Bearer, גם כשמשתמשים ב-DPoP.

קטע הקוד הבא מציג דוגמה לכותרות ולגוף של תגובה מוצלחת כשמשתמשים ב-DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

שלב 6: בודקים אילו היקפי הרשאות המשתמשים נתנו

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

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

למידע מפורט יותר, קראו את המאמר איך לטפל בהרשאות פרטניות.

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

לדוגמה, התגובה הבאה לדוגמה של טוקן גישה מציינת שהמשתמש העניק לאפליקציה גישה להרשאות לקריאה בלבד של פעילות ב-Drive ואירועים ביומן:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

קריאה ל-Google APIs

אחרי שהאפליקציה מקבלת טוקן גישה, אתם יכולים להשתמש בו כדי לבצע קריאות ל-Google API מטעם חשבון משתמש מסוים, אם ניתנו היקפי הגישה שה-API דורש. כדי לעשות את זה, צריך לכלול את טוקן הגישה בבקשה ל-API באמצעות הוספה של פרמטר השאילתה access_token או של ערך Bearer בכותרת ה-HTTP‏ Authorization. כשאפשר, עדיף להשתמש בכותרת HTTP, כי מחרוזות של שאילתות נוטות להופיע ביומני השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, כשקוראים ל-Drive Files API).

אתם יכולים לנסות את כל ממשקי ה-API של Google ולראות את היקפי ההרשאות שלהם ב-OAuth 2.0 Playground.

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה (endpoint) של drive.files (Drive Files API) באמצעות הכותרת Authorization: Bearer HTTP עשויה להיראות כך: שימו לב שאתם צריכים לציין את טוקן הגישה שלכם:

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

רענון של טוקן גישה

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

כדי לרענן אסימון גישה, האפליקציה שולחת בקשת HTTPS POST לשרת ההרשאות של Google‏ (https://oauth2.googleapis.com/token) שכוללת את הפרמטרים הבאים בגוף הבקשה:

שם ערך
client_id מזהה הלקוח שמתקבל מקונסולה לממשקי API.
client_secret אופציונלי

סוד הלקוח שהתקבל מקונסולה לממשקי API. (השדה client_secret לא רלוונטי לבקשות מלקוחות שרשומים כאפליקציות ל-Android, ל-iOS או ל-Chrome).

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

השימוש ב-DPoP הוא אופציונלי, אבל מומלץ להשתמש בו כדי לשפר את האבטחה. כדי להשתמש ב-DPoP עם טוקן רענון, האפליקציה צריכה ליצור JWT חדש וייחודי להוכחת DPoP לכל בקשה לנקודת הקצה של הטוקן. ההוכחה הזו חייבת להיות חתומה באותו מפתח פרטי ששימש במהלך ההחלפה הראשונית של קוד ההרשאה. האפליקציה מוסיפה את ההוכחה ככותרת של בקשת HTTP.

כותרת חובה תיאור
DPoP אופציונלי הוכחת DPoP היא JWT שמוכיח את הבעלות על מפתח פרטי. זו כותרת, לא פרמטר. אם הוא מסופק, האסימונים שמוחזרים קשורים למפתח הזה. צריך ליצור הוכחה חדשה וייחודית לכל בקשה, והיא צריכה לכלול הצהרות htm (שיטת HTTP) ו-htu (מזהה URI של HTTP) שתואמות לבקשה.

בקטע הקוד הבא יש בקשה לדוגמה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: DPOP_PROOF_JWT

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

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

החלפה מוצלחת מסומנת בתגובה 200 OK שמכילה אסימון גישה חדש. כשמשתמשים ב-DPoP, הערך של token_type הוא Bearer. תגובה מוצלחת מאשרת שהתקבל הוכחת ה-DPoP של טוקן הרענון. יכול להיות ש-Google תחזיר גם כותרת HTTP חדשה מסוג DPoP-Nonce בתגובה. אם היא מוחזרת, הלקוח צריך לשמור את ה-nonce הזה במטמון ולכלול אותו בטענת הנכוֹנוּת (claim) של nonce בהוכחת ה-DPoP בבקשות הבאות.

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

קטע הקוד הבא מציג דוגמה לכותרות ולגוף של תגובה מוצלחת כשמשתמשים ב-DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

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

ביטול טוקן

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

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

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

שיטות להפניה אוטומטית לאפליקציה

סכמת URI מותאמת אישית

סכמות URI בהתאמה אישית הן סוג של קישורי עומק שמשתמשים בסכמה מוגדרת בהתאמה אישית כדי לפתוח את האפליקציה.

חלופה לשימוש בסכימות URI בהתאמה אישית באפליקציות Chrome

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

כתובת IP של לולאה חוזרת (macOS, ‏ Linux, ‏ Windows למחשב)

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

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

שימוש מומלץ אפליקציות למחשב ב-macOS, ב-Linux וב-Windows
ערכי טופס מגדירים את סוג האפליקציה למחשב בתור Desktop app.

העתקה והדבקה ידנית (הוצא משימוש)

הגנה על האפליקציות

אימות הבעלות על האפליקציה ב-Chrome

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

כדי להשלים את תהליך האימות, צריך להשתמש בחשבון הפיתוח בחנות האינטרנט של Chrome. כדי שהאימות יצליח, צריך לעמוד בדרישות הבאות:

  • צריך להיות לכם פריט רשום במרכז השליטה למפתחים בחנות האינטרנט של Chrome עם אותו מזהה פריט כמו של לקוח OAuth של התוסף ל-Chrome שאתם מאמתים.
  • אתם צריכים להיות בעלי התוכן הדיגיטלי של הפריט בחנות האינטרנט של Chrome. מידע נוסף על ניהול הרשאות הגישה במרכז השליטה למפתחים בחנות האינטרנט של Chrome.

בקטע Verify App Ownership בלקוח של התוסף ל-Chrome, לוחצים על הכפתור Verify Ownership כדי להשלים את תהליך האימות.

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

אם האימות יצליח, תופיע הודעה שמאשרת את הצלחת תהליך האימות. אחרת, תוצג הודעת שגיאה.

אם האימות נכשל, נסו את הפתרונות הבאים:

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

גישה מבוססת-זמן

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

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

קריאה נוספת

השיטה המומלצת הנוכחית של IETF,‏ OAuth 2.0 for Native Apps, כוללת רבות מהשיטות המומלצות שמתוארות כאן.

הטמעת ההגנה על כל החשבונות

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

דוגמאות לסוגי האירועים ששירות ההגנה על כל החשבונות של Google שולח לאפליקציה:

  • https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
  • https://schemas.openid.net/secevent/oauth/event-type/token-revoked
  • https://schemas.openid.net/secevent/risc/event-type/account-disabled

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