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

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

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

הפעלת ממשקי 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 שרוצים להפעיל ולוחצים על הלחצן הפעלה.
  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. לוחצים על Create credentials > OAuth client ID.
  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). הערך הזה מוצג בדרך כלל בחלונית 'כללי' או בחלונית 'חתימה ויכולות' בכלי לעריכת פרויקטים ב-Xcode. מזהה החבילה מוצג גם בקטע General Information (מידע כללי) בדף App Information (מידע כללי) של האפליקציה באתר App Store Connect של Apple.
  4. (לא חובה)

    אם האפליקציה פורסמה ב-Apple 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

  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 בהתאמה אישית ב-Android

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

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

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

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

כדי לעבור ל-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 בשם המשתמש.
  2. משביתים את התמיכה בסכימה בהתאמה אישית דרך Google API Console:
    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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Google תומכת בפרוטוקול הוכחת מפתח ל-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 נדרש

מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה בשדה API Console Credentials page.

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.
כתובת IP של הלולאה החוזרת (loop) http://127.0.0.1:port או http://[::1]:port

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

הערה: התמיכה באפשרות ההפניה האוטומטית לכתובת ה-IP בלולאה חוזרת באפליקציות לנייד הוצאה משימוש.

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

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

login_hint אופציונלי

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

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

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

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

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

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

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

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

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

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

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

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

שגיאות

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

admin_policy_enforced

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

disallowed_useragent

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

Android

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

מפתחי אתרים עשויים להיתקל בשגיאה הזו כשאפליקציה ל-Android פותחת קישור אינטרנט כללי לסוכן משתמש מוטמע, ומשתמש עובר לנקודת הקצה של הרשאת OAuth 2.0 של Google מהאתר שלך. המפתחים צריכים לאפשר לקישורים כלליים להיפתח ב-handler שמוגדר כברירת מחדל לקישורים של מערכת ההפעלה, שכולל גם את רכיבי ה-handler של קישורים לאפליקציות ל-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 Web Token (JWT) שמכיל פרטי זהות חתומים בחתימה דיגיטלית של המשתמש.
refresh_token אסימון שניתן להשתמש בו כדי לקבל אסימון גישה חדש. אסימוני הרענון בתוקף עד שהמשתמש יבטל את הגישה. חשוב לזכור שאסימוני רענון תמיד מוחזרים לאפליקציות מותקנות.
scope היקפי הגישה שהוענקה על ידי access_token, מבוטאים כרשימה של מחרוזות תלויות-רישיות ותלויות-רישיות.
token_type סוג האסימון שהוחזר. בשלב הזה, הערך בשדה הזה מוגדר תמיד כ-Bearer.

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

{
  "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 או ערך Bearer של כותרת HTTP Authorization. כשניתן, כותרת ה-HTTP עדיפה, כי מחרוזות השאילתה מופיעות בדרך כלל ביומני השרתים. ברוב המקרים, תוכלו להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, כשקוראים ל-Drive Files API).

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

דוגמאות ל-HTTP GET

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

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

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

קריאה נוספת

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