API لینک کردن حساب کاربری شما

این صفحه مرجع، نقاط پایانی API را که سرویس شما باید برای پشتیبانی از اتصال حساب کاربری با گوگل پیاده‌سازی کند، مستند می‌کند. این شامل اتصال حساب کاربری مبتنی بر OAuth ، اتصال حساب کاربری ساده و App Flip می‌شود .

پیش نیازها و استانداردها

برای پیاده‌سازی موفقیت‌آمیز این نقاط پایانی، سرویس شما باید استانداردهای زیر را رعایت کند:

  • OAuth 2.0 : مطابق با RFC 6749 .
  • ابطال توکن : مطابق با RFC 7009 .
  • توکن‌های وب JSON (JWT) : مطابق با RFC 7519 (برای لینک‌دهی ساده مورد نیاز است).
  • HTTPS : تمام نقاط پایانی باید از طریق یک اتصال امن HTTPS سرویس‌دهی شوند.

نقطه پایانی مجوز

نقطه پایانی احراز هویت، مسئول احراز هویت کاربران و کسب رضایت آنها برای پیوند دادن حساب‌هایشان با گوگل است.

  • URL: در Actions Console یا Google Cloud Console پیکربندی شده است.
  • روش: GET

پارامترهای درخواست

پارامترها توضیحات
client_id شناسه کلاینتی که به گوگل اختصاص داده‌اید.
redirect_uri آدرس اینترنتی (URL) که پاسخ این درخواست را به آن ارسال می‌کنید.
state یک مقدار حسابداری که در URL تغییر مسیر بدون تغییر به گوگل بازگردانده شده است.
response_type باید code برای جریان کد مجوز باشد.
scope (اختیاری) فهرستی از محدوده‌ها که با فاصله از هم جدا شده‌اند برای داده‌هایی که گوگل درخواست می‌کند.
user_locale (اختیاری) تنظیم زبان حساب گوگل، که با استفاده از برچسب زبان BCP-47 مشخص شده است (مثلاً en-US ).

نقطه پایانی تبادل توکن

این نقطه پایانی مسئول تبادل کدهای مجوز برای توکن‌ها و به‌روزرسانی توکن‌های دسترسی منقضی شده است.

  • URL: در Actions Console یا Google Cloud Console پیکربندی شده است.
  • روش: POST
  • نوع محتوا: application/x-www-form-urlencoded

کد مجوز صرافی برای توکن‌ها

پارامترهای زیر در درخواست اولیه تبادل توکن استفاده می‌شوند.

پارامترهای درخواست

پارامترها توضیحات
client_id شناسه کلاینتی که به گوگل اختصاص داده‌اید.
client_secret راز کلاینتی که به گوگل اختصاص داده‌اید.
grant_type باید authorization_code باشد.
code کد مجوز دریافتی از نقطه پایانی مجوز.
redirect_uri همان URI تغییر مسیر استفاده شده در درخواست اولیه.

توکن رفرش را با توکن دسترسی (Access Token) مبادله کنید

پارامترهای زیر هنگام به‌روزرسانی یک توکن دسترسی استفاده می‌شوند.

پارامترهای درخواست

پارامترها توضیحات
client_id شناسه کلاینتی که به گوگل اختصاص داده‌اید.
client_secret راز کلاینتی که به گوگل اختصاص داده‌اید.
grant_type باید refresh_token باشد.
refresh_token توکن به‌روزرسانی که قبلاً برای گوگل صادر شده است.

پاسخ (JSON)

یک پاسخ موفق با یک شیء JSON در بدنه پاسخ HTTPS برگردانید.

  • وضعیت HTTP: 200 OK
  • نوع محتوا: application/json;charset=UTF-8
فیلدها توضیحات
token_type الزامی. باید bearer باشد.
access_token الزامی. یک توکن کوتاه‌مدت که برای دسترسی به APIهای سرویس شما استفاده می‌شود.
refresh_token مورد نیاز برای authorization_code grant_type . یک توکن با طول عمر بالا که برای دریافت توکن‌های دسترسی جدید استفاده می‌شود.
expires_in الزامی. طول عمر باقیمانده‌ی توکن دسترسی بر حسب ثانیه.

پاسخ‌های خطا

اگر درخواستی به نقطه پایانی توکن با شکست مواجه شود، یک خطای HTTP 400 Bad Request به همراه یک پاسخ JSON حاوی فیلدهای زیر برگردانید:

  • وضعیت HTTP: 400 Bad Request
  • نوع محتوا: application/json;charset=UTF-8
فیلدهای خطا (JSON) توضیحات
error الزامی. باید invalid_grant باشد.
error_description (اختیاری) متن قابل خواندن توسط انسان که اطلاعات اضافی ارائه می‌دهد.

مدیریت ساده‌سازی اهداف لینک‌دهی

اگر سرویس شما از اتصال حساب کاربری ساده (OAuth با ورود با گوگل) پشتیبانی می‌کند، نقطه پایانی تبادل توکن شما باید علاوه بر این، از ادعاهای JSON Web Token (JWT) نیز پشتیبانی کند و اهداف check ، create و get را پیاده‌سازی کند.

پارامترهای زیر در این درخواست‌ها استفاده می‌شوند:

پارامترهای درخواست

پارامترها توضیحات
intent هدف پیوند ساده و مشخصی که درخواست می‌شود: check ، get یا create .
grant_type برای این درخواست‌ها، این پارامتر همیشه مقدار urn:ietf:params:oauth:grant-type:jwt-bearer را دارد.
assertion یک توکن وب JSON (JWT) که یک تأیید امضا شده از هویت کاربر گوگل ارائه می‌دهد. JWT حاوی اطلاعاتی است که شامل شناسه حساب گوگل، نام و آدرس ایمیل کاربر می‌شود.

سرور شما باید این JWT را با استفاده از معیارهای ذکر شده در بخش اعتبارسنجی JWT اعتبارسنجی کند.
client_id شناسه کلاینتی که به گوگل اختصاص داده‌اید.
client_secret راز کلاینتی که به گوگل اختصاص داده‌اید.
scope اختیاری: هر محدوده‌ای که گوگل را برای درخواست از کاربران پیکربندی کرده‌اید. معمولاً در طول intentهای get و create ارائه می‌شود.
response_type مورد نیاز برای create قصد: باید روی token تنظیم شود.

اعتبارسنجی JWT

برای اطمینان از امنیت لینک‌دهی ساده، سرور شما باید با استفاده از معیارهای زیر، اعتبارسنجی assertion (JWT) را انجام دهد:

  • امضا : امضا را با کلیدهای عمومی گوگل (موجود در نقطه پایانی JWK گوگل ) تأیید کنید.
  • صادرکننده ( iss ) : باید https://accounts.google.com باشد.
  • مخاطب ( aud ) : باید با شناسه کلاینت API گوگل که به ادغام شما اختصاص داده شده است، مطابقت داشته باشد.
  • انقضا ( exp ) : باید در آینده باشد.

پاسخ برای check قصد

یک درخواست با intent=check بررسی می‌کند که آیا حساب گوگل (که توسط sub یا email claim در عبارت رمزگشایی شده JWT شناسایی شده است) در پایگاه داده کاربر شما وجود دارد یا خیر.

  • وضعیت HTTP: 200 OK (حساب کاربری پیدا شد) یا 404 Not Found (حساب کاربری پیدا نشد)
  • نوع محتوا: application/json;charset=UTF-8
فیلدها توضیحات
account_found الزامی. اگر حساب کاربری وجود داشته باشد، true و در غیر این صورت، false .

پاسخ برای get نیت

یک درخواست با intent=get توکن دسترسی را برای یک حساب گوگل موجود درخواست می‌کند.

  • وضعیت HTTP: 200 OK
  • نوع محتوا: application/json;charset=UTF-8

شیء JSON پاسخ موفق دقیقاً از همان ساختار یک پاسخ استاندارد Token Exchange موفق استفاده می‌کند (که access_token ، refresh_token و غیره را برمی‌گرداند).

اگر حساب کاربری قابل پیوند نباشد، خطای HTTP 401 بازگردانده می‌شود.

  • وضعیت HTTP: 401 Unauthorized
  • نوع محتوا: application/json;charset=UTF-8
فیلدهای خطا (JSON) توضیحات
error الزامی. باید linking_error باشد.
login_hint (اختیاری) آدرس ایمیل کاربر برای ارسال به جریان لینک‌دهی OAuth جایگزین.

پاسخ برای create قصد

یک درخواست با intent=create درخواست ایجاد یک حساب کاربری جدید با اطلاعات ارائه شده در JWT را دارد.

  • وضعیت HTTP: 200 OK
  • نوع محتوا: application/json;charset=UTF-8

شیء JSON پاسخ موفق دقیقاً از همان ساختار یک پاسخ استاندارد Token Exchange موفق استفاده می‌کند (که access_token ، refresh_token و غیره را برمی‌گرداند).

اگر کاربر از قبل وجود داشته باشد، یک خطای HTTP 401 برگردانده می‌شود تا کاربر را وادار به پیوند دادن حساب کاربری موجود خود کند.

  • وضعیت HTTP: 401 Unauthorized
  • نوع محتوا: application/json;charset=UTF-8
فیلدهای خطا (JSON) توضیحات
error الزامی. باید linking_error باشد.
login_hint آدرس ایمیل کاربر برای ارسال به جریان لینک‌دهی OAuth جایگزین.

نقطه پایانی UserInfo (اختیاری)

برای بازیابی اطلاعات اولیه پروفایل در مورد کاربر لینک شده، همانطور که در مشخصات OpenID Connect Core 1.0 مشخص شده است، استفاده می‌شود. این مورد برای ویژگی‌هایی مانند «لینک ساده» یا «ورود با یک ضربه» مورد نیاز است.

  • روش: GET
  • احراز هویت: Authorization: Bearer ACCESS_TOKEN

پاسخ (JSON)

یک پاسخ موفق با یک شیء JSON در بدنه پاسخ HTTPS برگردانید.

  • وضعیت HTTP: 200 OK
  • نوع محتوا: application/json;charset=UTF-8

فیلدهای پاسخ

فیلدها توضیحات
sub الزامی. یک شناسه منحصر به فرد که کاربر را در سیستم شما مشخص می‌کند.
email الزامی. آدرس ایمیل کاربر.
email_verified الزامی. یک مقدار بولی که نشان می‌دهد آیا آدرس ایمیل تأیید شده است یا خیر.
given_name (اختیاری) نام کوچک کاربر.
family_name (اختیاری) نام خانوادگی کاربر.
name (اختیاری) نام کامل کاربر.
picture (اختیاری) یک آدرس اینترنتی (URL) برای تصویر پروفایل کاربر.

پاسخ‌های خطا

اگر توکن دسترسی نامعتبر یا منقضی شده باشد، خطای HTTP 401 Unauthorized را برگردانید. همچنین باید هدر پاسخ WWW-Authenticate را نیز وارد کنید.

هرگونه پاسخ ناموفق (4xx یا 5xx) که در طول فرآیند پیوند بازگردانده شود، غیرقابل بازیابی تلقی می‌شود. در این موارد، گوگل هرگونه توکن بازیابی شده را حذف می‌کند و کاربر باید فرآیند پیوند حساب را دوباره آغاز کند.

نقطه پایانی ابطال توکن (اختیاری)

به گوگل اجازه می‌دهد تا وقتی کاربری حساب کاربری خود را از سطح گوگل جدا می‌کند، به سرویس شما اطلاع دهد. این نقطه پایانی باید الزامات شرح داده شده در RFC 7009 را برآورده کند.

  • روش: POST
  • نوع محتوا: application/x-www-form-urlencoded

پارامترهای درخواست

پارامترها توضیحات
client_id رشته‌ای که مبدا درخواست را گوگل معرفی می‌کند. این رشته باید در سیستم شما به عنوان شناسه منحصر به فرد گوگل ثبت شود.
client_secret یک رشته مخفی که شما برای سرویس خود در گوگل ثبت کرده‌اید.
token توکنی که قرار است باطل شود.
token_type_hint (اختیاری) راهنمایی در مورد نوع توکنی که لغو می‌شود، که می‌تواند access_token یا refresh_token باشد. اگر مشخص نشود، پیش‌فرض access_token است.

پاسخ‌ها

وقتی توکن با موفقیت حذف شود، یا اگر توکن از قبل نامعتبر باشد، یک پاسخ موفقیت‌آمیز برگردانید.

  • وضعیت HTTP: 200 OK
  • نوع محتوا: application/json;charset=UTF-8

پاسخ‌های خطا

اگر به هر دلیلی (مثلاً عدم دسترسی به پایگاه داده) امکان حذف توکن وجود نداشته باشد، خطای HTTP 503 را برگردانید. گوگل درخواست را بعداً یا طبق دستور سربرگ Retry-After دوباره امتحان خواهد کرد.

  • وضعیت HTTP: 503 Service Unavailable
  • نوع محتوا: application/json;charset=UTF-8
  • سرآیندها: Retry-After: <HTTP-date / delay-seconds>