חשבונות מקושרים באמצעות תהליך המשתמע וקוד הרשאה רגיל של OAuth 2.0. השירות חייב לתמוך בנקודות קצה (endpoint) מסוג הרשאה ו-Token Exchange התואמות ל-OAuth 2.0.
בתהליך המשתמע, Google פותחת את נקודת הקצה של ההרשאה בדפדפן של המשתמש. לאחר כניסה מוצלחת, מחזירים ל-Google אסימון גישה לטווח ארוך. אסימון הגישה הזה כלול עכשיו בכל בקשה שנשלחה מ-Google.
בתהליך קוד ההרשאה צריך שתי נקודות קצה:
נקודת הקצה הרשאה, שמציגה את ממשק המשתמש לכניסה למשתמשים שלך שאינם מחוברים לחשבון. נקודת הקצה לאישור יוצרת גם קוד הרשאה לטווח קצר כדי לתעד משתמשים' מסכים לגישה המבוקשת.
נקודת הקצה של החלפת אסימונים, שאחראית לשני סוגים של בורסות:
- מתבצעת העברה של קוד הרשאה לאסימון רענון לטווח ארוך ולאסימון גישה לטווח קצר. ההחלפה הזו מתרחשת כשהמשתמש עובר את תהליך קישור החשבון.
- העברה של אסימון רענון לטווח ארוך עבור אסימון גישה לטווח קצר (LTS). ההחלפה הזו מתרחשת כש-Google צריכה אסימון גישה חדש כי תוקפו פג.
בחירת זרימת OAuth 2.0
אומנם קל יותר להטמיע את התהליך המשתמע, אבל Google ממליצה שפג התוקף של אסימוני הגישה שהונפקו על ידי התהליך המשתמע. הסיבה לכך היא שהמשתמש מאלץ קישור מחדש של החשבון שלו לאחר שפג תוקפו של אסימון עם התהליך המשתמע. אם אתם צריכים תפוגה של אסימון מסיבות אבטחה, מומלץ מאוד להשתמש בתהליך קוד ההרשאה במקום זאת.
הנחיות עיצוב
בקטע הזה מתוארות הדרישות וההמלצות בנוגע לעיצוב של מסך המשתמש שאתם מארחים בתהליכי קישור OAuth. אחרי שהאפליקציה נקראת על ידי האפליקציה של Google, היא מציגה למשתמש מסך כניסה לדף Google ולמסך ההסכמה לקישור חשבון. המשתמש מופנה בחזרה לאפליקציה של Google אחרי שהוא נותן את הסכמתו לקשר חשבונות.
דרישות
- עליך להודיע שהחשבון של המשתמש יקושר ל-Google, לא למוצר ספציפי של Google כגון Google Home או Google Assistant.
המלצות
מומלץ לבצע את הפעולות הבאות:
הצגת מדיניות הפרטיות של Google. במסך הקישור יש לציין את מדיניות הפרטיות של Google.
הנתונים לשיתוף. השתמש בשפה ברורה ותמציתית כדי לספר למשתמש אילו נתונים הוא דורש ומדוע.
קריאה ברורה לפעולה. יש לציין במסך קריאה ברורה פעולה, כמו "הסכמה וקישור", כי המשתמשים צריכים להבין אילו נתונים הם נדרשים לשתף עם Google כדי לקשר את החשבונות שלהם.
יכולת לבטל. למשתמשים תהיה אפשרות לחזור אחורה או לבטל את המינוי אם הם יבחרו שלא לקשר.
ניקוי תהליך הכניסה. חשוב לוודא שהמשתמשים מקבלים שיטה ברורה להיכנס לחשבון Google שלהם, כמו השדות של שם המשתמש והסיסמה שלהם, או כניסה באמצעות חשבון Google.
יכולת לבטל את הקישור. צריך להציע למשתמשים מנגנון לביטול הקישור, כמו כתובת URL להגדרות החשבון בפלטפורמה שלהם. לחלופין, אפשר לכלול קישור לחשבון Google, שבו המשתמשים יכולים לנהל את החשבון המקושר שלהם.
היכולת לשנות את חשבון המשתמש. להציע למשתמשים שיטה להחלפת החשבונות שלהם. אפשרות זו שימושית במיוחד אם למשתמשים יש מספר חשבונות.
- אם משתמש צריך לסגור את מסך ההסכמה כדי להחליף חשבון, צריך לשלוח ל-Google הודעת שגיאה ניתנת לשחזור. כך הוא יוכל להיכנס לחשבון הרצוי באמצעות קישור OAuth ותהליך המשתמע.
הלוגו צריך לכלול. הצגת הלוגו של החברה במסך ההסכמה. היעזרו בהנחיות הסגנון כדי למקם את הלוגו. אם ברצונך להציג גם את הלוגו של Google, יש לעיין בלוגו ובסימנים מסחריים.
יצירת הפרויקט
כדי ליצור פרויקט באמצעות קישור חשבונות:
- Go to the Google API Console.
- לחץ על צור פרויקט .
- הזן שם או קבל את ההצעה שנוצרה.
- אשר או ערוך את כל השדות שנותרו.
- לחץ על צור .
לצפייה במזהה הפרוייקט שלך:
- Go to the Google API Console.
- מצא את הפרוייקט שלך בטבלה בדף הנחיתה. מזהה הפרויקט מופיע בעמודה מזהה .
הגדרה של מסך ההסכמה ל-OAuth
תהליך הקישור של חשבון Google כולל מסך הסכמה שמציין למשתמשים את האפליקציה שמבקשת גישה לנתונים שלהם, אילו סוגי נתונים הם מבקשים והתנאים החלים. צריך להגדיר את מסך ההסכמה ל-OAuth לפני שיוצרים מזהה לקוח ב-Google API.
- פותחים את הדף מסך ההסכמה של OAuth במסוף Google APIs.
- אם מתבקשים, בוחרים את הפרויקט שיצרתם.
בדף 'מסך הסכמה של OAuth', ממלאים את הטופס ולוחצים על הלחצן 'שמירה'.
שם האפליקציה: השם של האפליקציה שמבקשת הסכמה. השם צריך לשקף את האפליקציה באופן מדויק ולהיות תואם לשם האפליקציה שהמשתמשים רואים במקומות אחרים. שם האפליקציה יוצג במסך ההסכמה לקישור חשבונות.
הלוגו של האפליקציה: תמונה במסך ההסכמה שתעזור למשתמשים לזהות את האפליקציה. הלוגו מוצג במסך ההסכמה לקישור חשבון ובהגדרות החשבון
כתובת אימייל לתמיכה: מאפשר למשתמשים ליצור איתכם קשר אם יש להם שאלות לגבי ההסכמה שלהם.
היקפים עבור Google APIs: היקפי הרשאות מאפשרים לאפליקציה לגשת לנתוני Google הפרטיים של המשתמשים. בתרחיש לדוגמה של 'קישור חשבון Google', היקף ברירת המחדל (אימייל, פרופיל, מזהה פתוח) מספיק. אין צורך להוסיף היקפים רגישים. בדרך כלל מומלץ לבקש היקפים באופן מצטבר, בזמן שנדרשת גישה, ולא מראש. מידע נוסף
דומיינים מורשים: כדי להגן עליכם ועל המשתמשים שלכם, Google מאפשרת רק לאפליקציות שמבצעות אימות באמצעות OAuth להשתמש בדומיינים מורשים. הקישורים לאפליקציות שלכם חייבים להתארח ב'דומיינים מורשים'. מידע נוסף
קישור לדף הבית של האפליקציה: דף הבית של האפליקציה. חייב להתארח בדומיין מורשה.
קישור למדיניות הפרטיות של האפליקציה: מוצג במסך ההסכמה לקישור חשבון Google. חייב להתארח בדומיין מורשה.
קישור לתנאים ולהגבלות של האפליקציה (אופציונלי): חייב להתארח בדומיין מורשה.
איור 1. מסך הסכמה לקישור חשבון Google לאפליקציה פיקטיבית, Tunery
מסמנים את 'סטטוס אימות'. אם צריך לאמת את הבקשה, לוחצים על הלחצן 'שליחה לאימות' כדי לשלוח את הבקשה לאימות. לפרטים, יש לעיין בדרישות לאימות OAuth.
הטמעה של שרת ה-OAuth
OAuth 2.0 יישום השרת של זרימת קוד אישור מורכב משני נקודות קצה, אשר השירות מעמיד לרשות ידי HTTPS. נקודת הקצה הראשונה היא נקודת הקצה של ההרשאה, אשר אחראית לאיתור או קבלת הסכמה ממשתמשים לגישה לנתונים. נקודת הקצה של ההרשאה מציגה ממשק משתמש כניסה למשתמשים שלך שעדיין לא נכנסו לחשבון ומתעדת הסכמה לגישה המבוקשת. נקודת הקצה השנייה היא נקודת הקצה של חילופי האסימונים, המשמשת להשגת מחרוזות מוצפנות, הנקראות אסימונים, המאשרות למשתמש לגשת לשירות שלך.
כאשר אפליקציה של Google צריכה להתקשר לאחד מממשקי ה-API של השירות שלך, Google משתמשת בנקודות הקצה הללו יחד כדי לקבל הרשאה מהמשתמשים שלך להתקשר לממשקי ה-API האלה בשמם.
הפעלת זרימת קוד הרשאות OAuth 2.0 שיזמה Google כוללת את הזרימה הבאה:
- Google פותחת את נקודת קצה ההרשאה שלך בדפדפן של המשתמש. אם הזרימה התחילה במכשיר קולי בלבד עבור פעולה, Google מעבירה את הביצוע לטלפון.
- המשתמש נכנס, אם עדיין לא נכנס, ומעניק ל-Google הרשאה לגשת לנתונים שלו באמצעות ה-API שלך, אם הוא עדיין לא העניק הרשאה.
- השירות שלך יוצר קוד אישור ומחזיר אותו ל- Google. לשם כך, הפנה את הדפדפן של המשתמש בחזרה לגוגל עם קוד ההרשאה המצורף לבקשה.
- גוגל שולחת את קוד האישור לנקודה הסיום החילוף האסימון שלך, אשר מאמת את האותנטיות של הקוד ומחזיר גישת אסימון רענון אסימון. אסימון הגישה הוא אסימון קצר מועד שהשירות שלך מקבל כאישורים לגישה לממשקי API. אסימון הרענון הוא אסימון ארוך טווח שגוגל יכולה לאחסן ולהשתמש בו כדי לרכוש אסימוני גישה חדשים כאשר תוקפם יפוג.
- לאחר שהמשתמש סיים את תהליך קישור החשבון, כל בקשה שלאחר מכן שנשלחה מ-Google מכילה אסימון גישה.
טיפול בבקשות הרשאה
כאשר אתה צריך לבצע קישור חשבון באמצעות זרימת קוד ההרשאה של OAuth 2.0, Google שולחת את המשתמש לנקודת הקצה של ההרשאה שלך עם בקשה הכוללת את הפרמטרים הבאים:
פרמטרים של נקודת קצה הרשאה | |
---|---|
client_id | מזהה הלקוח שהקצית ל-Google. |
redirect_uri | כתובת האתר שאליה אתה שולח את התגובה לבקשה זו. |
state | ערך הנהלת חשבונות המועבר בחזרה ל-Google ללא שינוי ב-URI להפניה מחדש. |
scope | אופציונלי: סט מופרדת ברווחים של מחרוזות היקף המציינים את הנתונים של Google מבקשת אישור. |
response_type | סוג הערך שיש להחזיר בתגובה. עבור זרימת קוד 2.0 אישור OAuth, את סוג התגובה הוא תמיד code . |
user_locale | הגדרת השפה של חשבון Google RFC5646 פורמט, נהגה לבצע לוקליזציה התוכן שלך בשפה המועדפת של המשתמש. |
לדוגמה, אם נקודת הסיום אישורך זמין בכתובת https://myservice.example.com/auth
, בקשה עשוי להיראות כך:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
כדי שנקודת הקצה של ההרשאה שלך יטפל בבקשות כניסה, בצע את השלבים הבאים:
- ודא
client_id
תואם את זיהוי לקוח שהקצית גוגל, וכיredirect_uri
תואם את כתובת האתר הפניה מסופק על ידי גוגל עבור השירות שלך. בדיקות אלו חשובות כדי למנוע הענקת גישה ליישומי לקוח לא מכוונים או בתצורה שגויה. אם אתה תומך מרובה OAuth 2.0 תזרימים, גם מאשר כיresponse_type
הואcode
. - בדוק אם המשתמש מחובר לשירות שלך. אם המשתמש אינו מחובר, השלם את תהליך הכניסה או ההרשמה של השירות שלך.
- צור קוד הרשאה ש-Google תשתמש בו כדי לגשת ל-API שלך. קוד ההרשאה יכול להיות כל ערך מחרוזת, אך עליו לייצג באופן ייחודי את המשתמש, את הלקוח עבורו מיועד האסימון ואת זמן התפוגה של הקוד, ואין לנחש אותו. בדרך כלל אתה מנפיק קודי הרשאה שפג תוקפם לאחר כ-10 דקות.
- אשר שכתובת האתר שצוין על ידי
redirect_uri
פרמטר יש את הטופס הבא:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- נתב מחדש את הדפדפן של המשתמש לכתובת שצוינה על ידי
redirect_uri
פרמטר. כלול את קוד האישור אתה פשוט שנוצרת ואת מקורי, ערך מדינה ללא שינוי בעת ביצוע ההפניה מחדש על ידי צירוףcode
ואתstate
הפרמטרים. להלן דוגמא של האתר שמתקבל:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
טיפול בבקשות להחלפת אסימונים
נקודת הקצה של החלפת אסימונים של השירות שלך אחראית לשני סוגים של החלפת אסימונים:
- החלף קודי הרשאה עבור אסימוני גישה ואסימוני רענון
- החלף אסימוני רענון לאסימוני גישה
בקשות להחלפת אסימונים כוללות את הפרמטרים הבאים:
פרמטרים של נקודת קצה של החלפת אסימונים | |
---|---|
client_id | מחרוזת המזהה את מקור הבקשה כ-Google. מחרוזת זו חייבת להיות רשומה במערכת שלך כמזהה ייחודי של Google. |
client_secret | מחרוזת סודית שרשמת ב-Google עבור השירות שלך. |
grant_type | סוג האסימון המוחלף. זה גם authorization_code או refresh_token . |
code | כאשר grant_type=authorization_code , פרמטר זה הוא הקוד של גוגל קבל משתי הכניסה שלך או נקודת הסיום חילוף אסימון. |
redirect_uri | כאשר grant_type=authorization_code , פרמטר זה הוא האתר שנמצא בשימוש בקשת האישור הראשוני. |
refresh_token | כאשר grant_type=refresh_token , פרמטר זה הוא לרענן את אסימון Google שהתקבל הסיום החילוף האסימון שלך. |
החלף קודי הרשאה עבור אסימוני גישה ואסימוני רענון
לאחר שהמשתמש נכנס ונקודת קצה ההרשאה שלך מחזירה קוד הרשאה קצר מועד ל-Google, Google שולחת בקשה לנקודת הקצה של החלפת האסימונים שלך להחליף את קוד ההרשאה לאסימון גישה ואסימון רענון.
לקבלת בקשות אלה, הערך של grant_type
הוא authorization_code
, ואת הערך של code
הוא הערך של קוד האישור שנתן בעבר ל- Google. להלן דוגמה לבקשה להחליף קוד הרשאה עבור אסימון גישה ואסימון רענון:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
כדי להחליף קודי הרשאה עבור גישת אסימון רענון אסימון, מגיב הסיום חילוף האסימון שלך POST
בקשות על ידי ביצוע הצעדים הבאים:
- ודא
client_id
מזהה את מקור הבקשה בתור מקור מוסמך, וכיclient_secret
תואם את הערך הצפוי. - ודא שקוד ההרשאה חוקי ולא פג, ושמזהה הלקוח שצוין בבקשה תואם לזהות הלקוח המשויך לקוד ההרשאה.
- אשר שכתובת האתר שצוינה על ידי
redirect_uri
הפרמטר זהה לערך משמש בבקשת האישור הראשונית. - אם אתה לא יכול לאמת את כל הקריטריונים הנ"ל, להחזיר שגיאה בקשה שגויה HTTP 400 עם
{"error": "invalid_grant"}
כגוף. - אחרת, השתמש במזהה המשתמש מקוד ההרשאה כדי ליצור אסימון רענון ואסימון גישה. אסימונים אלה יכולים להיות כל ערך מחרוזת, אך עליהם לייצג באופן ייחודי את המשתמש ואת הלקוח עבורו מיועד האסימון, ואסור שהם ניתנים לניחוש. עבור אסימוני גישה, רשמו גם את זמן התפוגה של האסימון, שהוא בדרך כלל שעה לאחר הנפקת האסימון. אסימוני רענון לא יפוג.
- החזר את אובייקט JSON הבא בגוף התגובה HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
גוגל מאחסנת את אסימון הגישה ואת אסימון הרענון עבור המשתמש ומתעדת את תפוגה של אסימון הגישה. כאשר תוקף אסימון הגישה יפוג, Google משתמשת באסימון הרענון כדי לקבל אסימון גישה חדש מנקודת הקצה של החלפת האסימונים שלך.
החלף אסימוני רענון לאסימוני גישה
כאשר תוקף אסימון גישה פג, Google שולחת בקשה לנקודת הקצה של החלפת האסימונים שלך להחליף אסימון רענון לאסימון גישה חדש.
לקבלת בקשות אלה, הערך של grant_type
הוא refresh_token
, ואת הערך של refresh_token
הוא הערך של רענון אסימון שנתן בעבר ל- Google. להלן דוגמה לבקשה להחליף אסימון רענון לאסימון גישה:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
כדי להחליף אסימון רענון לקוד גישה, מגיב הסיום חילוף האסימון שלך POST
בקשות על ידי ביצוע הצעדים הבאים:
- ודא
client_id
מזהה את מקור הבקשה כפי גוגל, וכיclient_secret
תואם את הערך הצפוי. - ודא שאסימון הרענון חוקי ושמזהה הלקוח שצוין בבקשה תואם לזיהוי הלקוח המשויך לאסימון הרענון.
- אם אתה לא יכול לאמת את כל הקריטריונים הנ"ל, להחזיר שגיאה בקשה שגויה HTTP 400 עם
{"error": "invalid_grant"}
כגוף. - אחרת, השתמש במזהה המשתמש מתוך אסימון הרענון כדי ליצור אסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם חייבים לייצג באופן ייחודי את המשתמש ואת הלקוח שהאסימון מיועד, ואסור להם להיות ניתנים לניחוש. עבור אסימוני גישה, רשמו גם את זמן התפוגה של האסימון, בדרך כלל שעה לאחר הנפקת האסימון.
- החזר את אובייקט ה-JSON הבא בגוף תגובת ה-HTTPS:
{ "token_type": "Bearer", "access_token": " ACCESS_TOKEN ", "expires_in": SECONDS_TO_EXPIRATION }
טיפול בבקשות למידע משתמש
סיום UserInfo הוא משאב מוגן 2.0 OAuth כי טענות החזרה על המשתמש המקושר. הטמעה ואירוח של נקודת הקצה של מידע המשתמש היא אופציונלית, למעט מקרי השימוש הבאים:
- מקושרים הכניס לחשבון עם Google One Tap.
- מנוי חיכוך על androidtv.
לאחר שאחזור אסימון הגישה בהצלחה מנקודת הקצה האסימון שלך, Google שולחת בקשה לנקודת הקצה של פרטי המשתמש שלך כדי לאחזר מידע בסיסי על הפרופיל על המשתמש המקושר.
כותרות בקשת נקודת קצה של מידע משתמש | |
---|---|
Authorization header | אסימון הגישה מסוג Bearer. |
לדוגמה, אם שלך הסיום UserInfo זמין בכתובת https://myservice.example.com/userinfo
, בקשה עשוי להיראות כך:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
כדי שנקודת הקצה של פרטי המשתמש שלך תטפל בבקשות, בצע את הצעדים הבאים:
- חלץ אסימון גישה מכותרת ההרשאה והחזר מידע עבור המשתמש המשויך לאסימון הגישה.
- אם את האסימון הגישה אינו חוקי, להחזיר שגיאה HTTP לא מורשה 401 עם באמצעות
WWW-Authenticate
בכותרת התגובה. להלן דוגמה של תגובת שגיאת UserInfo:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
אם 401 לא מורשה, או כול תגובת שגיאת חסרי-ההצלחה מוחזר בזמן תהליך הקישור, הטעות תהיה אי-השבה, האסימון שהורד לא ייפסל והמשתמש יצטרך כדי להתחיל שוב את תהליך הקישור. אם אסימון הגישה תקפה, השיבה HTTP 200 בתגובה עם אובייקט JSON הבא בגוף התגובה HTTPS:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
אם מחזיר הסיום UserInfo שלך לתגובה הצלחה HTTP 200, את לאחזר אסימון ותביעות רשומים נגד המשתמשים של גוגל חֶשְׁבּוֹן.תגובת נקודת הקצה של מידע משתמש sub
מזהה ייחודי המזהה את המשתמש במערכת שלך. email
כתובת האימייל של המשתמש. given_name
אופציונלי: שם פרטי של המשתמש. family_name
אופציונלי: שם משפחה של המשתמש. name
אופציונלי: שם מלא של המשתמש. picture
תמונת הפרופיל של המשתמש: אופציונלי.
אימות ההטמעה
אתה יכול לאמת את הביצוע שלך באמצעות מגרש 2.0 OAuth הכלי.
בצע את הפעולות הבאות בכלי:
- לחץ תצורת כדי לפתוח את חלון תצורת 2.0 OAuth.
- בתחום זרימת OAuth, בחר בצד הלקוח.
- בתחום נקודות קצה OAuth, בחר Custom.
- ציין את נקודת הקצה של OAuth 2.0 ואת מזהה הלקוח שהקצית ל- Google בשדות המתאימים.
- במקטע שלב 1, לא יבחר אף היקפי Google. במקום זאת, השאר שדה זה ריק או הקלד טווח תקף עבור השרת שלך (או מחרוזת שרירותית אם אינך משתמש בהיקפי OAuth). כשתסיים, לחץ על הרשה APIs.
- בסעיפים שלב 2 ושלב 3, לעבור את זרימת 2.0 OAuth ולוודא כי כל צעד עובד כמתוכנן.
אתה יכול לאמת את הביצוע שלך באמצעות קישור הדגמת חשבון Google הכלי.
בצע את הפעולות הבאות בכלי:
- לחץ על כניסה עם כפתור גוגל.
- בחר את החשבון שברצונך לקשר.
- הזן את מזהה השירות.
- לחלופין, הזן אחד או יותר טווחים שאליהם תבקש גישה.
- לחץ על התחל הדגמה.
- כשתתבקש, אשר שאתה רשאי להסכים ולדחות את בקשת הקישור.
- אשר שהפנית לפלטפורמה שלך.