هر اقدام smart home باید مکانیزمی برای احراز هویت کاربران داشته باشد.
احراز هویت به شما امکان میدهد حسابهای Google کاربران خود را با حسابهای کاربری در سیستم احراز هویت خود پیوند دهید. این به شما این امکان را می دهد که کاربران خود را هنگامی که تحقق شما هدف خانه هوشمند دریافت می کند شناسایی کنید. خانه هوشمند Google فقط از OAuth با جریان کد مجوز پشتیبانی می کند.
این صفحه نحوه راهاندازی سرور OAuth 2.0 را توضیح میدهد تا با اکشن smart home شما کار کند.
پیوند حساب 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:
- 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.
- 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
- You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
- 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.
- You must provide a way for users to go back or cancel, if they choose not to link.
- 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:
Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
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.
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.
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.
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 آغاز شده است دارای جریان زیر است:
- Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می کند. اگر جریان در یک دستگاه فقط صوتی برای یک Action شروع شود، Google اجرا را به تلفن منتقل میکند.
- اگر کاربر قبلاً وارد سیستم نشده باشد، وارد سیستم میشود، و به Google اجازه میدهد تا با API شما به دادههای خود دسترسی داشته باشد، اگر قبلاً اجازه نداده باشد.
- سرویس شما یک کد مجوز ایجاد می کند و آن را به Google برمی گرداند. برای انجام این کار، مرورگر کاربر را با کد مجوز پیوست شده به درخواست به Google هدایت کنید.
- Google کد مجوز را به نقطه پایانی تبادل رمز شما میفرستد، که صحت کد را تأیید میکند و یک نشانه دسترسی و یک نشانه تازهسازی را برمیگرداند. نشانه دسترسی یک توکن کوتاه مدت است که سرویس شما آن را به عنوان اعتبار برای دسترسی به APIها می پذیرد. توکن رفرش یک توکن با عمر طولانی است که گوگل می تواند آن را ذخیره کرده و از آن برای بدست آوردن توکن های دسترسی جدید پس از انقضا استفاده کند.
- پس از تکمیل جریان پیوند حساب توسط کاربر، هر درخواست بعدی که از Google ارسال میشود حاوی یک نشانه دسترسی است.
رسیدگی به درخواست های مجوز
هنگامی که باید پیوند حساب را با استفاده از جریان کد مجوز OAuth 2.0 انجام دهید، Google کاربر را با درخواستی که شامل پارامترهای زیر است به نقطه پایانی مجوز شما می فرستد:
پارامترهای نقطه پایانی مجوز | |
---|---|
client_id | شناسه مشتری که به Google اختصاص داده اید. |
redirect_uri | آدرس اینترنتی که پاسخ این درخواست را به آن ارسال می کنید. |
state | یک مقدار حسابداری که بدون تغییر در URI تغییر مسیر به Google بازگردانده می شود. |
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
برای اینکه نقطه پایانی مجوز شما به درخواستهای ورود به سیستم رسیدگی کند، مراحل زیر را انجام دهید:
- بررسی کنید که
client_id
با شناسه مشتری که به Google اختصاص داده اید مطابقت داشته باشد وredirect_uri
با URL تغییر مسیر ارائه شده توسط Google برای سرویس شما مطابقت داشته باشد. این بررسی ها برای جلوگیری از اعطای دسترسی به برنامه های مشتری ناخواسته یا پیکربندی نادرست مهم هستند. اگر از چند جریان OAuth 2.0 پشتیبانی می کنید، همچنین تأیید کنید کهresponse_type
code
. - بررسی کنید که آیا کاربر به سرویس شما وارد شده است یا خیر. اگر کاربر وارد سیستم نشده است، جریان ورود به سیستم یا ثبت نام سرویس خود را تکمیل کنید.
- یک کد مجوز برای Google ایجاد کنید تا از آن برای دسترسی به API شما استفاده کند. کد مجوز میتواند هر مقدار رشتهای باشد، اما باید بهطور منحصربهفرد نشاندهنده کاربر، کلاینت توکن و زمان انقضای کد باشد، و نباید قابل حدس زدن باشد. شما معمولاً کدهای مجوز صادر می کنید که پس از تقریباً 10 دقیقه منقضی می شوند.
- تأیید کنید که URL مشخص شده توسط پارامتر
redirect_uri
شکل زیر را دارد:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- مرورگر کاربر را به URL مشخص شده توسط پارامتر
redirect_uri
کنید. هنگام تغییر مسیر با افزودنcode
و پارامترهایstate
، کد مجوزی را که به تازگی ایجاد کردهاید و مقدار حالت اصلی و اصلاح نشده را وارد کنید. مثال زیر نمونه ای از URL به دست آمده است: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 ، این پارامتر کدی است که Google از نقطه پایانی ورود به سیستم یا تبادل رمز شما دریافت کرده است. |
redirect_uri | وقتی grant_type=authorization_code ، این پارامتر URL مورد استفاده در درخواست مجوز اولیه است. |
refresh_token | هنگامی که grant_type=refresh_token ، این پارامتر نشانه تازهسازی است که Google از نقطه پایانی تبادل توکن شما دریافت کرده است. |
کدهای مجوز را برای توکن های دسترسی و رفرش کردن نشانه ها مبادله کنید
پس از اینکه کاربر وارد سیستم شد و نقطه پایان مجوز شما یک کد مجوز کوتاه مدت را به Google برگرداند، Google درخواستی را به نقطه پایانی مبادله رمز شما ارسال میکند تا کد مجوز را با یک نشانه دسترسی و یک نشانه تازهسازی مبادله کند.
برای این درخواستها، مقدار grant_type
است و مقدار code
مقدار کد authorization_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
با مقدار مورد انتظار مطابقت دارد. - بررسی کنید که کد مجوز معتبر است و منقضی نشده است و شناسه مشتری مشخص شده در درخواست با شناسه مشتری مرتبط با کد مجوز مطابقت دارد.
- تأیید کنید که URL مشخص شده توسط پارامتر
redirect_uri
با مقدار مورد استفاده در درخواست مجوز اولیه یکسان است. - اگر نمیتوانید همه معیارهای بالا را تأیید کنید، یک خطای HTTP 400 Bad Request را با
{"error": "invalid_grant"}
به عنوان متن بازگردانید. - در غیر این صورت، از شناسه کاربری موجود در کد مجوز برای ایجاد یک نشانه تازهسازی و یک نشانه دسترسی استفاده کنید. این توکنها میتوانند هر مقدار رشتهای باشند، اما باید بهطور منحصربهفرد نشاندهنده کاربر و مشتریای باشند که توکن برای آن است، و نباید قابل حدس زدن باشند. برای توکنهای دسترسی، زمان انقضای توکن را نیز ثبت کنید، که معمولاً یک ساعت پس از صدور توکن است. نشانههای Refresh منقضی نمیشوند.
- شی 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
مبدا درخواست را به عنوان Google شناسایی میکند، و اینکهclient_secret
با مقدار مورد انتظار مطابقت دارد. - بررسی کنید که کد بازخوانی معتبر است، و شناسه مشتری مشخص شده در درخواست با شناسه مشتری مرتبط با نشانه بازخوانی مطابقت دارد.
- اگر نمیتوانید همه معیارهای بالا را تأیید کنید، یک خطای HTTP 400 Bad Request را با
{"error": "invalid_grant"}
به عنوان متن بازگردانید. - در غیر این صورت، از شناسه کاربری موجود در نشانه رفرش برای ایجاد یک نشانه دسترسی استفاده کنید. این توکنها میتوانند هر مقدار رشتهای باشند، اما باید بهطور منحصربهفرد نشاندهنده کاربر و مشتریای باشند که توکن برای آن است، و نباید قابل حدس زدن باشند. برای توکنهای دسترسی، زمان انقضای توکن را نیز ثبت کنید، معمولاً یک ساعت پس از صدور توکن.
- شی 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:
- Extract access token from the Authorization header and return information for the user associated with the access token.
- 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. 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.