حسابها با استفاده از جریانهای کد ضمنی و مجوزدهی استاندارد صنعتی OAuth 2.0 به هم مرتبط میشوند.
سرویس شما باید از نقاط پایانی احراز هویت و تبادل توکن سازگار با OAuth 2.0 پشتیبانی کند.
In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.
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.
Choose an OAuth 2.0 flow
Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.
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.
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 cancel. Provide a way for users to go back or cancel, if they choose not to link.
Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.
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 and the implicit flow.
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.
پروژه را ایجاد کنید
برای ایجاد پروژه خود با استفاده از پیوند حساب:
- به کنسول API گوگل بروید.
- روی ایجاد پروژه کلیک کنید.
- یک نام وارد کنید یا پیشنهاد تولید شده را بپذیرید.
- فیلدهای باقی مانده را تأیید یا ویرایش کنید.
- روی ایجاد کلیک کنید.
برای مشاهده شناسه پروژه خود:
- به کنسول API گوگل بروید.
- پروژه خود را در جدول صفحه اصلی پیدا کنید. شناسه پروژه در ستون شناسه نمایش داده میشود.
صفحه رضایت OAuth خود را پیکربندی کنید
فرآیند پیوند حساب گوگل شامل یک صفحه رضایتنامه است که به کاربران میگوید برنامهای که درخواست دسترسی به دادههای آنها را دارد، چه نوع دادههایی را درخواست میکند و شرایط اعمال آن چیست. قبل از ایجاد شناسه کلاینت Google API، باید صفحه رضایتنامه OAuth خود را پیکربندی کنید.
- صفحهی رضایتنامهی OAuth را در کنسول Google APIs باز کنید.
- در صورت درخواست، پروژهای را که تازه ایجاد کردهاید انتخاب کنید.
در صفحه «صفحه رضایت OAuth»، فرم را پر کنید و روی دکمه «ذخیره» کلیک کنید.
نام برنامه: نام برنامهای که درخواست رضایت میکند. این نام باید دقیقاً منعکسکننده برنامه شما باشد و با نام برنامهای که کاربران در جاهای دیگر میبینند، مطابقت داشته باشد. نام برنامه در صفحه رضایتنامه پیوند حساب نمایش داده خواهد شد.
لوگوی برنامه: تصویری در صفحه رضایتنامه که به کاربران کمک میکند برنامه شما را بشناسند. این لوگو در صفحه رضایتنامه پیوند حساب و در تنظیمات حساب نمایش داده میشود.
ایمیل پشتیبانی: برای اینکه کاربران بتوانند در مورد رضایت خود با شما تماس بگیرند.
حوزههای دسترسی برای APIهای گوگل: حوزهها به برنامه شما اجازه میدهند تا به دادههای خصوصی گوگل کاربر دسترسی داشته باشد. برای مورد استفاده اتصال حساب گوگل، حوزه پیشفرض (ایمیل، نمایه، شناسه باز) کافی است، نیازی به اضافه کردن هیچ حوزه حساسی ندارید. به طور کلی، بهترین روش این است که حوزهها را به صورت تدریجی، در زمانی که دسترسی مورد نیاز است، درخواست کنید، نه اینکه از ابتدا درخواست دهید. اطلاعات بیشتر .
دامنههای مجاز: برای محافظت از شما و کاربرانتان، گوگل فقط به برنامههایی که با استفاده از OAuth احراز هویت میشوند، اجازه استفاده از دامنههای مجاز را میدهد. لینکهای برنامههای شما باید در دامنههای مجاز میزبانی شوند. اطلاعات بیشتر .
لینک صفحه اصلی برنامه: صفحه اصلی برنامه شما. باید روی یک دامنه مجاز میزبانی شود.
پیوند سیاست حفظ حریم خصوصی برنامه: در صفحه رضایتنامه پیوند حساب گوگل نشان داده میشود. باید در یک دامنه مجاز میزبانی شود.
لینک شرایط خدمات برنامه (اختیاری): باید روی یک دامنه مجاز میزبانی شود.
شکل ۱. صفحه رضایتنامه اتصال حساب گوگل برای یک برنامه جعلی، Tunery
«وضعیت تأیید» را بررسی کنید، اگر درخواست شما نیاز به تأیید دارد، روی دکمه «ارسال برای تأیید» کلیک کنید تا درخواست شما برای تأیید ارسال شود. برای جزئیات بیشتر به الزامات تأیید OAuth مراجعه کنید.
سرور OAuth خود را پیادهسازی کنید
ن
برای پشتیبانی از جریان ضمنی OAuth 2.0، سرویس شما یک نقطه پایانی مجوزدهی را از طریق HTTPS در دسترس قرار میدهد. این نقطه پایانی مسئول احراز هویت و اخذ رضایت از کاربران برای دسترسی به دادهها است. نقطه پایانی مجوزدهی، یک رابط کاربری ورود به سیستم را به کاربرانی که هنوز وارد سیستم نشدهاند، ارائه میدهد و رضایت آنها را برای دسترسی درخواستی ثبت میکند.
وقتی یک برنامه گوگل نیاز به فراخوانی یکی از APIهای مجاز سرویس شما دارد، گوگل از این نقطه پایانی برای دریافت مجوز از کاربران شما برای فراخوانی این APIها از طرف آنها استفاده میکند.
لینک کردن حساب گوگل: جریان ضمنی OAuth
نمودار توالی زیر، جزئیات تعاملات بین کاربر، گوگل و نقاط پایانی سرویس شما را نشان میدهد.
نقشها و مسئولیتها
جدول زیر نقشها و مسئولیتهای بازیگران در جریان ضمنی OAuth لینکینگ حساب گوگل (GAL) را تعریف میکند. توجه داشته باشید که در GAL، گوگل به عنوان کلاینت OAuth عمل میکند، در حالی که سرویس شما به عنوان ارائهدهنده هویت/سرویس عمل میکند.
| بازیگر / جزء | نقش GAL | مسئولیتها |
|---|---|---|
| برنامه/سرور گوگل | کلاینت OAuth | جریان را آغاز میکند، توکن دسترسی را با استفاده از تغییر مسیر مرورگر دریافت میکند و آن را به صورت ایمن برای دسترسی به APIهای سرویس شما ذخیره میکند. |
| نقطه پایانی مجوز شما | سرور احراز هویت | کاربران شما را احراز هویت میکند، رضایت آنها را دریافت میکند و توکنهای دسترسی بلندمدت را مستقیماً برای گوگل صادر میکند. |
| آدرس اینترنتی ریدایرکت گوگل | نقطه پایانی پاسخ به تماس | تغییر مسیر کاربر را از سرویس احراز هویت شما به همراه مقادیر access_token و state در قطعه URL دریافت میکند. |
یک جلسه جریان ضمنی OAuth 2.0 معمولی که توسط گوگل آغاز میشود، جریان زیر را دارد:
- گوگل نقطه پایانی مجوز شما را در مرورگر کاربر باز میکند. کاربر، اگر قبلاً وارد سیستم نشده باشد، وارد سیستم میشود و اگر قبلاً اجازه نداده باشد، به گوگل اجازه دسترسی به دادههایش با API شما را میدهد.
- سرویس شما یک توکن دسترسی ایجاد میکند و آن را به گوگل برمیگرداند. برای انجام این کار، مرورگر کاربر را به گوگل هدایت کنید و توکن دسترسی به درخواست پیوست شود.
- گوگل APIهای سرویس شما را فراخوانی میکند و توکن دسترسی را به هر درخواست پیوست میکند. سرویس شما تأیید میکند که توکن دسترسی، مجوز دسترسی به API را به گوگل میدهد و سپس فراخوانی API را تکمیل میکند.
رسیدگی به درخواستهای مجوز
وقتی یک برنامه گوگل نیاز به انجام پیوند حساب با استفاده از جریان ضمنی OAuth 2.0 دارد، گوگل کاربر را با درخواستی که شامل پارامترهای زیر است به نقطه پایانی مجوز شما ارسال میکند:
| پارامترهای نقطه پایانی احراز هویت | |
|---|---|
client_id | شناسه کلاینتی که به گوگل اختصاص دادهاید. |
redirect_uri | آدرس اینترنتی (URL) که پاسخ این درخواست را به آن ارسال میکنید. |
state | یک مقدار حسابداری که بدون تغییر در URL تغییر مسیر به گوگل بازگردانده میشود. |
response_type | نوع مقداری که در پاسخ برگردانده میشود. برای جریان ضمنی OAuth 2.0، نوع پاسخ همیشه token است. |
user_locale | تنظیمات زبان حساب گوگل در قالب RFC5646 که برای بومیسازی محتوای شما به زبان دلخواه کاربر استفاده میشود. |
برای مثال، اگر نقطه پایانی مجوز شما در https://myservice.example.com/auth موجود باشد، یک درخواست ممکن است به شکل زیر باشد:
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE
برای اینکه نقطه پایانی احراز هویت شما بتواند درخواستهای ورود به سیستم را مدیریت کند، مراحل زیر را انجام دهید:
مقادیر
client_idوredirect_uriرا تأیید کنید تا از اعطای دسترسی به برنامههای کلاینت ناخواسته یا با پیکربندی نادرست جلوگیری شود:- تأیید کنید که
client_idبا client ID که به گوگل اختصاص دادهاید، مطابقت دارد. - تأیید کنید که URL مشخص شده توسط پارامتر
redirect_uriبه شکل زیر باشد:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- تأیید کنید که
بررسی کنید که آیا کاربر وارد سرویس شما شده است یا خیر. اگر کاربر وارد نشده است، مراحل ورود یا ثبتنام سرویس خود را تکمیل کنید.
یک توکن دسترسی برای گوگل ایجاد کنید تا از آن برای دسترسی به API شما استفاده کند. توکن دسترسی میتواند هر مقدار رشتهای باشد، اما باید به طور منحصر به فرد، کاربر و کلاینتی را که توکن برای آن است، نشان دهد و نباید قابل حدس زدن باشد.
یک پاسخ HTTP ارسال کنید که مرورگر کاربر را به URL مشخص شده توسط پارامتر
redirect_uriهدایت کند. تمام پارامترهای زیر را در قطعه URL قرار دهید:-
access_token: توکن دسترسی که ایجاد کردهاید -
token_type:bearerرشته -
state: مقدار state اصلاح نشده از درخواست اصلی
نمونهای از URL حاصل در زیر آمده است:
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
-
کنترلکنندهی تغییر مسیر OAuth 2.0 گوگل، توکن دسترسی را دریافت کرده و تأیید میکند که مقدار state تغییر نکرده است. پس از اینکه گوگل توکن دسترسی را برای سرویس شما دریافت کرد، این توکن را به فراخوانیهای بعدی به APIهای سرویس شما متصل میکند.
رسیدگی به درخواست های اطلاعات کاربر
نقطه پایانی userinfo یک منبع محافظت شده OAuth 2.0 است که ادعاهای مربوط به کاربر پیوند شده را برمیگرداند. پیاده سازی و میزبانی نقطه پایانی اطلاعات کاربر اختیاری است، به جز موارد استفاده زیر:
- ورود به سیستم حساب پیوندی با Google One Tap.
- اشتراک بدون اصطکاک در AndroidTV.
پس از اینکه رمز دسترسی با موفقیت از نقطه پایانی نشانه شما بازیابی شد، Google درخواستی را به نقطه پایانی اطلاعات کاربری شما ارسال می کند تا اطلاعات نمایه اولیه کاربر پیوند داده شده را بازیابی کند.
| سرصفحه های درخواست نقطه پایانی کاربر | |
|---|---|
Authorization header | نشانه دسترسی از نوع Bearer. |
به عنوان مثال، اگر نقطه پایانی اطلاعات کاربری شما در https://myservice.example.com/userinfo در دسترس باشد، ممکن است یک درخواست به شکل زیر باشد:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
برای اینکه نقطه پایانی اطلاعات کاربری شما به درخواستها رسیدگی کند، مراحل زیر را انجام دهید:
- رمز دسترسی را از سربرگ Authorization استخراج کنید و اطلاعات کاربر مرتبط با نشانه دسترسی را برگردانید.
- اگر رمز دسترسی نامعتبر است، با استفاده از سربرگ پاسخ
WWW-Authenticateخطای غیرمجاز HTTP 401 را برگردانید. در زیر نمونه ای از پاسخ خطای userinfo آورده شده است:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
اگر نشانه دسترسی معتبر است، پاسخ HTTP 200 را با شی JSON زیر در بدنه پاسخ HTTPS برگردانید:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }پاسخ نقطه پایانی اطلاعات کاربر subیک شناسه منحصر به فرد که کاربر را در سیستم شما شناسایی می کند. emailآدرس ایمیل کاربر. given_nameاختیاری: نام کاربر. family_nameاختیاری: نام خانوادگی کاربر. nameاختیاری: نام کامل کاربر. pictureاختیاری: تصویر نمایه کاربر.
اعتبارسنجی پیادهسازی شما
شما میتوانید پیادهسازی خود را با استفاده از ابزار OAuth 2.0 Playground اعتبارسنجی کنید.
در ابزار، مراحل زیر را انجام دهید:
- برای باز کردن پنجره پیکربندی OAuth 2.0، پیکربندی کلیک کنید.
- در فیلد جریان OAuth ، گزینه Client-side را انتخاب کنید.
- در فیلد OAuth Endpoints ، گزینه Custom را انتخاب کنید.
- نقطه پایانی OAuth 2.0 خود و شناسه کلاینتی که به گوگل اختصاص دادهاید را در فیلدهای مربوطه مشخص کنید.
- در بخش مرحله ۱ ، هیچ محدوده گوگلی را انتخاب نکنید. در عوض، این فیلد را خالی بگذارید یا یک محدوده معتبر برای سرور خود تایپ کنید (یا اگر از محدودههای OAuth استفاده نمیکنید، یک رشته دلخواه). وقتی کارتان تمام شد، روی Authorize APIs کلیک کنید.
- در بخشهای مرحله ۲ و مرحله ۳ ، جریان OAuth 2.0 را بررسی کنید و تأیید کنید که هر مرحله طبق برنامه عمل میکند.
شما میتوانید پیادهسازی خود را با استفاده از ابزار Google Account Linking Demo اعتبارسنجی کنید.
در ابزار، مراحل زیر را انجام دهید:
- روی دکمه ورود با گوگل کلیک کنید.
- حسابی را که میخواهید پیوند دهید انتخاب کنید.
- شناسه سرویس را وارد کنید.
- به صورت اختیاری یک یا چند محدودهای را که برای دسترسی به آنها درخواست خواهید کرد، وارد کنید.
- روی شروع نسخه نمایشی کلیک کنید.
- وقتی از شما خواسته شد، تأیید کنید که میتوانید درخواست پیوند را تأیید یا رد کنید.
- تأیید کنید که به پلتفرم خود هدایت میشوید.