لینک کردن حساب گوگل با OAuth (Implicit Flow - بایگانی‌شده)

خطر: جریان ضمنی برای جریان‌های MCP، UCP و Agent-driven پشتیبانی نمی‌شود . به طور کلی به دلیل ملاحظات امنیتی، استفاده از آن برای همه ادغام‌های جدید توصیه نمی‌شود. به جای آن از جریان کد مجوز استفاده کنید.

برای پشتیبانی از جریان ضمنی OAuth 2.0، سرویس شما یک نقطه پایانی مجوزدهی را از طریق HTTPS در دسترس قرار می‌دهد. این نقطه پایانی مسئول احراز هویت و اخذ رضایت از کاربران برای دسترسی به داده‌ها است. نقطه پایانی مجوزدهی، یک رابط کاربری ورود به سیستم را به کاربرانی که هنوز وارد سیستم نشده‌اند، ارائه می‌دهد و رضایت آنها را برای دسترسی درخواستی ثبت می‌کند.

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

لینک کردن حساب گوگل: جریان ضمنی OAuth

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

شکل ۱. توالی رویدادها در جریان ضمنی OAuth 2.0 برای پیوند دادن حساب گوگل.

نقش‌ها و مسئولیت‌ها

جدول زیر نقش‌ها و مسئولیت‌های بازیگران در جریان ضمنی OAuth لینکینگ حساب گوگل (GAL) را تعریف می‌کند. توجه داشته باشید که در GAL، گوگل به عنوان کلاینت OAuth عمل می‌کند، در حالی که سرویس شما به عنوان ارائه‌دهنده هویت/سرویس عمل می‌کند.

بازیگر / جزء	نقش GAL	مسئولیت‌ها
برنامه/سرور گوگل	کلاینت OAuth	جریان را آغاز می‌کند، توکن دسترسی را با استفاده از تغییر مسیر مرورگر دریافت می‌کند و آن را به صورت ایمن برای دسترسی به APIهای سرویس شما ذخیره می‌کند.
نقطه پایانی مجوز شما	سرور احراز هویت	کاربران شما را احراز هویت می‌کند، رضایت آنها را دریافت می‌کند و توکن‌های دسترسی بلندمدت را مستقیماً برای گوگل صادر می‌کند.
آدرس اینترنتی ریدایرکت گوگل	نقطه پایانی پاسخ به تماس	تغییر مسیر کاربر را از سرویس احراز هویت شما به همراه مقادیر access_token و state در قطعه URL دریافت می‌کند.

یک جلسه جریان ضمنی OAuth 2.0 معمولی که توسط گوگل آغاز می‌شود، جریان زیر را دارد:

1. گوگل نقطه پایانی مجوز شما را در مرورگر کاربر باز می‌کند. کاربر، اگر قبلاً وارد سیستم نشده باشد، وارد سیستم می‌شود و اگر قبلاً اجازه نداده باشد، به گوگل اجازه می‌دهد تا به داده‌هایش با API شما دسترسی پیدا کند.
2. سرویس شما یک توکن دسترسی ایجاد می‌کند و آن را به گوگل برمی‌گرداند. برای انجام این کار، مرورگر کاربر را به همراه توکن دسترسی متصل به درخواست، به گوگل هدایت کنید.
3. گوگل APIهای سرویس شما را فراخوانی می‌کند و توکن دسترسی را به هر درخواست پیوست می‌کند. سرویس شما تأیید می‌کند که توکن دسترسی، مجوز دسترسی به API را به گوگل می‌دهد و سپس فراخوانی API را تکمیل می‌کند.

دستور العمل اجرا

برای پیاده‌سازی جریان ضمنی، این مراحل را دنبال کنید.

مرحله ۱: رسیدگی به درخواست‌های مجوز

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

برای مدیریت درخواست، اقدامات زیر را انجام دهید:

1. اعتبارسنجی درخواست :

   • تأیید کنید که client_id با Client ID اختصاص داده شده به گوگل مطابقت دارد.
   • تأیید کنید که redirect_uri با آدرس اینترنتی ریدایرکت مورد انتظار گوگل مطابقت دارد: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
   • Verify that response_type is token .

2. احراز هویت کاربر :

   • بررسی کنید که آیا کاربر به سرویس شما وارد شده است یا خیر.
   • اگر کاربر وارد سیستم نشده است، از او بخواهید مراحل ورود یا ثبت‌نام شما را تکمیل کند.

3. تولید توکن دسترسی :

   • یک توکن دسترسی منحصر به فرد و غیرقابل حدس مرتبط با کاربر و کلاینت ایجاد کنید.

4. ریدایرکت مجدد به گوگل :

   • مرورگر را به URL ارائه شده در redirect_uri هدایت کنید.
   • پارامترهای زیر را در قطعه URL (هش) اضافه کنید:
     • access_token : توکن دسترسی که ایجاد کرده‌اید.
     • token_type : باید bearer باشد.
     • state : مقدار وضعیت اصلاح نشده‌ای که از گوگل دریافت شده است.

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:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. 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.

3. 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.