Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫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 Library ב-Google API Console.
אם מתבקשים, בוחרים פרויקט או יוצרים פרויקט חדש.
בספריית ה-API מפורטים כל ממשקי ה-API הזמינים, מקובצים לפי משפחת מוצרים ופופולריות. אם ה-API שרוצים להפעיל לא מופיע ברשימה, אפשר להשתמש בחיפוש כדי למצוא אותו, או ללחוץ על הצגת כל במשפחת המוצרים שאליה הוא שייך.
בוחרים את ה-API שרוצים להפעיל ולוחצים על הכפתור הפעלה.
אם תופיע בקשה, תצטרכו להפעיל את החיוב.
אם מתבקשים לעשות זאת, קוראים את התנאים וההגבלות של ה-API ומאשרים אותם.

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

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

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

iOS

בוחרים את סוג האפליקציה iOS.
מזינים שם ללקוח OAuth. השם הזה מוצג בדף הלקוחות של הפרויקט כדי לזהות את הלקוח.
מזינים את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של המפתח 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
(אופציונלי)
מזינים את מזהה הצוות. מידע נוסף מופיע במאמר איפה נמצא מספר הצוות במסמכי התיעוד של חשבון Apple למפתחים.
הערה: השדה Team ID (מזהה צוות) הוא חובה אם מפעילים את App Check עבור הלקוח.
(אופציונלי)
מפעילים את App Check באפליקציית iOS. כשמפעילים את App Check, נעשה שימוש בשירות App Attest של Apple כדי לוודא שבקשות OAuth 2.0 שמקורן בלקוח OAuth הן אמיתיות ומגיעות מהאפליקציה. כך אפשר לצמצם את הסיכון להתחזות לאפליקציה. מידע נוסף על הפעלת App Check באפליקציית iOS
לוחצים על יצירה.

UWP

בוחרים בסוג האפליקציה Universal Windows Platform.
מזינים שם ללקוח OAuth. השם הזה מוצג בפרויקט שלכם ב- כדי לזהות את הלקוח.
מזינים את מזהה האפליקציה בחנות Microsoft Store, שמורכב מ-12 תווים. אפשר למצוא את הערך הזה במרכז השותפים של מיקרוסופט בדף זהות האפליקציה בקטע 'ניהול אפליקציות'.
לוחצים על יצירה.

באפליקציות UWP, כתובת ה-URI להפניה אוטומטית נוצרת באמצעות מזהה האבטחה (SID) הייחודי של חבילת האפליקציה. אפשר למצוא את Package SID של האפליקציה בקובץ Package.appxmanifest בפרויקט Visual Studio.

כשיוצרים את מזהה הלקוח במסוף Google Cloud, צריך לציין את ה-URI של ההפניה האוטומטית בפורמט הבא, באמצעות הערך באותיות קטנות של ה-SID של החבילה:

ms-app://YOUR_APP_PACKAGE_SID

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

באפליקציות UWP, סכמת ה-URI המותאמת אישית לא יכולה להיות ארוכה יותר מ-39 תווים, כפי שמצוין במסמכי Microsoft.

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

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

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

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

קבלת אסימוני גישה מסוג OAuth 2.0

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

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

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

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

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

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

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

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

שיטות ליצירת אתגר קוד
‫S256 (מומלץ)	אתגר הקוד הוא גיבוב SHA256 של מאמת הקוד בקידוד 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

חובה

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

redirect_uri

חובה

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

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

‫http://127.0.0.1:port או http://[::1]:port

מבצעים שאילתה בפלטפורמה כדי למצוא את כתובת ה-IP הרלוונטית של ה-loopback ומתחילים מאזין 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 בבקשה שכוללת code_challenge, ברירת המחדל היא plain. הערכים הנתמכים היחידים של הפרמטר הזה הם S256 או plain.

state

מומלץ

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

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

שגיאות

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

`admin_policy_enforced`

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

`disallowed_useragent`

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

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

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

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

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

`invalid_request`

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

הפורמט של הבקשה לא תקין
בבקשה חסרים פרמטרים נדרשים
הבקשה משתמשת בשיטת הרשאה ש-Google לא תומכת בה. אימות ששילוב ה-OAuth משתמש בשיטת שילוב מומלצת
נעשה שימוש בסכימה מותאמת אישית שלא נתמכת בכתובת ה-URI להפניה אוטומטית. אם מופיעה הודעת השגיאה Custom URI scheme is not supported on Android or Chrome apps, learn more about custom URI scheme alternatives.

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

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

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

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

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

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

השימוש ב-DPoP הוא אופציונלי, אבל מומלץ לשיפור האבטחה. האבטחה של DPoP מתבססת על כך שהמפתח הפרטי מוגבל למכשיר יחיד. מומלץ לאחסן אותו באופן שלא מאפשר להעתיק אותו מהמכשיר, למשל באמצעות TPM, אזורים מאובטחים או מאגרי מפתחות אחרים שמגובים בחומרה. כדי להשתמש ב-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: 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 (URI של HTTP, למשל https://oauth2.googleapis.com/token) ו-iat (הונפק בזמן). אם קיבלתם ערך חד-פעמי מהשרת בכותרת DPoP-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 של הוכחת ה-DPoP בבקשות הבאות (למשל, כשמבצעים החלפה של טוקן רענון בטוקן גישה חדש, או כששולחים קריאה לממשקי API שמוגנים באמצעות DPoP). אם משתמשים בערך ה-nonce שהונפק מוקדם, אפשר להימנע מכישלון נוסף של הלוך ושוב (use_dpop_nonce) בבקשה הבאה.

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

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

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

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

שדות
`access_token`	האסימון שהאפליקציה שולחת כדי לאשר בקשת API של Google.
`expires_in`	משך החיים שנותר של אסימון הגישה בשניות.
`id_token`	הערה: המאפיין הזה מוחזר רק אם הבקשה כוללת היקף זהות, כמו `openid`, `profile` או `email`. הערך הוא אסימון אינטרנט מסוג JSON ‏ (JWT) שמכיל מידע על זהות המשתמש בחתימה דיגיטלית.
`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"
}

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

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

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

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

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

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

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

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

דוגמאות ל-HTTP GET

קריאה לנקודת הקצה drive.files (ה-API של קובצי Drive) באמצעות כותרת ה-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 שמוכיח את הבעלות על מפתח פרטי. זו כותרת, לא פרמטר. אם המפתח הזה מסופק, הטוקנים שמוחזרים קשורים אליו. צריך ליצור הוכחה חדשה וייחודית לכל בקשה, והיא צריכה לכלול טענות של `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 הזה ולכלול אותו בטענת 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 של Loopback (macOS, ‏ Linux, מחשב Windows)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

צריך לוודא שיש פריט רשום במרכז השליטה למפתחים בחנות האינטרנט של 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, מעבירים את המתג Protect your OAuth client from abuse with Firebase 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 for iOS בצד שמאל של הדף, יופיעו מדדים של App Check. המדדים כוללים את הפרטים הבאים:

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

הערה: אחרי שמבטלים את האכיפה של 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 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

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

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

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

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

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

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

iOS

UWP

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

קבלת אסימוני גישה מסוג 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 APIs

דוגמאות ל-HTTP GET

curl דוגמאות

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

ביטול טוקן

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

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

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

כתובת IP של Loopback (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` דוגמאות