‫OAuth 2.0 برای برنامه‌های تلویزیون و دستگاه‌های ورودی محدود

این سند نحوه پیاده‌سازی مجوز OAuth 2.0 برای دسترسی به YouTube Data API را بااستفاده از برنامه‌هایی که در دستگاه‌هایی مانند تلویزیون، کنسول بازی، و چاپگر اجرا می‌شوند توضیح می‌دهد. به‌طور دقیق‌تر، این جریان برای دستگاه‌هایی طراحی شده است که یا به مرورگر دسترسی ندارند یا قابلیت‌های ورودی محدودی دارند.

‫OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه‌ای هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و اطلاعات دیگرشان را خصوصی نگه دارند. برای مثال، یک برنامه تلویزیونی می‌تواند از OAuth 2.0 برای دریافت اجازه برای انتخاب فایلی که در Google Drive ذخیره شده است استفاده کند.

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

جایگزین‌ها

اگر فقط می‌خواهید کاربران را با «حساب Google» خودشان به سیستم وارد کنید و از JWT شناسه ژتون برای دریافت اطلاعات نمایه کاربر پایه استفاده کنید، ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود را ببینید.

پیش‌نیازها

فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه

هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.

برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:

1. کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
2. اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
3. از صفحه کتابخانه برای پیدا کردن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آن‌ها را نیز فعال کنید.

ایجاد اعتبارنامه مجوز

هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوزی داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اطلاعات اعتباری برای پروژه را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.

1. به صفحه کارخواهان بروید.
2. روی ایجاد کارخواه کلیک کنید.
3. نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود را انتخاب کنید.
4. نامی برای کارخواه OAuth 2.0 خود انتخاب کنید و روی ایجاد کلیک کنید.

شناسایی کردن دامنه‌های دسترسی

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

قبل‌از شروع پیاده‌سازی مجوز OAuth 2.0، توصیه می‌کنیم دامنه‌هایی را که برنامه‌تان برای دسترسی به آن‌ها نیاز به اجازه دارد شناسایی کنید.

YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:

فهرست گستره‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید.

دریافت کدهای دسترسی OAuth 2.0

اگرچه برنامه شما در دستگاهی با قابلیت‌های ورودی محدود اجرا می‌شود، کاربران باید دسترسی جداگانه‌ای به دستگاهی با قابلیت‌های ورودی غنی‌تر داشته باشند تا این جریان مجوز را تکمیل کنند. جریان مراحل زیر را دارد:

1. برنامه شما درخواستی به سرور صدور مجوز Google ارسال می‌کند که دامنه‌هایی را که برنامه شما برای دسترسی به آن‌ها اجازه درخواست می‌کند، شناسایی می‌کند.
2. سرور با چند بخش اطلاعاتی که در مراحل بعدی استفاده می‌شود پاسخ می‌دهد، مثل کد دستگاه و کد کاربر.
3. اطلاعاتی را نمایش می‌دهید که کاربر می‌تواند در دستگاهی جداگانه وارد کند تا به برنامه شما اجازه دهد.
4. برنامه شما شروع به نظرسنجی از سرور مجوز Google می‌کند تا مشخص کند آیا کاربر به برنامه شما مجوز داده است یا نه.
5. کاربر به دستگاهی با قابلیت‌های ورودی غنی‌تر می‌رود، مرورگر وب را راه‌اندازی می‌کند، به نشانی وب نمایش‌داده‌شده در مرحله ۳ می‌رود و کدی را که در مرحله ۳ نیز نمایش داده شده است وارد می‌کند. سپس کاربر می‌تواند دسترسی به برنامه شما را اعطا (یا رد) کند.
6. پاسخ بعدی به درخواست نظرسنجی شما حاوی کدهای امنیتی است که برنامه‌تان برای صدور مجوز درخواست‌ها ازطرف کاربر به آن‌ها نیاز دارد. (اگر کاربر دسترسی به برنامه شما را رد کرده باشد، پاسخ حاوی کد نیست.)

تصویر این فرایند را نشان می‌دهد:

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

مرحله ۱: درخواست کدهای دستگاه و کاربر

در این مرحله، دستگاه شما درخواست HTTP POST را به سرور مجوز Google در https://oauth2.googleapis.com/device/code ارسال می‌کند که برنامه شما و همچنین دامنه‌های دسترسی را که برنامه شما می‌خواهد ازطرف کاربر به آن‌ها دسترسی داشته باشد شناسایی می‌کند. باید این نشانی وب را از سند اکتشاف بااستفاده از مقدار فراداده device_authorization_endpoint بازیابی کنید. پارامترهای درخواست اچ‌تی‌تی‌پی زیر را اضافه کنید:

مثال‌ها

قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly

این مثال فرمان curl را برای ارسال همان درخواست نشان می‌دهد:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly" \
     https://oauth2.googleapis.com/device/code

مرحله ۲: رسیدگی به پاسخ سرور مجوزدهی

سرور صدور مجوز یکی از پاسخ‌های زیر را برمی‌گرداند:

پاسخ موفقیت‌آمیز

اگر درخواست معتبر باشد، پاسخ شما یک شیء JSON خواهد بود که حاوی ویژگی‌های زیر است:

قطعه کد زیر نمونه‌ای از پاسخ را نشان می‌دهد:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

پاسخ فراتر رفتن از سهمیه

اگر درخواست‌های کد دستگاه شما از سهمیه مرتبط با شناسه مشتری‌تان فراتر رفته باشد، پاسخ ۴۰۳ دریافت خواهید کرد که حاوی خطای زیر است:

{
  "error_code": "rate_limit_exceeded"
}

در این صورت، از استراتژی عقب‌نشینی برای کاهش نرخ درخواست‌ها استفاده کنید.

مرحله ۳: نمایش کد کاربر

verification_url و user_code به‌دست‌آمده در مرحله ۲ را به کاربر نشان دهید. هر دو مقدار می‌توانند شامل هر نویسه قابل‌چاپی از مجموعه نویسه‌های US-ASCII باشند. محتوایی که به کاربر نمایش می‌دهید باید به کاربر دستور دهد که در دستگاهی جداگانه به verification_url برود و user_code را وارد کند.

واسط کاربر (UI) خود را با درنظر گرفتن قوانین زیر طراحی کنید:

• user_code
  • user_code باید در فیلدی نمایش داده شود که بتواند ۱۵ نویسه با اندازه «W» را در خود جای دهد. به‌عبارت دیگر، اگر بتوانید کد WWWWWWWWWWWWWWW را به‌درستی نمایش دهید، واسط کاربر شما معتبر است و توصیه می‌کنیم هنگام آزمایش نحوه نمایش user_code در واسط کاربرتان، از آن مقدار رشته استفاده کنید.
  • user_code به حروف بزرگ و کوچک حساس است و نباید به هیچ وجه تغییر کند، مثلاً تغییر حروف بزرگ و کوچک یا درج نویسه‌های قالب‌بندی دیگر.
• verification_url
  • فضایی که verification_url را در آن نمایش می‌دهید باید به‌اندازه کافی عریض باشد تا بتواند رشته نشانی وبی با طول ۴۰ نویسه را در خود جای دهد.
  • نباید verification_url را به هیچ وجه تغییر دهید، مگر اینکه به‌طور اختیاری طرح را برای نمایش بردارید. اگر قصد دارید طرح را به‌دلایل نمایشی از نشانی وب حذف کنید (مثلاً https://)، مطمئن شوید که برنامه‌تان می‌تواند هر دو نوع http و https را مدیریت کند.

مرحله ۴: نظرسنجی از سرور مجوز Google

ازآنجایی‌که کاربر از دستگاه جداگانه‌ای برای پیمایش به verification_url و اعطا (یا رد) دسترسی استفاده خواهد کرد، وقتی کاربر به درخواست دسترسی پاسخ می‌دهد، دستگاه درخواست‌کننده به‌طور خودکار مطلع نمی‌شود. به همین دلیل، دستگاه درخواست‌کننده باید سرور مجوز Google را نظرسنجی کند تا مشخص شود کاربر چه زمانی به درخواست پاسخ داده است.

دستگاه درخواست‌کننده باید به ارسال درخواست‌های نظرسنجی ادامه دهد تا زمانی که پاسخی دریافت کند که نشان دهد کاربر به درخواست دسترسی پاسخ داده است یا تا زمانی که device_code و user_code به‌دست‌آمده در مرحله ۲ منقضی شوند. interval برگردانده‌شده در مرحله ۲ مقدار زمان انتظار بین درخواست‌ها را برحسب ثانیه مشخص می‌کند.

نشانی وب نقطه پایان برای نظرسنجی https://oauth2.googleapis.com/token است. درخواست نظرسنجی شامل پارامترهای زیر است:

مثال‌ها

قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

این مثال فرمان curl را برای ارسال همان درخواست نشان می‌دهد:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

مرحله ۵: کاربر به درخواست دسترسی پاسخ می‌دهد

تصویر زیر صفحه‌ای شبیه به آنچه را نشان می‌دهد که کاربران هنگام پیمایش به verification_url که در مرحله ۳ نمایش دادید می‌بینند:

پس‌از وارد کردن user_code و، اگر قبلاً به سیستم وارد نشده باشد، وارد شدن به سیستم Google، کاربر صفحه رضایت را می‌بیند:

مرحله ۶: رسیدگی به پاسخ‌های درخواست‌های نظرسنجی

سرور مجوز Google به هر درخواست نظرسنجی با یکی از پاسخ‌های زیر پاسخ می‌دهد:

دسترسی داده شد

اگر کاربر دسترسی به دستگاه را اعطا کرده باشد (با کلیک کردن روی Allow در صفحه رضایت)، پاسخ حاوی کد دسترسی و ژتون بازآوری است. این توکن‌ها به دستگاهتان امکان می‌دهند ازطرف کاربر به میاناهای برنامه‌سازی کاربردی Google دسترسی داشته باشد. (ویژگی scope در پاسخ تعیین می‌کند که دستگاه به کدام میاناهای برنامه‌سازی کاربردی می‌تواند دسترسی داشته باشد.)

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

قطعه کد زیر نمونه‌ای از پاسخ را نشان می‌دهد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

دسترسی امکان‌پذیر نیست

اگر کاربر از اعطای دسترسی به دستگاه امتناع کند، پاسخ سرور دارای کد وضعیت پاسخ HTTP 403 (Forbidden) است. پاسخ حاوی خطای زیر است:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

درانتظار صدور مجوز

اگر کاربر هنوز جریان مجوز را تکمیل نکرده باشد، سرور کد وضعیت پاسخ HTTP 428 (Precondition Required) را برمی‌گرداند. پاسخ حاوی خطای زیر است:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

نظرسنجی بیش‌ازحد مکرر

اگر دستگاه درخواست‌های نظرسنجی را بیش‌ازحد ارسال کند، سرور کد وضعیت پاسخ HTTP 403 (Forbidden) را برمی‌گرداند. پاسخ حاوی خطای زیر است:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

خطاهای دیگر

اگر درخواست نظرسنجی فاقد هرکدام از پارامترهای الزامی باشد یا مقدار پارامتر نادرستی داشته باشد، سرور مجوزدهی نیز خطا برمی‌گرداند. این درخواست‌ها معمولاً رمز وضعیت پاسخ HTTP 400 (Bad Request) یا 401 (Unauthorized) دارند. این خطاها عبارت‌اند از:

فراخوانی میاناهای برنامه‌سازی کاربردی Google

پس‌از اینکه برنامه‌تان کد دسترسی را دریافت کرد، می‌توانید از این کد برای برقراری تماس با Google API ازطرف حساب کاربری مشخصی استفاده کنید، به‌شرطی که گستره(های) دسترسی موردنیاز API اعطا شده باشد. برای انجام این کار، کد دسترسی را با گنجاندن پارامتر پُرسمان access_token یا مقدار سرصفحه HTTP Authorization در درخواست به میانای برنامه‌سازی کاربردی بگنجانید.Bearer درصورت امکان، سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در اکثر موارد، می‌توانید از کتابخانه کارخواه برای راه‌اندازی فراخوانی‌هایتان به Google APIs استفاده کنید (برای مثال، هنگام فراخوانی YouTube Data API).

توجه داشته باشید که YouTube Data API از حساب‌های سرویس فقط برای مالکان محتوای YouTube که مالک و مدیر چندین کانال YouTube هستند، مانند شرکت‌های ضبط موسیقی و استودیوهای فیلم‌سازی، پشتیبانی می‌کند.

می‌توانید همه میاناهای برنامه‌سازی کاربردی Google را امتحان کنید و دامنه‌های آن‌ها را در OAuth 2.0 Playground مشاهده کنید.

نمونه‌های HTTP GET

فراخوانی نقطه پایانی youtube.channels (YouTube Data API) بااستفاده از سرصفحه Authorization: Bearer HTTP ممکن است به‌صورت زیر باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl مثال

می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا نمونه‌ای آورده شده است که از گزینه سرصفحه HTTP (ترجیحی) استفاده می‌کند:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

یا، به‌عنوان گزینه جایگزین، گزینه پارامتر رشته پُرسمان:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

بازآوری کد دسترسی

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

برای بازآوری کد دسترسی، برنامه‌تان درخواست HTTPS POST به سرور مجوز Google (https://oauth2.googleapis.com/token) ارسال می‌کند که شامل پارامترهای زیر در بدنه درخواست است:

قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "token_type": "Bearer"
}

توجه داشته باشید که تعداد ژتون‌های بازآوری که صادر می‌شود محدود است؛ یک محدودیت برای هر ترکیب مشتری/کاربر، و محدودیت دیگر برای هر کاربر در همه مشتری‌ها. باید کدهای بازآوری را در فضای ذخیره‌سازی بلندمدت ذخیره کنید و تا زمانی که معتبر هستند از آن‌ها استفاده کنید. اگر برنامه شما ژتون‌های بازآوری زیادی درخواست کند، ممکن است با این محدودیت‌ها مواجه شود که در این صورت ژتون‌های بازآوری قدیمی‌تر از کار خواهند افتاد.

ابطال کد

در برخی موارد، ممکن است کاربر بخواهد دسترسی اعطاشده به برنامه‌ای را لغو کند. کاربر می‌تواند با مراجعه به تنظیمات حساب، دسترسی را لغو کند. برای اطلاعات بیشتر، به سند پشتیبانی برداشتن دسترسی سایت یا برنامه در بخش «برنامه‌ها و سایت‌های طرف سوم با امکان دسترسی به حساب شما» مراجعه کنید.

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

برای لغو کردن توکن به‌صورت برنامه‌نویسی‌شده، برنامه شما درخواستی به https://oauth2.googleapis.com/revoke ارسال می‌کند و توکن را به‌عنوان پارامتر اضافه می‌کند:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

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

اگر لغو با موفقیت پردازش شود، رمز وضعیت HTTP پاسخ 200 است. برای شرایط خطا، رمز وضعیت HTTP 400 به‌همراه کد خطا برگردانده می‌شود.

دامنه‌های مجاز

جریان OAuth 2.0 برای دستگاه‌ها فقط برای دامنه‌های زیر پشتیبانی می‌شود:

دسترسی زمان‌محور

دسترسی زمان‌محور به کاربر اجازه می‌دهد برای مدت محدودی به برنامه شما اجازه دسترسی به داده‌هایش را بدهد تا کنشی را تکمیل کند. دسترسی زمان‌محور در محصولات منتخب Google درطول جریان رضایت دردسترس است و به کاربران این امکان را می‌دهد که دسترسی را برای مدت محدودی اعطا کنند. یک نمونه از این ابزارها Data Portability API است که امکان انتقال یک‌باره داده‌ها را فراهم می‌کند.

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