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

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

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

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

جایگزین‌ها

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

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

پیش‌نیازها

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

هر برنامه‌ای که 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. API Library تمام APIهای موجود را که بر اساس خانواده محصول و محبوبیت گروه‌بندی شده‌اند، فهرست می‌کند. اگر API مورد نظر برای فعال‌سازی در لیست قابل مشاهده نیست، از جستجو برای یافتن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
4. API مورد نظر خود را انتخاب کنید و سپس روی دکمه‌ی فعال‌سازی کلیک کنید.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

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

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

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

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

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

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

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

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

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

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

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

در این مرحله، دستگاه شما یک درخواست HTTP POST به سرور احراز هویت گوگل، به آدرس 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=email%20profile

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

curl -d "client_id=client_id&scope=email%20profile" \
     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 را نمایش می‌دهید باید به اندازه کافی عریض باشد تا بتواند یک رشته URL با طول ۴۰ کاراکتر را در خود جای دهد.
  • شما نباید به هیچ وجه verification_url تغییر دهید، مگر اینکه بخواهید طرح نمایش را به صورت اختیاری حذف کنید. اگر قصد دارید طرح (مثلاً https:// ) را به دلایل نمایشی از URL حذف کنید، مطمئن شوید که برنامه شما می‌تواند هر دو نوع http و https را پشتیبانی کند.

مرحله ۴: از سرور احراز هویت گوگل نظرسنجی کنید

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

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

آدرس اینترنتی (URL) نقطه پایانی برای نظرسنجی، 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 و اگر قبلاً وارد سیستم نشده‌اید، وارد گوگل شوید، کاربر صفحه رضایت‌نامه‌ای مانند تصویر زیر را مشاهده می‌کند:

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

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

دسترسی اعطا شد

اگر کاربر (با کلیک روی Allow در صفحه رضایت‌نامه) به دستگاه دسترسی داده باشد، پاسخ شامل یک توکن دسترسی و یک توکن به‌روزرسانی است. این توکن‌ها دستگاه شما را قادر می‌سازند تا از طرف کاربر به 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 ) هستند. این خطاها عبارتند از:

فراخوانی API های گوگل

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

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

مثال‌های HTTP GET

فراخوانی نقطه پایانی drive.files (رابط برنامه‌نویسی کاربردی Drive Files) با استفاده از هدر HTTP مربوط به Authorization: Bearer ممکن است چیزی شبیه به شکل زیر باشد. توجه داشته باشید که باید توکن دسترسی خودتان را مشخص کنید:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

مثال‌های curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

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

برای به‌روزرسانی یک توکن دسترسی، برنامه شما یک درخواست HTTPS POST به سرور احراز هویت گوگل ( 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.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 برای دستگاه‌ها فقط برای محدوده‌های زیر پشتیبانی می‌شود:

دسترسی مبتنی بر زمان

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

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