דף זה תורגם על ידי Cloud Translation API.

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

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

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 לפרויקט:

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

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

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

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

Android

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

iOS

בוחרים בסוג האפליקציה iOS.
מזינים שם ללקוח OAuth. השם הזה מוצג בפרויקט Credentials page כדי לזהות את הלקוח.
יש להזין את מזהה החבילה של האפליקציה. מזהה החבילה הוא הערך של CFBundleIdentifier בקובץ המשאבים של רשימת מאפייני המידע (info.plist). הערך מוצגת בדרך כלל בחלונית 'כללי' או בחלונית 'חתימה & חלונית היכולות של עורך פרויקט Xcode. מזהה החבילה מוצג גם בקטע 'מידע כללי' של את דף פרטי האפליקציה שבו אתר App Store Connect של Apple.
(אופציונלי)
אם האפליקציה פורסמה ב-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
(אופציונלי)
צריך להזין את מזהה הצוות. צפייה איתור מזהה הצוות במסמכי התיעוד של חשבון הפיתוח של Apple.
לוחצים על יצירה.

UWP

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

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

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

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

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

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

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

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

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

צריך לעדכן את הקוד כדי להשתמש בערכת ה-SDK ל-Android לכניסה באמצעות חשבון 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 של סכימה מותאמת אישית להפניה מחדש בדוגמה שלמעלה. לצפייה הגדרת הפרמטר redirect_uri לפרטים נוספים על הפורמט של הערך המותאם אישית של סכימת ה-URI.
2. חשוב לשים לב לפרמטרים של הבקשות scope ו-client_id, יהיה עליך להגדיר את ה-SDK של כניסה באמצעות Google.
  הערה: אם אתם משתמשים בספרייה של צד שלישי, כדאי לעיין קובץ התצורה כדי למצוא את המידע הזה.
3. פועלים לפי שילוב של כניסה באמצעות חשבון Google באפליקציה ל-Android ההוראות להגדרת ה-SDK. אפשר לדלג על מקבלים את מזהה הלקוח OAuth 2.0 של שרת הקצה העורפי כמו שעושים בו שימוש חוזר client_id שאחזרת מהשלב הקודם.
4. פועלים לפי הפעלת גישה ל-API בצד השרת הוראות להתאמה אישית. זה כולל את השלבים הבאים:
  1. משתמשים בשיטה getServerAuthCode כדי לאחזר קוד הרשאה עבור את היקפי ההרשאות שביקשת עבורם הרשאה.
  2. יש לשלוח את קוד ההרשאה לקצה העורפי של האפליקציה כדי להחליף אותו ולקבל גישה לרענן ב-Assistant.
  3. משתמשים באסימון הגישה שאוחזר כדי לבצע קריאות ל-Google APIs בשם המשתמש.
  הערה: אם לאפליקציה לא נדרשת גישה אופליין, צריך לפעול לפי ההוראות הוראות אלה במקום זאת כדי לבקש גישה לממשק API בצד הלקוח.
השבתת התמיכה בסכמה מותאמת אישית במסוף Google API:
1. עוברים אל פרטי כניסה בפרוטוקול OAuth 2.0 ובוחרים את לקוח Android שלכם.
2. עוברים לקטע הגדרות מתקדמות ומבטלים את הסימון של התיבה. הפעל סכימת URI מותאמת אישית, ולחץ על שמור כדי השבתת התמיכה בסכמת URI מותאמת אישית.

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

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

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

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

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

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

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

Android

כדי להשלים את תהליך האימות, יש לך אפשרות להשתמש בחשבון הפיתוח שלך ב-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 בלולאה חוזרת (loopback) (macOS, Linux, מחשב עם Windows)

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

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

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

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

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

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

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

לפני שמתחילים להטמיע הרשאה מסוג 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 של הלולאה החוזרת

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

שולחים לפלטפורמה את כתובת ה-IP הרלוונטית בלולאה חוזרת (loopback) ומתחילים HTTP ל-listener בשקע זמין אקראי. מחליפים את 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 יכול להגביר את הביטחון שחיבור נכנס הוא תוצאה של בקשת אימות. אם יוצרים מחרוזת אקראית או מקודדים גיבוב של קובץ cookie, ערך אחר שמתעד את המצב של הלקוח, אפשר לאמת את התגובה לוודא גם שהבקשה והתגובה הגיעו מאותו דפדפן, אספקת הגנה מפני מתקפות כגון בקשה בין אתרים זיוף. לצפייה OpenID Connect תיעוד לדוגמה של יצירה ואישור של אסימון state.

חשוב: לקוח OAuth חייב למנוע CRF כפי שמוסבר ב מפרט 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 בלולאה חוזרת

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`

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

Android

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

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

iOS

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

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

`invalid_request`

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

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

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

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

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

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

כדי להחליף קוד הרשאה באסימון גישה, קוראים אל 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`

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

{
  "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

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

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

דוגמאות ל-HTTP GET

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

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

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

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

ביטול אסימון

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

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

יישום הגנה על כל החשבונות

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

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

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

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

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

Android

iOS

UWP

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

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

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

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

Android

Chrome

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

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

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

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

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

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

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

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

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

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

כתובת IP בלולאה חוזרת

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

שגיאות

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_grant

redirect_uri_mismatch

invalid_request

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

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

קריאה ל-Google APIs

דוגמאות ל-HTTP GET

curl דוגמאות

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

ביטול אסימון

קריאה נוספת

יישום הגנה על כל החשבונות

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`curl` דוגמאות