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

نمای کلی

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. آیا کاربر در سیستم احراز هویت شما حساب کاربری دارد؟ (کاربر با انتخاب بله یا خیر تصمیم می‌گیرد)
   1. بله: آیا کاربر از ایمیل مرتبط با حساب گوگل خود برای ورود به پلتفرم شما استفاده می‌کند؟ (کاربر با انتخاب بله یا خیر تصمیم می‌گیرد)
      1. بله: آیا کاربر در سیستم احراز هویت شما حساب کاربری منطبقی دارد؟ ( منظور check ، تأیید است)
         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 فراخوانی می‌شود و در صورت موفقیت‌آمیز بودن نتیجه، حساب کاربری متصل می‌شود. اگر ایجاد حساب کاربری پشتیبانی نشود، نقطه پایانی شما باید خطای HTTP 401 linking_error را برگرداند تا جریان لینک‌دهی OAuth جایگزین فعال شود.

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

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

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

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"account_found": "false"}.

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

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

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

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

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)

نکته: پشتیبانی از هدف create intent) اختیاری است. اهداف مورد نیاز برای پیوند ساده (Streamlined Linking)، check و get هستند.

اگر سرویس شما از ایجاد حساب کاربری پشتیبانی می‌کند و هیچ حسابی وجود ندارد، گوگل نقطه پایانی شما را با intent=create فراخوانی می‌کند تا یک کاربر جدید ایجاد کند. برای جزئیات پارامتر، به Streamlined 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> را به فیلد «منشأ جاوا اسکریپت مجاز» اضافه کنید.

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

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

   1234567890-abc123def456.apps.googleusercontent.com
   

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

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

In the tool, do the following steps:

1. Click Configuration 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.