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

הערה

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

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

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

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

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

חלופות

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

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

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

מומלץ להיעזר בספריות ובדוגמאות הבאות שיעזרו לכם להטמיע את תהליך OAuth 2.0 שמתואר במסמך הזה:

• ספריית AppAuth ל-Android
• ספריית AppAuth ל-iOS
• OAuth לאפליקציות: דוגמאות של Windows

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

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

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

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

1. Open the API Library ב Google API Console.
2. If prompted, select a project, or create a new one.
3. בטבלה API Library מפורטים כל ממשקי ה-API הזמינים, בקיבוץ לפי משפחת מוצרים ופופולריות. אם ממשק ה-API שרוצים להפעיל לא מופיע ברשימה, משתמשים בחיפוש כדי למצוא אותו או לוחצים על הצגת הכול במשפחת המוצרים שאליה הוא שייך.
4. בוחרים את ממשק ה-API שרוצים להפעיל ולוחצים על הלחצן Enable (הפעלה).
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Credentials page.
2. לוחצים על יצירת פרטי כניסה > מזהה לקוח OAuth.
3. בקטעים הבאים מתוארים סוגי הלקוחות והשיטות להפניה אוטומטית שבהן תומך שרת ההרשאות של Google. צריך לבחור את סוג הלקוח המומלץ לאפליקציה, לתת שם ללקוח OAuth ולהגדיר את השדות האחרים בטופס לפי הצורך.

Android

1. בוחרים את סוג האפליקציה Android.
2. מזינים שם ללקוח OAuth. השם הזה מוצג בדף Credentials page של הפרויקט כדי לזהות את הלקוח.
3. יש להזין את שם החבילה של האפליקציה ל-Android. הערך הזה מוגדר במאפיין package של האלמנט <manifest> בקובץ המניפסט של האפליקציה.
4. יש להזין את טביעת האצבע לאישור החתימה SHA-1 של הפצת האפליקציה.
   • אם באפליקציה נעשה שימוש בחתימת אפליקציות ב-Google Play, צריך להעתיק את טביעת האצבע מסוג SHA-1 מדף חתימת האפליקציות ב-Play Console.
   • אם אתם מנהלים מאגר מפתחות ומפתחות חתימה משלכם, השתמשו בכלי keytool הכלול ב-Java כדי להדפיס את פרטי האישור בפורמט קריא לאנשים. מעתיקים את הערך SHA1 בקטע Certificate fingerprints בפלט של keytool. למידע נוסף, קראו את המאמר אימות הלקוח במסמכי התיעוד של Google APIs ל-Android.
5. (אופציונלי) מאמתים את הבעלות על האפליקציה ל-Android.
6. לוחצים על יצירה.

iOS

1. בוחרים את סוג האפליקציה iOS.
2. מזינים שם ללקוח OAuth. השם הזה מוצג בדף Credentials page של הפרויקט כדי לזהות את הלקוח.
3. מזינים את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של מפתח CFBundleIdentifier בקובץ המשאבים של רשימת מאפייני המידע של האפליקציה (info.plist). הערך בדרך כלל מוצג בחלונית General או בחלונית Signing & Capabilities של עורך הפרויקטים ב-Xcode. מזהה החבילה מוצג גם בקטע General Information בדף פרטי האפליקציה של האפליקציה באתר App Store Connect של Apple.
4. (לא חובה)

   יש להזין את המזהה של האפליקציה ב-App Store אם היא פורסמה ב-Apple 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

5. (לא חובה)

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

6. לוחצים על יצירה.

UWP

1. בוחרים את סוג האפליקציה Universal Windows Platform.
2. מזינים שם ללקוח OAuth. השם הזה מוצג בדף Credentials page של הפרויקט כדי לזהות את הלקוח.
3. מזינים את מזהה Microsoft Store בן 12 התווים של האפליקציה. אפשר למצוא את הערך הזה במרכז השותפים של Microsoft בדף App Identity בקטע 'ניהול אפליקציות'.
4. לוחצים על יצירה.

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

סכימת URI מותאמת אישית (Android, iOS, UWP)

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

חשוב: סכימות URI בהתאמה אישית לא נתמכות יותר באפליקציות Chrome חדשות, והן מושבתות כברירת מחדל בלקוחות Android חדשים בגלל הסיכון להתחזות לאפליקציה.

חלופה לשימוש בסכמות URI בהתאמה אישית ב-Android

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

איך עוברים ל-SDK לכניסה באמצעות חשבון Google ל-Android

אם משתמשים כרגע בסכימה מותאמת אישית לשילוב OAuth ב-Android, צריך להשלים את הפעולות שמפורטות בהמשך כדי לעבור באופן מלא לשימוש בערכת ה-SDK המומלצת לכניסה באמצעות חשבון Google ל-Android SDK:

1. צריך לעדכן את הקוד כדי להשתמש ב-SDK לכניסה באמצעות חשבון Google.
2. השבתת התמיכה בסכימה מותאמת אישית ב-Google API Console.

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

כדי לעבור ל-Android SDK לכניסה באמצעות חשבון Google:

1. מעדכנים את הקוד כדי להשתמש ב-Android SDK לכניסה באמצעות חשבון Google:
   1. צריך לבדוק את הקוד כדי לזהות לאן אתם שולחים בקשה לשרת OAuth 2.0 של Google. אם אתם משתמשים בסכימה בהתאמה אישית, הבקשה שלכם תיראה כך:

        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        

      com.example.app:/oauth2redirect הוא ה-URI להפניה אוטומטית עם סכימה מותאמת אישית בדוגמה שלמעלה. לפרטים נוספים על הפורמט של הערך של סכימת ה-URI המותאמת אישית, אפשר לעיין בהגדרת הפרמטר redirect_uri.
   2. חשוב לשים לב לפרמטרים של הבקשה scope ו-client_id שצריך כדי להגדיר את ה-SDK לכניסה באמצעות חשבון Google.
      הערה: אם משתמשים בספרייה של צד שלישי, צריך לבדוק את קובץ התצורה של הספרייה כדי למצוא את המידע הזה.
   3. פועלים לפי ההוראות לשילוב הכניסה באמצעות חשבון Google באפליקציה ל-Android כדי להגדיר את ה-SDK. אפשר לדלג על השלב קבלת מזהה הלקוח של OAuth 2.0 של שרת הקצה העורפי, כי לשם כך משתמשים שוב ב-client_id שאחזרת מהשלב הקודם.
   4. פועלים לפי ההוראות ל הפעלת גישה ל-API בצד השרת. זה כולל את השלבים הבאים:
      1. משתמשים בשיטה getServerAuthCode כדי לאחזר קוד הרשאה להיקפי ההרשאות שעבורם מבקשים הרשאה.
      2. שלח את קוד ההרשאה לקצה העורפי של האפליקציה כדי להחליף אותו באסימון גישה ורענון.
      3. משתמשים באסימון הגישה שאוחזר כדי לבצע קריאות ל-Google APIs בשם המשתמש.
      הערה: אם האפליקציה לא מחייבת גישה אופליין, צריך לפעול לפי ההוראות האלה כדי לבקש גישה ל-API בצד הלקוח.
2. השבתת התמיכה בסכימה בהתאמה אישית במסוף Google API:
   1. עוברים לרשימה של פרטי הכניסה של OAuth 2.0 ובוחרים את לקוח Android הרלוונטי.
   2. מנווטים לקטע Advanced Settings (הגדרות מתקדמות) ומבטלים את הסימון בתיבה Enable Custom URI Scheme (הפעלה של סכימת URI מותאמת אישית) ולוחצים על Save (שמירה) כדי להשבית את התמיכה בסכמות URI מותאמות אישית.

הפעלת סכימת URI מותאמת אישית

אם החלופה המומלצת לא מתאימה לך, אפשר להפעיל סכמות URI בהתאמה אישית ללקוח Android שלך. לשם כך, פועלים לפי ההוראות הבאות:

1. נכנסים לרשימה של פרטי הכניסה של OAuth 2.0 ובוחרים את הלקוח הרלוונטי ל-Android.
2. עוברים לקטע Advanced Settings (הגדרות מתקדמות), מסמנים את התיבה Enable Custom URI Scheme (הפעלה של סכימת URI מותאמת אישית) ולוחצים על Save כדי להפעיל תמיכה בסכמות בהתאמה אישית של URI.

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

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

אימות הבעלות על האפליקציה (Android, Chrome)

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

Android

הערה: אימות הבעלות על אפליקציות ל-Android זמין כרגע רק לאפליקציות ב-Google Play.

כדי להשלים את תהליך האימות, יש לך אפשרות להשתמש בחשבון הפיתוח שלך ב-Google Play, אם יש לך חשבון והאפליקציה שלך רשומה ב-Google Play Console. כדי שהאימות יתבצע בהצלחה, צריך לעמוד בדרישות הבאות:

• צריך שתהיה לך אפליקציה רשומה ב-Google Play Console עם שם חבילה וטביעת אצבע של אישור חתימה SHA-1 שזהים לאלה של לקוח OAuth ל-Android שעבורו ברצונך להשלים את האימות.
• נדרשת הרשאת אדמין לאפליקציה ב-Google Play Console. מידע נוסף על ניהול הרשאות גישה ב-Google Play Console

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

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

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

• יש לוודא שהאפליקציה שבחרת לאמת היא אפליקציה רשומה ב-Google Play Console.
• עליך לוודא שיש לך הרשאת אדמין לאפליקציה ב-Google Play Console.

Chrome

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

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

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

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

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

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

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

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

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

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

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

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

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

העתקה/הדבקה ידנית

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

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

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

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

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

המסמך היקפי API של OAuth 2.0 מכיל רשימה מלאה של היקפי ההרשאות שיכולים לעזור לכם לגשת ל-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 (מומלץ)	אתגר הקוד הוא גיבוב SHA256 עם קידוד Base64URL (ללא מרווח פנימי) של מאמת הקוד. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
פשוט	האתגר של הקוד זהה לערך של מאמת הקוד שנוצר למעלה. code_challenge = code_verifier

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

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

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

פרמטרים
client_id	חובה מזהה הלקוח באפליקציה שלכם. הערך הזה מופיע ב Credentials page API Console.
redirect_uri	חובה המדיניות זו קובעת את האופן שבו שרת ההרשאות של Google שולח תגובה לאפליקציה שלך. יש כמה אפשרויות זמינות להפניה אוטומטית לאפליקציות מותקנות, ועליך להגדיר את פרטי הכניסה להרשאה עם שיטת הפניה מסוימת מסוימת. הערך צריך להתאים במדויק לאחד ממזהי ה-URI המורשים להפניה אוטומטית בלקוח OAuth 2.0, שהגדרת ב- API Console Credentials pageשל הלקוח. אם הערך הזה לא תואם ל-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. הערה : סכמות URI בהתאמה אישית לא נתמכות יותר באפליקציות Chrome והן מושבתות כברירת מחדל ב-Android. מידע נוסף על חלופות עם סכמות בהתאמה אישית לאפליקציות ל-Android ול-Chrome. כתובת IP מסוג לופ חוזר http://127.0.0.1:port או http://[::1]:port שולחים שאילתה לפלטפורמה לגבי כתובת ה-IP הרלוונטית בלולאה לאחור, ומפעילים האזנה ל-HTTP ביציאה אקראית זמינה. מחליפים את port במספר היציאה שהאפליקציה מאזינה בפועל. שימו לב שהתמיכה באפשרות ההפניה האוטומטית לכתובת ה-IP בלולאה לאחור באפליקציות לנייד הוצאה משימוש.
response_type	חובה המדיניות הזו קובעת אם נקודת הקצה (endpoint) של 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, אחרי שהמשתמש מביע הסכמה או דחייה של בקשת הגישה של האפליקציה. אפשר להשתמש בפרמטר הזה לכמה מטרות, כמו הפניית המשתמש למשאב הנכון באפליקציה, שליחת נתונים חד-פעמיים (nonces) וצמצום זיוף בקשות בין אתרים. מאחר שניתן לנחש את redirect_uri, שימוש בערך state יכול להגביר את הביטחון שחיבור נכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב של קובץ cookie או ערך אחר שמתעד את המצב של הלקוח, אפשר לאמת את התגובה כדי לוודא גם שהבקשה והתגובה הגיעו מאותו דפדפן, וכך לספק הגנה מפני מתקפות כמו זיוף של בקשה בין אתרים. כדי לראות דוגמה ליצירה ולאישור של אסימון state, כדאי לעיין במסמכי התיעוד של OpenID Connect.
login_hint	אופציונלי אם האפליקציה שלכם יודעת איזה משתמש מנסה לבצע אימות, היא יכולה להשתמש בפרמטר הזה כדי לספק רמז לשרת האימות של Google. השרת משתמש ברמז כדי לפשט את תהליך ההתחברות על ידי מילוי מראש של שדה האימייל בטופס הכניסה או בחירה בסשן המתאים עם כניסות מרובות. צריך להגדיר את ערך הפרמטר לכתובת אימייל או למזהה sub, שזהה למזהה Google של המשתמש.

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

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

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

כתובות ה-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 מסוג לולאה חוזרת

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

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

Android

מפתחי Android עשויים להיתקל בהודעת השגיאה הזו כשהם פותחים בקשות הרשאה ב-android.webkit.WebView. במקום זאת, מפתחים צריכים להשתמש בספריות ל-Android, כמו כניסה באמצעות חשבון Google ל-Android או AppAuth ל-Android של OpenID Foundation.

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

iOS

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

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

org_internal

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

invalid_grant

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

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

redirect_uri_mismatch

הערך redirect_uri שהועבר בבקשת ההרשאה לא תואם ל-URI מורשה של הפניה אוטומטית עבור מזהה הלקוח ב-OAuth. יש לבדוק מזהי URI מורשים להפניה אוטומטית ב- Google API Console Credentials page.

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

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

invalid_request

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הערה: האפליקציה צריכה להתעלם משדות לא מזוהים שכלולים בתגובה.

קריאה ל-Google APIs

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

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

דוגמאות GET של HTTP

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

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

הנה קריאה לאותו API עבור המשתמש המאומת באמצעות הפרמטר של מחרוזת השאילתה access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl דוגמאות

אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה שמשתמשת באפשרות של כותרת HTTP (מועדף):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

לחלופין, אפשרות הפרמטר של מחרוזת השאילתה:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

רענון אסימון גישה

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

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

שדות
client_id	מזהה הלקוח שהתקבל מ- API Console.
client_secret	סוד הלקוח שהתקבל מה- API Console. (client_secret לא רלוונטי לבקשות מלקוחות שרשומים כאפליקציות ל-Android, ל-iOS או ל-Chrome).
grant_type	כפי שמוגדר במפרט OAuth 2.0, הערך בשדה הזה צריך להיות refresh_token.
refresh_token	אסימון הרענון שהוחזר מהחלפת קוד ההרשאה.

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

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.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 יחד עם קוד שגיאה.

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

קריאה נוספת

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