پیوند حساب Google با OAuth

حساب‌ها با استفاده از جریان‌های کد ضمنی و مجوزدهی استاندارد صنعتی OAuth 2.0 به هم مرتبط می‌شوند.

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

در جریان کد مجوز ، به دو نقطه پایانی نیاز دارید:

• نقطه پایانی مجوز ، که رابط کاربری ورود به سیستم را به کاربرانی که هنوز وارد سیستم نشده‌اند، نمایش می‌دهد. نقطه پایانی مجوز همچنین یک کد مجوز کوتاه‌مدت ایجاد می‌کند تا رضایت کاربران برای دسترسی درخواستی را ثبت کند.

• نقطه پایانی تبادل توکن ، که مسئول دو نوع تبادل است:

  1. یک کد مجوز را با یک توکن به‌روزرسانی طولانی‌مدت و یک توکن دسترسی کوتاه‌مدت مبادله می‌کند. این تبادل زمانی اتفاق می‌افتد که کاربر از جریان اتصال حساب عبور می‌کند.
  2. یک توکن به‌روزرسانی بلندمدت را با یک توکن دسترسی کوتاه‌مدت تعویض می‌کند. این تعویض زمانی اتفاق می‌افتد که گوگل به یک توکن دسترسی جدید نیاز دارد، زیرا توکنی که منقضی شده بود.

یک جریان OAuth 2.0 انتخاب کنید

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

دستورالعمل‌های طراحی

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

الزامات

1. شما باید به کاربر اطلاع دهید که حساب کاربری به گوگل متصل خواهد شد، نه به یک محصول خاص گوگل مانند گوگل هوم یا گوگل اسیستنت.

توصیه‌ها

توصیه می‌کنیم موارد زیر را انجام دهید:

1. سیاست حفظ حریم خصوصی گوگل را نمایش دهید. پیوندی به سیاست حفظ حریم خصوصی گوگل را در صفحه رضایت‌نامه قرار دهید.

2. داده‌هایی که باید به اشتراک گذاشته شوند. با زبانی واضح و مختصر به کاربر بگویید که گوگل به چه داده‌هایی از او نیاز دارد و چرا.

3. فراخوان عمل واضح. در صفحه رضایت خود، یک فراخوان عمل واضح مانند «موافقت و پیوند» بیان کنید. دلیل این امر این است که کاربران باید بدانند برای پیوند دادن حساب‌هایشان، چه داده‌هایی را باید با گوگل به اشتراک بگذارند.

4. امکان لغو. در صورتی که کاربران تمایلی به لینک دادن نداشته باشند، راهی برای بازگشت یا لغو آن فراهم کنید.

5. فرآیند ورود به سیستم را شفاف کنید. مطمئن شوید که کاربران روش واضحی برای ورود به حساب گوگل خود دارند، مانند فیلدهای نام کاربری و رمز عبور یا ورود با گوگل .

6. امکان لغو پیوند. مکانیزمی برای لغو پیوند کاربران ارائه دهید، مانند URL به تنظیمات حساب کاربری آنها در پلتفرم شما. از طرف دیگر، می‌توانید پیوندی به حساب گوگل قرار دهید که کاربران بتوانند حساب پیوند شده خود را مدیریت کنند.

7. امکان تغییر حساب کاربری. روشی را برای کاربران پیشنهاد دهید تا حساب(های) خود را تغییر دهند. این امر به ویژه در صورتی مفید است که کاربران تمایل به داشتن چندین حساب داشته باشند.

   • اگر کاربری برای تغییر حساب کاربری باید صفحه رضایت را ببندد، یک خطای قابل بازیابی به گوگل ارسال کنید تا کاربر بتواند با پیوند OAuth و جریان ضمنی به حساب مورد نظر خود وارد شود.

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

Create the project

To create your project to use account linking:

1. Go to the Google API Console.
2. Click Create project.
3. Enter a name or accept the generated suggestion.
4. Confirm or edit any remaining fields.
5. Click Create.

To view your project ID:

1. Go to the Google API Console.
2. Find your project in the table on the landing page. The project ID appears in the ID column.

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

سرور OAuth خود را پیاده‌سازی کنید

ن

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

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

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

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

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

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

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

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

رسیدگی به درخواست‌های مجوز

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

برای مثال، اگر نقطه پایانی مجوز شما در https://myservice.example.com/auth موجود باشد، یک درخواست ممکن است به شکل زیر باشد:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

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

1. مقادیر client_id و redirect_uri را تأیید کنید تا از اعطای دسترسی به برنامه‌های کلاینت ناخواسته یا با پیکربندی نادرست جلوگیری شود:

   • تأیید کنید که client_id با client ID که به گوگل اختصاص داده‌اید، مطابقت دارد.
   • تأیید کنید که URL مشخص شده توسط پارامتر redirect_uri به شکل زیر باشد:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

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

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

4. یک پاسخ HTTP ارسال کنید که مرورگر کاربر را به URL مشخص شده توسط پارامتر redirect_uri هدایت کند. تمام پارامترهای زیر را در قطعه URL قرار دهید:

   • access_token : توکن دسترسی که ایجاد کرده‌اید
   • token_type : bearer رشته
   • state : مقدار state اصلاح نشده از درخواست اصلی

   نمونه‌ای از URL حاصل در زیر آمده است:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

کنترل‌کننده‌ی تغییر مسیر OAuth 2.0 گوگل، توکن دسترسی را دریافت کرده و تأیید می‌کند که مقدار state تغییر نکرده است. پس از اینکه گوگل توکن دسترسی را برای سرویس شما دریافت کرد، این توکن را به فراخوانی‌های بعدی به APIهای سرویس شما متصل می‌کند.

رسیدگی به درخواست های اطلاعات کاربر

نقطه پایانی userinfo یک منبع محافظت شده OAuth 2.0 است که ادعاهای مربوط به کاربر پیوند شده را برمی‌گرداند. پیاده سازی و میزبانی نقطه پایانی اطلاعات کاربر اختیاری است، به جز موارد استفاده زیر:

• ورود به سیستم حساب پیوندی با Google One Tap.
• اشتراک بدون اصطکاک در AndroidTV.

پس از اینکه رمز دسترسی با موفقیت از نقطه پایانی نشانه شما بازیابی شد، Google درخواستی را به نقطه پایانی اطلاعات کاربری شما ارسال می کند تا اطلاعات نمایه اولیه کاربر پیوند داده شده را بازیابی کند.

به عنوان مثال، اگر نقطه پایانی اطلاعات کاربری شما در https://myservice.example.com/userinfo در دسترس باشد، ممکن است یک درخواست به شکل زیر باشد:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

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

1. رمز دسترسی را از سربرگ Authorization استخراج کنید و اطلاعات کاربر مرتبط با نشانه دسترسی را برگردانید.
2. اگر رمز دسترسی نامعتبر است، با استفاده از سربرگ پاسخ WWW-Authenticate خطای غیرمجاز HTTP 401 را برگردانید. در زیر نمونه ای از پاسخ خطای userinfo آورده شده است:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

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

3. اگر نشانه دسترسی معتبر است، پاسخ HTTP 200 را با شی JSON زیر در بدنه پاسخ HTTPS برگردانید:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   اگر نقطه پایانی اطلاعات کاربری شما یک پاسخ موفقیت آمیز HTTP 200 برگرداند، رمز بازیابی شده و ادعاها در برابر حساب Google کاربر ثبت می شود.

   پاسخ نقطه پایانی اطلاعات کاربر
   sub	یک شناسه منحصر به فرد که کاربر را در سیستم شما شناسایی می کند.
   email	آدرس ایمیل کاربر.
   given_name	اختیاری: نام کاربر.
   family_name	اختیاری: نام خانوادگی کاربر.
   name	اختیاری: نام کامل کاربر.
   picture	اختیاری: تصویر نمایه کاربر.

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

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