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

نمای کلی

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

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

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

پیوند حساب کاربری روی گوشی کاربر با Streamlined Linking

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

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

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

شکل ۲. توالی رویدادها در جریان پیوند ساده.

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

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

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

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

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

توجه: این اهداف باید در همان نقطه پایانی تبادل توکن که برای جریان پیوند اولیه OAuth ایجاد کرده‌اید، پیاده‌سازی شوند. برای مدیریت این اهداف، نقطه پایانی متفاوتی ایجاد نکنید .

• شناسه کلاینت 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> را به فیلد «منشأ جاوا اسکریپت مجاز» اضافه کنید.

   نکته کلیدی: برای آزمایش یا توسعه محلی، هر دو http://localhost و http://localhost:<port_number> را به فیلد Authorized JavaScript origins اضافه کنید.

   نکته: یک شناسه کلاینت مانند مثال زیر است:

   1234567890-abc123def456.apps.googleusercontent.com
   

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

شما می‌توانید پیاده‌سازی خود را با استفاده از ابزار OAuth 2.0 Playground اعتبارسنجی کنید.

در ابزار، مراحل زیر را انجام دهید:

1. برای باز کردن پنجره پیکربندی OAuth 2.0، پیکربندی کلیک کنید.
2. در فیلد جریان OAuth ، گزینه Client-side را انتخاب کنید.
3. در فیلد OAuth Endpoints ، گزینه Custom را انتخاب کنید.
4. نقطه پایانی OAuth 2.0 خود و شناسه کلاینتی که به گوگل اختصاص داده‌اید را در فیلدهای مربوطه مشخص کنید.
5. در بخش مرحله ۱ ، هیچ محدوده گوگلی را انتخاب نکنید. در عوض، این فیلد را خالی بگذارید یا یک محدوده معتبر برای سرور خود تایپ کنید (یا اگر از محدوده‌های OAuth استفاده نمی‌کنید، یک رشته دلخواه). وقتی کارتان تمام شد، روی Authorize APIs کلیک کنید.
6. در بخش‌های مرحله ۲ و مرحله ۳ ، جریان OAuth 2.0 را بررسی کنید و تأیید کنید که هر مرحله طبق برنامه عمل می‌کند.

شما می‌توانید پیاده‌سازی خود را با استفاده از ابزار Google Account Linking Demo اعتبارسنجی کنید.

در ابزار، مراحل زیر را انجام دهید:

1. روی دکمه ورود با گوگل کلیک کنید.
2. حسابی را که می‌خواهید پیوند دهید انتخاب کنید.
3. شناسه سرویس را وارد کنید.
4. به صورت اختیاری یک یا چند محدوده‌ای را که برای دسترسی به آنها درخواست خواهید کرد، وارد کنید.
5. روی شروع نسخه نمایشی کلیک کنید.
6. وقتی از شما خواسته شد، تأیید کنید که می‌توانید درخواست پیوند را تأیید یا رد کنید.
7. تأیید کنید که به پلتفرم خود هدایت می‌شوید.