لینک‌دهی ساده با OAuth و ورود با گوگل

نمای کلی

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

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

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

شکل ۱. اتصال حساب کاربری روی گوشی کاربر با استفاده از قابلیت اتصال ساده

لینک‌دهی ساده: OAuth + ورود با Google Flow

نمودار توالی زیر، تعاملات بین کاربر، گوگل و نقطه پایانی تبادل توکن شما را برای لینک‌سازی ساده‌شده (Streamlined Linking) به تفصیل نشان می‌دهد.

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

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

بازیگر / جزء	نقش GAL	مسئولیت‌ها
برنامه/سرور گوگل	کلاینت OAuth	رضایت کاربر را برای ورود با گوگل دریافت می‌کند، اطلاعات احراز هویت (JWT) را به سرور شما ارسال می‌کند و توکن‌های حاصل را به طور ایمن ذخیره می‌کند.
نقطه پایانی تبادل توکن شما	ارائه دهنده هویت / سرور مجوز	اعتبارسنجی ادعاهای هویت، بررسی حساب‌های کاربری موجود، مدیریت اهداف اتصال حساب کاربری ( check ، get ، create ) و صدور توکن‌ها بر اساس اهداف درخواستی.
API سرویس شما	سرور منابع	دسترسی به داده‌های کاربر را در صورت ارائه یک توکن دسترسی معتبر فراهم می‌کند.

الزامات مربوط به لینک‌سازی ساده

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

• شناسه کلاینت API گوگل خود را ثبت کنید .

منطق تصمیم‌گیری برای لینک‌سازی ساده

منطق زیر نحوه فراخوانی intentها را در جریان ساده‌سازی لینکینگ تعیین می‌کند:

1. آیا کاربر در سیستم احراز هویت شما حساب کاربری دارد؟ (کاربر با انتخاب بله یا خیر تصمیم می‌گیرد)
   1. بله: آیا کاربر از ایمیل مرتبط با حساب گوگل خود برای ورود به پلتفرم شما استفاده می‌کند؟ (کاربر با انتخاب بله یا خیر تصمیم می‌گیرد)
      1. بله: آیا کاربر در سیستم احراز هویت شما حساب کاربری منطبقی دارد؟ ( check intent ، تأیید است)
         1. بله: اگر get intent با موفقیت برگردد، get intent فراخوانی می‌شود و حساب کاربری مرتبط می‌شود.
         2. خیر: ایجاد حساب کاربری جدید؟ (کاربر با انتخاب بله یا خیر تصمیم می‌گیرد)
            1. بله: در صورت موفقیت آمیز بودن create intent ، تابع create intent فراخوانی شده و حساب کاربری لینک می‌شود.
            2. خیر: جریان لینک‌دهی OAuth فعال می‌شود، کاربر به مرورگر خود هدایت می‌شود و به کاربر این امکان داده می‌شود که با یک ایمیل دیگر لینک دهد.
      2. خیر: جریان لینک‌دهی OAuth فعال می‌شود، کاربر به مرورگر خود هدایت می‌شود و به کاربر این امکان داده می‌شود که با یک ایمیل دیگر لینک دهد.
   2. خیر: آیا کاربر در سیستم احراز هویت شما حساب کاربری منطبقی دارد؟ (منظور check intent ، تأیید است)
      1. بله: اگر get intent با موفقیت برگردد، get intent فراخوانی می‌شود و حساب کاربری مرتبط می‌شود.
      2. خیر: در صورت موفقیت آمیز بودن create intent تابع create intent فراخوانی شده و حساب کاربری لینک می‌شود.

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

نقطه پایانی تبادل توکن شما باید اهداف check ، get و create را برای پشتیبانی از Simplelined Linking پیاده‌سازی کند.

برای مدیریت intent های مختلف، این مراحل را دنبال کنید:

بررسی وجود یک حساب کاربری موجود (بررسی قصد)

گوگل نقطه پایانی تبادل توکن شما را فراخوانی می‌کند تا تأیید کند که آیا کاربر گوگل در سیستم شما وجود دارد یا خیر. برای جزئیات پارامتر، به Simplelined Linking Intents مراجعه کنید.

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

برای مدیریت هدف check ، اقدامات زیر را انجام دهید:

1. Validate the request :

   • client_id ، client_secret و grant_type را تأیید کنید (باید urn:ietf:params:oauth:grant-type:jwt-bearer ).
   • با استفاده از معیارهای موجود در JWT Validation، assertion (JWT) را انجام دهید.

2. کاربر جستجو :

   • بررسی کنید که آیا شناسه حساب گوگل ( sub ) یا آدرس ایمیل در JWT با یک کاربر در پایگاه داده شما مطابقت دارد یا خیر.

3. پاسخ دهید :

   • اگر پیدا شد: با {"account_found": "true"} مقدار HTTP 200 OK را برگردانید.
   • اگر پیدا نشد: با {"account_found": "false"} خطای HTTP 404 Not Found را برگردانید.

Handle automatic linking (get intent)

If the account exists, Google calls your endpoint with intent=get to retrieve tokens. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the get intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Lookup user:

   • Verify the user exists using the sub or email claim.

3. Respond:

   • If successful: Generate and return access_token, refresh_token, and expires_in in a JSON response (HTTP 200 OK).
   • If linking fails: Return HTTP 401 Unauthorized with {"error": "linking_error"} and an optional login_hint to fall back to standard OAuth linking.

Handle account creation using Sign in with Google (create intent)

If no account exists, Google calls your endpoint with intent=create to create a new user. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the create intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type.
   • Validate the assertion (JWT).

2. Verify user does not exist:

   • Check if the sub or email is already in your database.
   • If the user does exist: Return HTTP 401 Unauthorized with {"error": "linking_error", "login_hint": "USER_EMAIL"} to force fallback to OAuth linking.

3. Create account:

   • Use the sub, email, name, and picture claims from the JWT to create a new user record.

4. Respond:

   • Generate and return tokens in a JSON response (HTTP 200 OK).

شناسه کلاینت API گوگل خود را دریافت کنید

در طول فرآیند ثبت نام اتصال حساب کاربری، از شما خواسته می‌شود که شناسه کلاینت API گوگل خود را ارائه دهید. برای دریافت شناسه کلاینت API خود، از پروژه‌ای که هنگام تکمیل مراحل اتصال OAuth ایجاد کرده‌اید، استفاده کنید. برای انجام این کار، مراحل زیر را انجام دهید:

1. به صفحه مشتریان بروید.

2. یک پروژه Google APIs ایجاد یا انتخاب کنید.

   اگر پروژه شما برای نوع برنامه وب، شناسه کلاینت ندارد، برای ایجاد آن روی «ایجاد کلاینت» کلیک کنید. حتماً دامنه سایت خود را در کادر «منشأ جاوا اسکریپت مجاز» (Authorized JavaScript origins) وارد کنید. هنگام انجام آزمایش‌ها یا توسعه محلی، باید هم http://localhost و هم http://localhost:<port_number> را به فیلد «منشأ جاوا اسکریپت مجاز» اضافه کنید.

اعتبارسنجی پیاده‌سازی شما

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.