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

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

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

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

جایگزین ها

اگر در حال نوشتن برنامه ای برای پلتفرمی مانند Android، iOS، macOS، Linux یا Windows (از جمله پلتفرم جهانی ویندوز) هستید که به مرورگر و قابلیت های ورودی کامل دسترسی دارد، از جریان OAuth 2.0 برای برنامه های موبایل و دسکتاپ استفاده کنید. (حتی اگر برنامه شما یک ابزار خط فرمان بدون رابط گرافیکی باشد، باید از آن جریان استفاده کنید.)

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

پیش نیازها

API ها را برای پروژه خود فعال کنید

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن APIها را در آن فعال کند API Console.

برای فعال کردن یک API برای پروژه خود:

1. Open the API Library در Google API Console.
2. If prompted, select a project, or create a new one.
3. از صفحه کتابخانه برای یافتن و فعال کردن Content ID API YouTube استفاده کنید. هر API دیگری را که برنامه شما از آن استفاده می کند پیدا کنید و آن ها را نیز فعال کنید.

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

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

1. Go to the Credentials page.
2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
3. نوع برنامه تلویزیون ها و دستگاه های ورودی محدود را انتخاب کنید.
4. مشتری OAuth 2.0 خود را نامگذاری کنید و روی ایجاد کلیک کنید.

محدوده های دسترسی را شناسایی کنید

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

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

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

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

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

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

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

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

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

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

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

نمونه ها

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

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%2Fyoutubepartner

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

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

مرحله 2: پاسخ سرور مجوز را مدیریت کنید

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

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

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

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

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

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

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

{
  "error_code": "rate_limit_exceeded"
}

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

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

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

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

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

مرحله 4: از سرور مجوز Google نظرسنجی کنید

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

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

نشانی اینترنتی نقطه پایانی نظرسنجی 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

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

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

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

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

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

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

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

در این مورد، پاسخ API شامل فیلدهای زیر است:

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

{
  "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 API

پس از اینکه برنامه شما یک نشانه دسترسی به دست آورد، در صورتی که دامنه دسترسی مورد نیاز توسط API اعطا شده باشد، می توانید از این رمز برای برقراری تماس با Google API از طرف یک حساب کاربری خاص استفاده کنید. برای انجام این کار، توکن دسترسی را با درج یک پارامتر query access_token یا یک مقدار Authorization HTTP header Bearer در درخواست API قرار دهید. در صورت امکان، هدر HTTP ترجیح داده می شود، زیرا رشته های پرس و جو در گزارش های سرور قابل مشاهده هستند. در بیشتر موارد می‌توانید از کتابخانه سرویس گیرنده برای تنظیم تماس‌های خود با Google APIها استفاده کنید (به عنوان مثال، هنگام تماس با YouTube Content ID API ).

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

نمونه های HTTP GET

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

GET /youtubepartner/v1/contentOwners?fetchMine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query access_token وجود دارد:

GET https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=true

نمونه های curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtubepartner/v1/contentOwners?fetchMine=true

یا، گزینه پارامتر query string:

curl https://www.googleapis.com/youtubepartner/v1/contentOwners?access_token=access_token&fetchMine=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&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "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 برای دستگاه‌ها فقط برای حوزه‌های زیر پشتیبانی می‌شود: