این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

الزامات

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

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

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

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

در طول جریان ورود به سیستم با یک ضربه، نمایش حساب‌های مرتبط را انتخاب می‌کنید.
یک درخواست ورود با یک ضربه به کاربر نشان داده می‌شود که گزینه‌ای برای ورود به سرویس شما با حساب مرتبط خود دارد.
اگر کاربر انتخاب کند که با حساب پیوند شده ادامه دهد، Google درخواستی برای ذخیره کد مجوز به نقطه پایانی رمز شما ارسال می کند. این درخواست شامل رمز دسترسی کاربر صادر شده توسط سرویس شما و یک کد مجوز Google است.
شما کد مجوز Google را با یک رمز Google ID که حاوی اطلاعات حساب Google کاربر است، مبادله می کنید.
برنامه شما همچنین پس از پایان جریان، یک کد شناسه دریافت می‌کند و شما آن را با شناسه کاربری در کد 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 به دست آمده است. این معمولاً اعتباری با نام اقدامات جدید در برنامه Google است
`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 ) شناسه مشتری اختصاص داده شده شما باشد، و اینکه نشانه منقضی نشده باشد ( exp میدان).

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

مواردی که گوگل معتبر است:

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

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