‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

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

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

באפליקציות ל-iOS, מומלץ להשתמש בגרסה העדכנית של Sign In With Google iOS SDK. ה-SDK מטפל בהרשאת המשתמשים, וקל יותר להטמיע אותו מאשר את הפרוטוקול ברמה הנמוכה יותר שמתואר במדריך הזה.

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

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

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

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

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

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

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

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

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

iOS

בוחרים את סוג האפליקציה iOS.
מזינים שם ללקוח OAuth. השם הזה מוצג בדף Clients של הפרויקט כדי לזהות את הלקוח.
מזינים את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של המפתח CFBundleIdentifier בקובץ המשאבים של רשימת מאפייני המידע של האפליקציה (info.plist). הערך מוצג בדרך כלל בחלונית General או בחלונית Signing & Capabilities של עורך הפרויקטים ב-Xcode. מזהה החבילה מוצג גם בקטע General Information (מידע כללי) בדף App Information (מידע על האפליקציה) של האפליקציה באתר App Store Connect של אפל.
חשוב לוודא שמשתמשים במזהה החבילה הנכון של האפליקציה, כי לא תהיה אפשרות לשנות אותו אם משתמשים בתכונה App Check.
(אופציונלי)
אם האפליקציה פורסמה ב-App Store של אפל, מזינים את מזהה האפליקציה ב-App Store. מזהה החנות הוא מחרוזת מספרית שכלולה בכל כתובת URL של Apple App Store.
1. פותחים את אפליקציית Apple App Store במכשיר iOS או iPadOS.
2. מחפשים את האפליקציה.
3. לוחצים על כפתור השיתוף (סמל של ריבוע וחץ למעלה).
4. לוחצים על העתקת הקישור.
5. מדביקים את הקישור בכלי לעריכת טקסט. מזהה ה-App Store הוא החלק האחרון של כתובת ה-URL.
  לדוגמה: https://apps.apple.com/app/google/id284815942
(אופציונלי)
מזינים את מזהה הצוות. למידע נוסף, עיינו בקטע Locate your Team ID במסמכי התיעוד של חשבון הפיתוח ב-Apple.
הערה: השדה "מזהה צוות" נדרש אם מפעילים את App Check עבור הלקוח.
(אופציונלי)
מפעילים את App Check באפליקציה ל-iOS. כשמפעילים את App Check, שירות App Attest של אפל משמש לאימות של בקשות OAuth 2.0 שמגיעות מלקוח OAuth, כדי לוודא שהן אמיתיות ומגיעות מהאפליקציה שלכם. כך אפשר לצמצם את הסיכון להתחזות לאפליקציה. מידע נוסף על הפעלת App Check באפליקציה ל-iOS
לוחצים על יצירה.

מחשב

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

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

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

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

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

איך מקבלים טוקני גישה מסוג 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.

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

login_hint

אופציונלי

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

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

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

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

`disallowed_useragent`

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

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

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

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

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

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

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

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

יצירת הוכחת DPoP

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

יצירת זוג מפתחות EC P-256:

openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

יוצרים את הכותרת של ה-DPoP:
הכותרת חייבת לכלול את ההצהרות typ,‏ alg ו-jwk (מפתח ציבורי). הערכים x ו-y הם הקואורדינטות של המפתח הציבורי של ה-EC בקידוד Base64Url. מקודדים את ה-JSON הזה ב-Base64Url:
```
{
  "typ":"dpop+jwt",
  "alg":"ES256",
  "jwk": {
    "kty":"EC",
    "x":"YOUR_PUBLIC_KEY_X",
    "y":"YOUR_PUBLIC_KEY_Y",
    "crv":"P-256"
  }
}
```
יוצרים את המטען הייעודי (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 צריך להיות גיבוב SHA256 בקידוד Base64Url של קוד ההרשאה: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
- בהחלפות של טוקן רענון, הערך של jti חייב להיות מזהה ייחודי לכל בקשה: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
חותמים על ההוכחה:
משרשרים את הכותרת המקודדת ואת המטען הייעודי (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`. הערך הוא אסימון אינטרנט מסוג JSON‏ (JWT) שמכיל פרטי זהות חתומים דיגיטלית של המשתמש.
`refresh_token`	טוקן שאפשר להשתמש בו כדי לקבל טוקן גישה חדש. טוקני הרענון תקפים עד שהמשתמש מבטל את הגישה או עד שתוקף הטוקן פג. אם נעשה שימוש ב-DPoP, טוקן הרענון מקושר למפתח הפרטי ששימש לחתימה על הוכחת ה-DPoP. שימו לב שתמיד מוחזרים טוקנים לרענון לאפליקציות מותקנות.
`refresh_token_expires_in`	משך הזמן שנותר לטוקן הרענון, בשניות. הערך הזה מוגדר רק כשהמשתמש מעניק גישה מבוססת-זמן.
`scope`	היקפי הגישה שניתנו על ידי `access_token`, מבוטאים כרשימה של מחרוזות תלויות אותיות רישיות (case-sensitive) שמופרדות ברווחים.
`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"
}

הערה: אם לאפליקציה כבר יש טוקן רענון למשתמש ואתם רוצים לקבל טוקן רענון חדש שקשור ל-DPoP, המשתמש צריך לבטל את ההרשאה הקיימת או שאתם צריכים להשתמש בפרמטר prompt=consent בבקשת ההרשאה הראשונית כדי להבטיח שיונפק טוקן רענון חדש.

שלב 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 API

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

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

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

הערה: למידע נוסף על כתובת ה-IP של הלולאה החוזרת (loopback), עיינו בהגדרה של הפרמטר redirect_uri. אפשר גם להשתמש ב-localhost במקום בכתובת ה-IP של הלולאה החוזרת, אבל ההגדרה הזו עלולה לגרום לבעיות בחומות האש של הלקוח. רוב חומות האש מאפשרות תקשורת לולאה חזרה, אבל לא כולן.

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

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

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

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

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

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

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

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

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

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

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

App Check (iOS בלבד)

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

הפעלת App Check בלקוח iOS

כדי להפעיל את App Check בלקוח iOS, צריך לעמוד בדרישות הבאות:

צריך לציין מזהה צוות ללקוח iOS.
אסור להשתמש בתו כללי לחיפוש במזהה החבילה, כי הוא יכול להתאים ליותר מאפליקציה אחת. כלומר, אסור לכלול במזהה החבילה את סמל הכוכבית (*).

כדי להפעיל את App Check, מעבירים את המתג הגנה על לקוח OAuth מפני ניצול לרעה באמצעות Firebase App Check למצב מופעל בתצוגת העריכה של לקוח iOS.

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

יכול להיות שיופיעו שגיאות שקשורות לתכונה App Check כשמפעילים את App Check באפליקציה ל-iOS. כדי לפתור את השגיאות האלה, נסו את הפתרונות הבאים:

מוודאים שמזהה החבילה ומזהה הצוות שציינתם תקינים.
מוודאים שלא משתמשים בתו כללי לחיפוש במזהה החבילה.

אכיפת App Check בלקוח iOS

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

מספר הבקשות המאומתות – בקשות שיש להן אסימון App Check תקין. אחרי שמפעילים את אכיפת App Check, רק בקשות בקטגוריה הזו יצליחו.
‫Number of unverified requests: likely outdated client requests – בקשות שחסר בהן אסימון App Check. יכול להיות שהבקשות האלה מגיעות מגרסה ישנה יותר של האפליקציה שלא כוללת הטמעה של App Check.
מספר הבקשות שלא אומתו: בקשות ממקור לא ידוע – בקשות שחסר בהן אסימון App Check, ולא נראה שהן מגיעות מהאפליקציה שלכם.
מספר הבקשות שלא אומתו: בקשות לא חוקיות – בקשות עם אסימון App Check לא חוקי, שיכולות להגיע מלקוח לא אותנטי שמנסה להתחזות לאפליקציה שלכם, או מסביבות אמולציה.

כדאי לעיין במדדים האלה כדי להבין איך אכיפת App Check תשפיע על המשתמשים.

כדי לאכוף את App Check, לוחצים על הכפתור ENFORCE ומאשרים את הבחירה. אחרי שהאכיפה תופעל, כל הבקשות הלא מאומתות מהלקוח יידחו.

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

ביטול האכיפה של App Check בלקוח iOS

ביטול האכיפה של App Check באפליקציה יפסיק את האכיפה ויאפשר את כל הבקשות מהלקוח לנקודות הקצה של Google OAuth 2.0, כולל בקשות לא מאומתות.

כדי לבטל את האכיפה של App Check בלקוח iOS, עוברים לתצוגת העריכה של לקוח iOS, לוחצים על הכפתור UNENFORCE ומאשרים את הבחירה.

הערה: אחרי שמבטלים את האכיפה של App Check, יכולות לעבור עד 15 דקות לפני שהשינויים ייכנסו לתוקף.

השבתת App Check בלקוח iOS

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

כדי להשבית את App Check בלקוח iOS, עוברים לתצוגת העריכה של לקוח iOS ומשביתים את המתג הגנה על לקוח OAuth מפני ניצול לרעה באמצעות Firebase App Check.

הערה: אחרי שמשביתים את App Check, יכולות לעבור עד 15 דקות עד שהשינויים ייכנסו לתוקף.

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

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

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

קריאה נוספת

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

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

כדי להגן על חשבונות המשתמשים, מומלץ גם להטמיע את שירות ההגנה על כל החשבונות של 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

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

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

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

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

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

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

iOS

מחשב

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

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

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

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

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

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

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

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

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

שלב 3: Google מבקשת הסכמה מהמשתמש

שגיאות

admin_policy_enforced

disallowed_useragent

org_internal

deleted_client

invalid_grant

redirect_uri_mismatch

invalid_request

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

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

יצירת הוכחת DPoP

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

קריאה לממשקי Google API

דוגמאות ל-HTTP GET

curl דוגמאות

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

ביטול הטוקן

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

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

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

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

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

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

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

App Check (iOS בלבד)

הפעלת App Check בלקוח iOS

אכיפת App Check בלקוח iOS

ביטול האכיפה של App Check בלקוח iOS

השבתת App Check בלקוח iOS

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

קריאה נוספת

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

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

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`deleted_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`curl` דוגמאות