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

هر یکپارچه‌سازی Cloud-to-cloud باید شامل مکانیزمی برای احراز هویت کاربران باشد.

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

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

اتصال حساب گوگل با OAuth

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

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

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

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

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

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

الزامات

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

توصیه‌ها

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

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

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

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

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

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

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

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

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

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

جریان کد مجوز

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

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

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

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

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

وقتی نیاز دارید که با استفاده از جریان کد مجوز 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&scope=REQUESTED_SCOPES&response_type=code

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

1. تأیید کنید که client_id با Client ID که به گوگل اختصاص داده‌اید مطابقت دارد و redirect_uri با URL تغییر مسیر ارائه شده توسط گوگل برای سرویس شما مطابقت دارد. این بررسی‌ها برای جلوگیری از اعطای دسترسی به برنامه‌های کلاینت ناخواسته یا پیکربندی نادرست مهم هستند. اگر از چندین جریان OAuth 2.0 پشتیبانی می‌کنید، همچنین تأیید کنید که response_type code است.
2. بررسی کنید که آیا کاربر وارد سرویس شما شده است یا خیر. اگر کاربر وارد نشده است، مراحل ورود یا ثبت‌نام سرویس خود را تکمیل کنید.
3. یک کد مجوز برای دسترسی گوگل به API خود ایجاد کنید. کد مجوز می‌تواند هر مقدار رشته‌ای باشد، اما باید به طور منحصر به فرد، کاربر، کلاینتی که توکن برای آن است و زمان انقضای کد را نشان دهد و نباید قابل حدس زدن باشد. شما معمولاً کدهای مجوزی صادر می‌کنید که تقریباً پس از 10 دقیقه منقضی می‌شوند.
4. تأیید کنید که URL مشخص شده توسط پارامتر 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

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

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

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

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

نحوه ارسال اعتبارنامه‌ها توسط گوگل به سرور خود را پیکربندی کنید

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

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

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

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

2. در بخش «ابر به ابر» ، «توسعه» را انتخاب کنید.

3. روی «باز کردن» کلیک کنید و سپس ادغام خود را انجام دهید.

4. به پایین اسکرول کنید تا به بخش مجوزها (اختیاری) برسید و کادر انتخاب «آیا گوگل شناسه کلاینت و رمز را از طریق هدر احراز هویت پایه HTTP ارسال کند؟» را انتخاب کنید.

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

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

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

برای این درخواست‌ها، مقدار grant_type authorization_code است و مقدار code برابر با کد مجوزی است که قبلاً به گوگل اعطا کرده‌اید. در زیر مثالی از درخواست برای تعویض کد مجوز با یک access token و یک refresh token آمده است:

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. تأیید کنید که URL مشخص شده توسط پارامتر 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
   }

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

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

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

برای این درخواست‌ها، مقدار grant_type refresh_token است و مقدار refresh_token برابر با مقدار توکن refresh است که قبلاً به گوگل اعطا کرده‌اید. در زیر مثالی از درخواست برای تعویض توکن refresh با توکن access آمده است:

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 مبدا درخواست را گوگل معرفی می‌کند و 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	اختیاری: تصویر نمایه کاربر.