پیاده‌سازی سرور OAuth 2.0

هر ادغام Cloud-to-cloud باید سازوکاری برای اصالت‌سنجی کاربران داشته باشد.

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

این صفحه نحوه راه‌اندازی سرور OAuth 2.0 را شرح می‌دهد تا با ادغام Cloud-to-cloud شما کار کند.

پیونددهی «حساب Google» با OAuth

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

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

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

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

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

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

الزامات

1. شما باید به کاربر اطلاع دهید که حساب کاربری به گوگل متصل خواهد شد، نه به یک محصول خاص گوگل مانند گوگل هوم یا گوگل اسیستنت.
2. شما باید یک عبارت مجوز گوگل مانند «با ورود به سیستم، شما به گوگل اجازه می‌دهید دستگاه‌های شما را کنترل کند» داشته باشید. به بخش مجوز کنترل دستگاه گوگل در سیاست‌های توسعه‌دهندگان گوگل هوم مراجعه کنید.
3. شما باید صفحه پیونددهی Web OAuth را باز کنید و مطمئن شوید که کاربران روش واضحی برای ورود به حساب گوگل خود، مانند فیلدهای نام کاربری و رمز عبور، دارند. از روش ورود به سیستم گوگل (GSI) که به کاربران امکان می‌دهد بدون هدایت به صفحه پیونددهی Web OAuth، پیوند برقرار کنند، استفاده نکنید. این کار نقض خط‌مشی گوگل است.
4. شما باید حداقل یکی از موارد زیر را در صفحه لینک‌دهی OAuth قرار دهید تا نشان دهید که کاربر به چه نوع ادغامی لینک می‌دهد:
   • لوگوی شرکت
   • نام شرکت
   • نام ادغام
   • آیکون برنامه

توصیه‌ها

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

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

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

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

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

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

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

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

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

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

جریان کد مجوز

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

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

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

1. Google نقطه پایان مجوز شما را در مرورگر کاربر باز می‌کند. اگر جریان در دستگاهی فقط صوتی برای «کنش» شروع شده باشد، Google اجرا را به تلفن منتقل می‌کند.
2. کاربر به سیستم وارد می‌شود (اگر قبلاً وارد نشده باشد) و به Google اجازه می‌دهد با میانای برنامه‌سازی کاربردی شما به داده‌هایش دسترسی داشته باشد (اگر قبلاً این اجازه را نداده باشد).
3. سرویس شما کد مجوزی ایجاد می‌کند و آن را به Google برمی‌گرداند. برای انجام این کار، مرورگر کاربر را با کد مجوز پیوست‌شده به درخواست، به Google هدایت کنید.
4. Google کد مجوز را به نقطه پایانی تبادل کد شما ارسال می‌کند، که اصالت کد را تأیید می‌کند و یک کد دسترسی و یک ژتون بازآوری برمی‌گرداند. کد دسترسی کدی کوتاه‌مدت است که سرویس شما آن را به‌عنوان اعتبارنامه برای دسترسی به میاناهای برنامه‌سازی کاربردی می‌پذیرد. ژتون بازآوری ژتونی طولانی‌مدت است که Google می‌تواند آن را ذخیره کند و از آن برای دریافت کدهای دسترسی جدید هنگام منقضی شدن آن‌ها استفاده کند.
5. پس‌از اینکه کاربر جریان پیوند دادن حساب را تکمیل کرد، هر درخواست بعدی ارسال‌شده از Google حاوی یک کد دسترسی است.

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

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

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

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code

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

1. تأیید کنید که client_id با «شناسه کارخواه» که به Google اختصاص داده‌اید مطابقت داشته باشد و redirect_uri با نشانی وب بازهدایت ارائه‌شده توسط Google برای سرویس شما مطابقت داشته باشد. این بررسی‌ها برای جلوگیری از اعطای دسترسی به برنامه‌های کارخواه ناخواسته یا با پیکربندی نادرست مهم است. اگر از چند جریان OAuth 2.0 پشتیبانی می‌کنید، همچنین تأیید کنید که response_type، code است.
2. بررسی کنید که آیا کاربر به سیستم سرویس شما وارد شده است یا نه. اگر کاربر به سیستم وارد نشده است، جریان ورود به سیستم یا ثبت‌نام سرویس خود را تکمیل کنید.
3. کد مجوزی تولید کنید تا Google از آن برای دسترسی به میانای برنامه‌سازی کاربردی شما استفاده کند. کد مجوز می‌تواند هر مقدار رشته‌ای باشد، اما باید به‌طور منحصربه‌فردی نشان‌دهنده کاربر، کارخواهی که کد برای آن است، و زمان انقضای کد باشد، و نباید قابل‌حدس زدن باشد. معمولاً کدهای مجوزی صادر می‌کنید که پس‌از تقریباً ۱۰ دقیقه منقضی می‌شوند.
4. تأیید کنید که نشانی وب مشخص‌شده با پارامتر redirect_uri دارای فرم زیر باشد:

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

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

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

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

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

• کدهای مجوز را با کدهای دسترسی و ژتون‌های بازآوری معاوضه کنید
• تبدیل ژتون‌های بازآوری به کدهای دسترسی

درخواست‌های تبادل داده‌واحد (توکن) شامل پارامترهای زیر است:

پیکربندی نحوه ارسال اطلاعات کاربری به سرور شما توسط Google

بسته به پیاده‌سازی آن، سرور مجوز شما انتظار دارد اعتبارنامه کارخواه را در بدنه درخواست یا در سرایند درخواست دریافت کند.

به‌طور پیش‌فرض، Google اطلاعات کاربری را در بدنه درخواست ارسال می‌کند. اگر سرور مجوزدهی شما نیاز دارد که اعتبارنامه کارخواه در سرایند درخواست باشد، باید ادغام Cloud-to-cloud را مطابق با آن پیکربندی کنید:

رفتن به «کنسول توسعه‌دهندگان»

1. از فهرست پروژه‌ها، روی باز کردن در کنار پروژه‌ای که می‌خواهید با آن کار کنید کلیک کنید.

2. در بخش Cloud-to-Cloud، توسعه را انتخاب کنید.

3. روی باز کردن در کنار ادغام خود کلیک کنید.

4. به بخش اجازه‌ها (اختیاری) پیمایش کنید و چارگوش انتخاب Google شناسه مشتری و رمز را ازطریق سرصفحه اصالت‌سنجی پایه HTTP ارسال کند را انتخاب کنید.

5. روی ذخیره کلیک کنید تا تغییرات را ذخیره کنید.

کدهای مجوز را با کدهای دسترسی و ژتون‌های بازآوری معاوضه کنید

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

برای این درخواست‌ها، مقدار grant_type برابر با authorization_code است و مقدار code برابر با مقدار کد مجوزی است که قبلاً به Google اعطا کرده‌اید. در زیر نمونه‌ای از درخواست برای تبادل کد مجوز با کد دسترسی و ژتون بازآوری آورده شده است:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

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

1. تأیید کنید که client_id مبدأ درخواست را به‌عنوان مبدأ مجاز شناسایی می‌کند و client_secret با مقدار موردانتظار مطابقت دارد.
2. درستی‌سنجی کنید که کد مجوز معتبر است و منقضی نشده است، و شناسه کارخواه مشخص‌شده در درخواست با شناسه کارخواه منسوب به کد مجوز مطابقت دارد.
3. تأیید کنید که نشانی وب مشخص‌شده توسط پارامتر redirect_uri با مقدار استفاده‌شده در درخواست مجوز اولیه یکسان است.
4. اگر نمی‌توانید همه معیارهای بالا را درستی‌سنجی کنید، خطای HTTP 400 Bad Request را با {"error": "invalid_grant"} به‌عنوان بدنه برگردانید.
5. درغیراین‌صورت، از شناسه کاربر کد مجوز برای تولید ژتون بازآوری و کد دسترسی استفاده کنید. این توکن‌ها می‌توانند هر مقدار رشته‌ای باشند، اما باید به‌طور منحصربه‌فرد نشان‌دهنده کاربر و مشتری‌ای باشند که توکن برای آن‌ها است، و نباید قابل‌حدس زدن باشند. برای کدهای دسترسی، زمان انقضای کد را نیز ثبت کنید که معمولاً یک ساعت پس‌از صدور کد است. ژتون‌های بازآوری منقضی نمی‌شوند.
6. شیء JSON زیر را در بدنه پاسخ HTTPS برگردانید:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Google کد دسترسی و کد بازآوری را برای کاربر ذخیره می‌کند و انقضای کد دسترسی را ثبت می‌کند. وقتی کد دسترسی منقضی می‌شود، Google از ژتون بازآوری استفاده می‌کند تا کد دسترسی جدیدی از نقطه پایانی تبادل ژتون شما دریافت کند.

تبدیل ژتون‌های بازآوری به کدهای دسترسی

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

برای این درخواست‌ها، مقدار grant_type برابر با refresh_token است و مقدار refresh_token برابر با مقدار ژتون بازآوری است که قبلاً به Google اعطا کرده‌اید. در زیر نمونه‌ای از درخواست برای مبادله ژتون بازآوری با کد دسترسی آورده شده است:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

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

1. درستی‌سنجی کنید که client_id مبدأ درخواست را Google شناسایی کند، و client_secret با مقدار موردانتظار مطابقت داشته باشد.
2. بررسی کنید که ژتون بازآوری معتبر باشد و شناسه کارخواهی که در درخواست مشخص شده است با شناسه کارخواه منسوب به ژتون بازآوری مطابقت داشته باشد.
3. اگر نمی‌توانید همه معیارهای بالا را درستی‌سنجی کنید، خطای HTTP 400 Bad Request را با {"error": "invalid_grant"} به‌عنوان بدنه برگردانید.
4. درغیراین‌صورت، از شناسه کاربر از ژتون بازآوری برای تولید کد دسترسی استفاده کنید. این نشان‌ها می‌توانند هر مقدار رشته‌ای باشند، اما باید به‌طور منحصربه‌فردی نشان‌دهنده کاربر و کارخواهی باشند که نشان برای آن‌ها است، و نباید قابل‌حدس زدن باشند. برای کد دسترسی، زمان انقضای کد را نیز ثبت کنید، معمولاً یک ساعت پس‌از صدور کد.
5. شیء JSON زیر را در بدنه پاسخ HTTPS برگردانید:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

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

نقطه پایانی 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	اختیاری: تصویر نمایه کاربر.