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

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

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

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

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

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

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

מומלץ להשתמש בסכימת URI מותאמת אישית עבור אפליקציות ל-Android, אפליקציות ל-iOS ואפליקציות Universal Windows Platform (UWP).

Android

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

iOS

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

   אם האפליקציה פורסמה ב-App Store של Apple, יש להזין את המזהה שלה. מזהה החנות הוא מחרוזת מספרית שמופיעה בכל כתובת URL של Apple App Store.

   1. פותחים את אפליקציית Apple App Store במכשיר iOS או iPadOS.
   2. מחפשים את האפליקציה.
   3. בוחרים בלחצן 'שיתוף' (הסמל מרובע וחץ למעלה).
   4. בוחרים באפשרות העתקת קישור.
   5. מדביקים את הקישור בכלי לעריכת טקסט. מזהה App Store הוא החלק האחרון של כתובת האתר.

      לדוגמה: https://apps.apple.com/app/google/id284815942

5. (לא חובה)

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

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

ארגון UWP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

במסמך OAuth 2.0 API Scopes יש רשימה מלאה של היקפי הרשאות שאפשר להשתמש בהם כדי לקבל גישה ל-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)))
plain (רגיל)	אתגר הקוד זהה לערך של מאמת הקוד שנוצר למעלה. code_challenge = code_verifier

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

כדי לקבל הרשאת משתמש, יש לשלוח בקשה לשרת ההרשאות של Google בכתובת https://accounts.google.com/o/oauth2/v2/auth. נקודת הקצה הזו מטפלת בחיפוש פעיל של ביקורים, מאמתת את המשתמש ומקבלת את הסכמת המשתמשים. ניתן לגשת לנקודת הקצה רק באמצעות 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 מסוג הלולאה החוזרת (loopback) http://127.0.0.1:port או http://[::1]:port שליחת שאילתה לפלטפורמה לגבי כתובת ה-IP הרלוונטית של הלולאה החוזרת (loopback) והפעלת 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, אחרי שהמשתמש מסכים או דוחה את בקשת הגישה של האפליקציה. אפשר להשתמש בפרמטר הזה לכמה מטרות, למשל הפניית המשתמש למשאב הנכון באפליקציה, שליחת מחרוזות ופתרון זיוף של בקשה בין אתרים. מכיוון שאפשר לנחש את redirect_uri, הערך state יכול להגביר את ההבטחה שחיבור נכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב (hash) של קובץ cookie או כל ערך אחר שמתעד את מצב הלקוח, ניתן לאמת את התגובה כדי לוודא שהבקשה ותגובה התקבלו באותו דפדפן, וכך לספק הגנה מפני מתקפות כמו זיוף בקשות באתרים שונים. במסמכי התיעוד OpenID Connect מוצגת דוגמה ליצירה ולאישור של אסימון 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=&
 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=&
 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 מציגה חלון הסכמה שמציג את שם האפליקציה ושירותי ה-API של Google שאליהם היא מבקשת הרשאה, באמצעות פרטי הכניסה של המשתמש לאישור וסיכום של היקפי הגישה שאפשר להעניק. לאחר מכן, המשתמש יוכל להסכים להעניק גישה להיקפים בהיקף אחד או יותר שצוינו בבקשה שלך או לדחות את הבקשה.

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

שגיאות

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

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 Custom Tabs.

iOS

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

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

org_internal

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

invalid_grant

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

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

redirect_uri_mismatch

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

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

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

שלב 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	האסימון שהאפליקציה שלך שולחת כדי לאשר בקשת API של Google.
expires_in	משך החיים הנותר של אסימון הגישה בשניות.
id_token	הערה: הנכס הזה מוחזר רק אם הבקשה שלך כללה היקף זהות, כמו openid, profile או email. הערך הוא אסימון Web 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 או ערך Bearer של כותרת HTTP מסוג Authorization. עדיף להשתמש בכותרת HTTP, כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. ברוב המקרים אפשר להשתמש בספריית לקוח כדי להגדיר קריאות ל-Google APIs (לדוגמה, כשמתבצעת קריאה ל-ב-Drive Files API).

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

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

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

קריאה נוספת

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