הטמעה של שרת OAuth 2.0

כל שילוב של Cloud-to-cloud חייב לכלול מנגנון לאימות משתמשים.

אימות מאפשר לקשר את חשבונות Google של המשתמשים לחשבונות המשתמשים במערכת האימות. כך תוכלו לזהות את המשתמשים שלכם כשהמערכת לטיפול בהזמנות תקבל כוונה לבית חכם. ב-Google Home יש תמיכה ב-OAuth רק עם תהליך של קוד הרשאה.

בדף הזה מוסבר איך להגדיר את שרת OAuth 2.0 כך שיעבוד עם השילוב של Cloud-to-cloud.

קישור חשבון Google באמצעות OAuth

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
2. You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
3. You must provide a way for users to go back or cancel, if they choose not to link.
4. You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

5. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking.

6. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

תהליך קוד ההרשאה

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

כשאפליקציה של Google צריכה לקרוא לאחד מממשקי ה-API של השירות שלכם, Google משתמשת בנקודות הקצה האלה יחד כדי לקבל מהמשתמשים הרשאה לקרוא לממשקי ה-API האלה בשמם.

סשן של תהליך קוד הרשאה ב-OAuth 2.0 שמופעל על ידי Google מתבצע לפי התהליך הבא:

1. Google פותחת את נקודת הקצה (endpoint) של ההרשאה בדפדפן של המשתמש. אם התהליך התחיל במכשיר קולי בלבד עבור פעולה, Google מעבירה את הביצוע לטלפון.
2. המשתמש מתחבר לחשבון, אם הוא עדיין לא מחובר, ומעניק ל-Google הרשאה לגשת לנתונים שלו באמצעות ה-API, אם הוא עדיין לא העניק הרשאה כזו.
3. השירות יוצר קוד הרשאה ומחזיר אותו ל-Google. כדי לעשות זאת, מפנים את הדפדפן של המשתמש בחזרה אל Google עם קוד ההרשאה שמצורף לבקשה.
4. Google שולחת את קוד ההרשאה לנקודת הקצה של המרת האסימון, שם מתבצע אימות של האותנטיות של הקוד ומוחזר אסימון גישה ואסימון רענון. אסימון הגישה הוא אסימון לטווח קצר שהשירות מקבל כפרטי כניסה כדי לגשת לממשקי API. אסימון הרענון הוא אסימון לטווח ארוך ש-Google יכולה לאחסן ולהשתמש בו כדי לקבל אסימוני גישה חדשים כשפג התוקף שלהם.
5. אחרי שהמשתמש משלים את תהליך הקישור של החשבון, כל בקשה שנשלחת לאחר מכן מ-Google מכילה אסימון גישה.

טיפול בבקשות הרשאה

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

פרמטרים של נקודת קצה להרשאה
client_id	מזהה הלקוח שהקצית ל-Google.
redirect_uri	כתובת ה-URL שאליה שולחים את התשובה לבקשה הזו.
state	ערך חשבונאי שמוחזר ל-Google ללא שינוי ב-URI של ההפניה האוטומטית.
scope	אופציונלי: קבוצה של מחרוזות היקף מופרדות באמצעות רווחים, שמציינות את הנתונים ש-Google מבקשת הרשאה לגביהם.
response_type	סוג הערך להחזרה בתגובה. בתהליך של קוד ההרשאה של OAuth 2.0, סוג התגובה הוא תמיד 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

כדי שנקודת הקצה של ההרשאה תעבד בקשות כניסה, צריך לבצע את השלבים הבאים:

1. מוודאים ש-client_id תואם למזהה הלקוח שהקציתם ל-Google, וש-redirect_uri תואם לכתובת ה-URL להפניה אוטומטית ש-Google מספקת לשירות שלכם. הבדיקות האלה חשובות כדי למנוע מתן גישה לאפליקציות לקוח לא רצויות או לאפליקציות עם הגדרות שגויות. אם אתם תומכים בכמה תהליכי OAuth 2.0, צריך לוודא גם שהערך של response_type הוא code.
2. בודקים אם המשתמש מחובר לשירות. אם המשתמש לא מחובר לחשבון, צריך להשלים את תהליך הכניסה או ההרשמה לשירות.
3. יוצרים קוד הרשאה ש-Google תשתמש בו כדי לגשת ל-API שלכם. קוד ההרשאה יכול להיות כל ערך מחרוזת, אבל הוא חייב לייצג באופן ייחודי את המשתמש, את הלקוח שהאסימון מיועד לו ואת מועד התפוגה של הקוד, ואי אפשר לנחש אותו. בדרך כלל, מונפקים קודי הרשאה שתוקפם פג לאחר כ-10 דקות.
4. מוודאים שכתובת ה-URL שצוינה באמצעות הפרמטר redirect_uri היא בפורמט הבא:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

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

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

טיפול בבקשות להחלפת אסימונים

נקודת הקצה (endpoint) של שירות המרות האסימונים אחראית לשני סוגים של המרות אסימונים:

• המרת קודי הרשאה באסימוני גישה ובאסימוני רענון
• המרת אסימוני רענון לאסימוני גישה

בקשות להחלפת אסימונים כוללות את הפרמטרים הבאים:

הפרמטרים של נקודת הקצה להחלפת אסימונים
client_id	מחרוזת שמזהה את מקור הבקשה כ-Google. המחרוזת הזו צריכה להיות רשומה במערכת שלכם כמזהה הייחודי של Google.
client_secret	מחרוזת סודית שרשומה ב-Google לשירות שלכם.
grant_type	סוג הטוקן שמתבצעת בו המרה. הערך יכול להיות authorization_code או refresh_token.
code	כשהערך של grant_type=authorization_code הוא 1, הפרמטר הזה הוא הקוד ש-Google קיבלה מנקודת הקצה (endpoint) של הכניסה או של המרת האסימון.
redirect_uri	כשהערך הוא grant_type=authorization_code, הפרמטר הזה הוא כתובת ה-URL ששימשה בבקשת ההרשאה הראשונית.
refresh_token	כשהערך הוא grant_type=refresh_token, הפרמטר הזה הוא אסימון הרענון ש-Google קיבלה מנקודת הקצה של החלפת האסימונים.

הגדרת האופן שבו Google שולחת את פרטי הכניסה לשרת

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

כברירת מחדל, Google שולחת את פרטי הכניסה בגוף הבקשה. אם שרת ההרשאות מחייב שפרטי הכניסה של הלקוח יהיו בכותרת הבקשה, צריך להגדיר את השילוב של Cloud-to-cloud בהתאם:

כניסה למסוף הפיתוח

1. ברשימת הפרויקטים, לוחצים על פתיחה לצד הפרויקט שרוצים לעבוד איתו.

2. בקטע מענן לענן, בוחרים באפשרות פיתוח.

3. לוחצים על Open (פתיחה) לצד השילוב.

4. גוללים למטה לקטע Permissions (optional) ומסמנים את התיבה Have Google transmit Client ID and secret via HTTP basic auth header.

5. לוחצים על שמירה כדי לשמור את השינויים.

המרת קודי הרשאה באסימוני גישה ובאסימוני רענון

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

1. מוודאים שהשדה client_id מזהה את מקור הבקשה כמקור מורשה, ושהשדה client_secret תואם לערך הצפוי.
2. מוודאים שקוד ההרשאה תקף ושלא פג התוקף שלו, ושמזהה הלקוח שצוין בבקשה תואם למזהה הלקוח שמשויך לקוד ההרשאה.
3. מוודאים שכתובת ה-URL שצוינה בפרמטר redirect_uri זהה לערך שנעשה בו שימוש בבקשת ההרשאה הראשונית.
4. אם אי אפשר לאמת את כל הקריטריונים שלמעלה, צריך להחזיר שגיאת HTTP 400 Bad Request עם {"error": "invalid_grant"} כתוכן.
5. אחרת, משתמשים במזהה המשתמש מקוד ההרשאה כדי ליצור אסימון רענון ואסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם חייבים לייצג באופן ייחודי את המשתמש ואת הלקוח שהאסימון מיועד להם, ואי אפשר לנחש אותם. באסימוני גישה, צריך לתעד גם את זמן התפוגה של האסימון, שבדרך כלל הוא שעה אחת אחרי הנפקת האסימון. תוקף של אסימוני רענון לא פג.
6. מחזירים את אובייקט ה-JSON הבא בגוף התגובה של ה-HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

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

1. מוודאים שהערך של client_id מזהה את מקור הבקשה כ-Google, ושערך client_secret תואם לערך הצפוי.
2. מוודאים שאסימון הרענון תקף, ומזהה הלקוח שצוין בבקשה תואם למזהה הלקוח שמשויך לאסימון הרענון.
3. אם אי אפשר לאמת את כל הקריטריונים שלמעלה, צריך להחזיר שגיאת HTTP 400 Bad Request עם {"error": "invalid_grant"} כגוף.
4. אחרת, משתמשים במזהה המשתמש מאסימון הרענון כדי ליצור אסימון גישה. האסימונים האלה יכולים להיות כל ערך מחרוזת, אבל הם חייבים לייצג באופן ייחודי את המשתמש ואת הלקוח שהאסימון מיועד להם, ואי אפשר לנחש אותם. באסימוני גישה, צריך לתעד גם את זמן התפוגה של האסימון, בדרך כלל שעה אחרי הנפקת האסימון.
5. מחזירים את אובייקט ה-JSON הבא בגוף התגובה של ה-HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header	The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }
   

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   userinfo endpoint response
   sub	A unique ID that identifies the user in your system.
   email	Email address of the user.
   given_name	Optional: First name of the user.
   family_name	Optional: Last name of the user.
   name	Optional: Full name of the user.
   picture	Optional: Profile picture of the user.