لینک‌دهی ساده با 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 را برگردانید.

مدیریت لینک‌های خودکار (دریافت هدف)

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

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

برای مدیریت get intent، اقدامات زیر را انجام دهید:

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

   • client_id ، client_secret و grant_type را تأیید کنید.
   • اعتبارسنجی assertion (JWT)

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

   • با استفاده از sub یا email Claim، وجود کاربر را تأیید کنید.

3. پاسخ دهید :

   • در صورت موفقیت: access_token ، refresh_token و expires_in در یک پاسخ JSON (HTTP 200 OK ) تولید و برگردانید.
   • اگر پیوند ناموفق بود: HTTP 401 Unauthorized را به همراه {"error": "linking_error"} و یک login_hint اختیاری برای بازگشت به پیوند استاندارد OAuth برگردانید.

مدیریت ایجاد حساب کاربری با استفاده از ورود با گوگل (create intent)

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

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

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

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

   • client_id ، client_secret و grant_type را تأیید کنید.
   • اعتبارسنجی assertion (JWT)

2. تأیید کنید که کاربر وجود ندارد :

   • بررسی کنید که آیا sub یا email از قبل در پایگاه داده شما وجود دارد یا خیر.
   • اگر کاربر وجود دارد: HTTP 401 Unauthorized را با {"error": "linking_error", "login_hint": "USER_EMAIL"} برگردانید تا مجبور به استفاده از لینک OAuth شوید.

3. ایجاد حساب کاربری :

   • از ادعاهای sub ، email ، name و picture از JWT برای ایجاد یک رکورد کاربر جدید استفاده کنید.

4. پاسخ دهید :

   • توکن‌ها را در یک پاسخ JSON تولید و برمی‌گرداند (HTTP 200 OK ).

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

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

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

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

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

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

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

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

1. برای باز کردن پنجره پیکربندی OAuth 2.0، settings پیکربندی کلیک کنید.
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. تأیید کنید که به پلتفرم خود هدایت می‌شوید.