ورود به حساب کاربری مرتبط

پیوند دادن حساب Google به دارندگان حساب Google این امکان را می‌دهد تا سریع، یکپارچه و ایمن به خدمات شما متصل شوند و داده‌ها را با Google به اشتراک بگذارند.

ورود به سیستم حساب پیوندی، ورود با یک ضربه با Google را برای کاربرانی که از قبل حساب Google خود را به سرویس شما مرتبط کرده‌اند، فعال می‌کند. این تجربه را برای کاربران بهبود می بخشد زیرا می توانند با یک کلیک بدون وارد کردن نام کاربری و رمز عبور خود وارد سیستم شوند. همچنین احتمال ایجاد حساب های تکراری در سرویس شما توسط کاربران را کاهش می دهد.

الزامات

برای پیاده سازی ورود به حساب پیوندی، باید شرایط زیر را رعایت کنید:

  • شما یک پیاده سازی OAuth Linking حساب Google دارید که از جریان کد مجوز OAuth 2.0 پشتیبانی می کند. اجرای OAuth شما باید شامل نقاط پایانی زیر باشد:
    • نقطه پایانی مجوز برای رسیدگی به درخواست های مجوز.
    • نقطه پایانی نشانه برای رسیدگی به درخواست دسترسی و به‌روزرسانی نشانه‌ها.
    • نقطه پایانی userinfo برای بازیابی اطلاعات اولیه حساب در مورد کاربر پیوند داده شده که در طول فرآیند ورود به حساب لینک شده به کاربر نمایش داده می شود.
  • شما یک برنامه اندروید دارید.

چگونه کار می کند

پیش نیاز: کاربر قبلاً حساب Google خود را با حساب خود در سرویس شما پیوند داده است.

  1. در طول جریان ورود به سیستم با یک ضربه، نمایش حساب‌های مرتبط را انتخاب می‌کنید.
  2. به کاربر یک اعلان ورود با یک ضربه با گزینه ای برای ورود به سرویس شما با حساب مرتبط خود نشان داده می شود.
  3. اگر کاربر بخواهد با حساب پیوند داده شده ادامه دهد، Google درخواستی برای ذخیره یک کد مجوز به نقطه پایانی رمز شما ارسال می کند. این درخواست شامل رمز دسترسی کاربر صادر شده توسط سرویس شما و یک کد مجوز Google است.
  4. شما کد مجوز Google را با یک نشانه Google ID که حاوی اطلاعات حساب Google کاربر است، مبادله می کنید.
  5. برنامه شما همچنین پس از پایان جریان، یک کد شناسه دریافت می‌کند و شما آن را با شناسه کاربر در کد ID که توسط سرور شما دریافت شده است، مطابقت می‌دهید تا کاربر را وارد برنامه خود کنید.
ورود به حساب کاربری مرتبط
شکل 1. جریان ورود به حساب مرتبط. اگر کاربر چندین حساب وارد شده در دستگاه خود داشته باشد، کاربر ممکن است یک انتخابگر حساب را ببیند و تنها در صورتی که یک حساب پیوندی را انتخاب کند به نمای ورود به حساب پیوندی منتقل می‌شود.

ورود به حساب پیوندی را در برنامه اندروید خود پیاده کنید

برای پشتیبانی از ورود به حساب پیوندی در برنامه Android خود، دستورالعمل‌های راهنمای اجرای Android را دنبال کنید.

رسیدگی به درخواست‌های کد مجوز از Google

Google یک درخواست POST را به نقطه پایانی رمز شما ارسال می کند تا کد مجوزی را ذخیره کند که با شناسه شناسه کاربر مبادله می کنید. این درخواست حاوی رمز دسترسی کاربر و کد مجوز OAuth2 صادر شده توسط Google است.

قبل از ذخیره کد مجوز، باید تأیید کنید که رمز دسترسی توسط شما به Google اعطا شده است که توسط client_id شناسایی شده است.

درخواست HTTP

نمونه درخواست

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN

نقطه پایانی تبادل توکن شما باید بتواند پارامترهای درخواست زیر را مدیریت کند:

پارامترهای نقطه پایانی رمز
code کد مجوز Google OAuth2 مورد نیاز است
client_id شناسه مشتری مورد نیازی که برای Google صادر کردید
client_secret راز مورد نیاز مشتری که برای Google صادر کردید
access_token رمز دسترسی مورد نیاز که برای Google صادر کردید. شما از این برای دریافت زمینه کاربر استفاده خواهید کرد
grant_type مقدار مورد نیاز باید روی urn:ietf:params:oauth:grant-type:reciprocal تنظیم شود

نقطه پایانی تبادل توکن شما باید با انجام کارهای زیر به درخواست POST پاسخ دهد:

  • بررسی کنید access_token به Google اعطا شده است که توسط client_id شناسایی شده است.
  • اگر درخواست معتبر است و کد احراز هویت با موفقیت با یک نشانه Google ID مبادله شده است، یا با یک پاسخ HTTP 200 (OK) پاسخ دهید، یا اگر درخواست نامعتبر است، با کد خطای HTTP پاسخ دهید.

پاسخ HTTP

موفقیت

کد وضعیت HTTP را 200 OK برگردانید

نمونه پاسخ موفقیت
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}

خطاها

در صورت درخواست نامعتبر HTTP، با یکی از کدهای خطای HTTP زیر پاسخ دهید:

کد وضعیت HTTP بدن شرح
400 {"error": "invalid_request"} درخواست فاقد پارامتر است، بنابراین سرور نمی تواند درخواست را ادامه دهد. همچنین در صورتی که درخواست شامل یک پارامتر پشتیبانی نشده باشد یا یک پارامتر را تکرار کند، ممکن است برگردانده شود
401 {"error": "invalid_request"} احراز هویت مشتری ناموفق بود، مثلاً اگر درخواست حاوی شناسه مشتری یا رمز نامعتبر باشد
401 {"error": "invalid_token"}

چالش احراز هویت "WWW-Authentication: Bearer" را در سرصفحه پاسخ قرار دهید

 رمز دسترسی شریک نامعتبر است.
403 {"error": "insufficient_permission"}

چالش احراز هویت "WWW-Authentication: Bearer" را در سرصفحه پاسخ قرار دهید

 رمز دسترسی شریک شامل محدوده(های) لازم برای اجرای OAuth متقابل نیست
500 {"error": "internal_error"} خطای سرور

پاسخ خطا باید شامل فیلدهای زیر باشد:

فیلدهای پاسخ به خطا
error رشته خطای مورد نیاز
error_description توصیف خطا توسط انسان
error_uri URI که جزئیات بیشتری در مورد خطا ارائه می دهد
نمونه پاسخ خطای 400
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error": "invalid_request",
  "error_description": "Request was missing the 'access_token' parameter."
}

مبادله کد مجوز برای شناسه رمز

شما باید کد مجوزی که دریافت کرده‌اید را با یک رمز Google ID که حاوی اطلاعاتی درباره حساب Google کاربر است، مبادله کنید.

برای مبادله کد مجوز برای یک نشانه Google ID، با https://oauth2.googleapis.com/token endpoint تماس بگیرید و پارامترهای زیر را تنظیم کنید:

فیلدهای درخواست
client_id مورد نیاز شناسه مشتری که از صفحه اعتبارنامه کنسول API به دست آمده است. این معمولاً اعتباری با نام New Actions on Google App است
client_secret مورد نیاز راز مشتری که از صفحه اعتبار کنسول API بدست می آید
code مورد نیاز کد مجوز ارسال شده در درخواست اولیه
grant_type مورد نیاز همانطور که در مشخصات OAuth 2.0 تعریف شده است، مقدار این فیلد باید روی authorization_code تنظیم شود.
نمونه درخواست
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET

Google با برگرداندن یک شی JSON که حاوی یک نشانه دسترسی کوتاه مدت و یک نشانه رفرش است به این درخواست پاسخ می دهد.

پاسخ شامل فیلدهای زیر است:

فیلدهای پاسخ
access_token نشانه دسترسی صادر شده توسط Google که برنامه شما برای تأیید درخواست Google API ارسال می کند
id_token رمز شناسه حاوی اطلاعات حساب Google کاربر است. بخش Validate Response شامل جزئیاتی در مورد نحوه رمزگشایی و اعتبارسنجی پاسخ نشانه ID است
expires_in طول عمر باقیمانده رمز دسترسی در ثانیه
refresh_token رمزی که می توانید برای به دست آوردن یک نشانه دسترسی جدید از آن استفاده کنید. نشانه‌های Refresh تا زمانی که کاربر دسترسی را لغو نکند معتبر هستند
scope مقدار این فیلد همیشه برای مورد استفاده از ورود به سیستم حساب پیوندی روی openid تنظیم می شود
token_type نوع رمز برگشتی. در این زمان، مقدار این فیلد همیشه روی Bearer تنظیم می شود
نمونه پاسخ
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8

{
  "access_token": "Google-access-token",
  "id_token": "Google-ID-token",
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "openid",
  "refresh_token": "Google-refresh-token"
}


POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret

پاسخ ID Token را اعتبارسنجی کنید

تأیید و رمزگشایی ادعای JWT

با استفاده از کتابخانه رمزگشایی JWT برای زبان خود می توانید ادعای JWT را تأیید و رمزگشایی کنید . برای تأیید امضای رمز ، از کلیدهای عمومی Google که در قالب های JWK یا PEM موجود است ، استفاده کنید.

هنگام رمزگشایی ، ادعای JWT مانند مثال زیر است: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

علاوه بر تایید امضای این نشانه رمز است، بررسی کنید که صادر کننده این ادعا است ( iss زمینه) است https://accounts.google.com ، که مخاطب ( aud زمینه) اختصاص ID مشتری شما است، و این که رمز او تمام نشده است ( exp رشته).

با استفاده از زمینه های email ، email_verified و hd می توانید تعیین کنید که آیا گوگل میزبان آدرس معتبر است یا خیر. در مواردی که Google معتبر باشد ، کاربر در حال حاضر به عنوان مالک قانونی حساب شناخته شده است و شما می توانید رمز عبور یا سایر روش های چالش را حذف کنید. در غیر این صورت ، می توان از این روش ها برای تأیید حساب قبل از پیوند استفاده کرد.

موارد معتبر Google:

  • email دارای پسوند @gmail.com ، این یک حساب Gmail است.
  • email_verified درست است و hd تنظیم شده است ، این یک حساب G Suite است.

کاربران می توانند بدون استفاده از Gmail یا G Suite در حساب های Google ثبت نام کنند. وقتی email حاوی پسوند @gmail.com و hd وجود ندارد Google معتبر نیست و رمز عبور یا سایر روشهای چالش برای تأیید کاربر توصیه می شود. email_verfied همچنین می تواند درست باشد زیرا گوگل در ابتدا هنگام ایجاد حساب Google کاربر را تأیید می کند ، اما ممکن است مالکیت حساب ایمیل شخص ثالث از آن زمان تغییر کرده باشد.