این سند توضیح می‌دهد که چگونه مجوز OAuth 2.0 را برای دسترسی به «میانای برنامه‌سازی کاربردی داده YouTube» بااستفاده از برنامه‌هایی که روی دستگاه‌هایی مانند تلویزیون، کنسول بازی، و چاپگر اجرا می‌شوند پیاده‌سازی کنید. به‌طور دقیق‌تر، این جریان برای دستگاه‌هایی طراحی شده است که یا به مرورگر دسترسی ندارند یا قابلیت‌های ورودی محدودی دارند.
OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه‌ای هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و اطلاعات دیگرشان را خصوصی نگه دارند. برای مثال، یک برنامه تلویزیون می‌تواند از OAuth 2.0 برای دریافت اجازه انتخاب فایل ذخیره‌شده در Google Drive استفاده کند.
ازآنجایی‌که برنامه‌هایی که از این جریان استفاده می‌کنند در دستگاه‌های شخصی توزیع می‌شوند، فرض می‌شود که برنامه‌ها نمی‌توانند اسرار را حفظ کنند. این برنامه‌ها می‌توانند درحالی‌که کاربر در برنامه حضور دارد یا زمانی‌که برنامه در پس‌زمینه اجرا می‌شود، به Google APIs دسترسی داشته باشند.
جایگزین‌ها
اگر درحال نوشتن برنامه‌ای برای پلاتفرمی مثل Android، iOS، macOS، Linux، یا Windows (ازجمله Universal Windows Platform) هستید که به مرورگر و قابلیت‌های ورودی کامل دسترسی دارد، از جریان OAuth 2.0 برای برنامه‌های تلفن همراه و رایانه استفاده کنید. (حتی اگر برنامه‌تان ابزار خط فرمان بدون میانای گرافیکی است، باید از این جریان استفاده کنید.)
اگر فقط می‌خواهید کاربران را با «حساب Google» خودشان به سیستم وارد کنید و از JWT شناسه ژتون برای دریافت اطلاعات نمایه کاربر پایه استفاده کنید، ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود را ببینید.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:
- در «کنسول Google API»، کتابخانه API را باز کنید.
- اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
- از صفحه کتابخانه برای پیدا کردن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه‌های مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوز داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبارنامه برای پروژه‌تان را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه کارخواهان بروید.
- روی ایجاد کارخواه کلیک کنید.
- نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود را انتخاب کنید.
- نامی برای کارخواه OAuth 2.0 خود انتخاب کنید و روی ایجاد کلیک کنید.
شناسایی کردن دامنه‌های دسترسی
محدوده‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی پیدا کند و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، ممکن است بین تعداد گستره‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود داشته باشد.
پیش‌از اینکه پیاده‌سازی مجوز OAuth 2.0 را شروع کنید، توصیه می‌کنیم محدوده‌هایی را که برنامه‌تان برای دسترسی به آنها به اجازه نیاز دارد شناسایی کنید.
YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
| دامنه | توضیحات |
|---|---|
https://www. googleapis. com/ auth/ youtube | حساب YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtube. channel-memberships. creator | فهرستی از اعضای فعال فعلی کانال خود، سطح فعلی آنها و زمان عضویت آنها را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. force-ssl | ویدیوها، رتبه‌بندی‌ها، نظرات و زیرنویس‌های YouTube خود را مشاهده، ویرایش و برای همیشه حذف کنید |
https://www. googleapis. com/ auth/ youtube. readonly | حساب YouTube خود را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. upload | ویدیوهای YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner | دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner-channel-audit | اطلاعات خصوصی مربوط به کانال YouTube خود را در طول فرآیند ممیزی با شریک YouTube مشاهده کنید |
فهرست گستره‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید.
دریافت کدهای دسترسی OAuth 2.0
اگرچه برنامه شما در دستگاهی با قابلیت‌های ورودی محدود اجرا می‌شود، کاربران باید برای تکمیل این جریان مجوز، دسترسی جداگانه‌ای به دستگاهی با قابلیت‌های ورودی غنی‌تر داشته باشند. جریان مراحل زیر را دارد:
- برنامه شما درخواستی به سرور صدور مجوز Google ارسال می‌کند که دامنه‌هایی را که برنامه شما برای دسترسی به آنها اجازه درخواست می‌کند، شناسایی می‌کند.
- سرور با چند بخش اطلاعاتی که در مراحل بعدی استفاده می‌شود پاسخ می‌دهد، مثل کد دستگاه و کد کاربر.
- اطلاعاتی را نمایش می‌دهید که کاربر می‌تواند در دستگاهی جداگانه وارد کند تا به برنامه شما اجازه دهد.
- برنامه شما شروع به نظرسنجی از سرور مجوز Google می‌کند تا تعیین کند کاربر برنامه شما را مجاز کرده است یا نه.
- کاربر به دستگاهی با قابلیت‌های ورودی غنی‌تر می‌رود، مرورگر وب راه‌اندازی می‌کند، به نشانی وب نمایش‌داده‌شده در مرحله ۳ می‌رود و کدی را که در مرحله ۳ نیز نمایش داده می‌شود وارد می‌کند. سپس کاربر می‌تواند دسترسی به برنامه شما را اعطا (یا رد) کند.
- پاسخ بعدی به درخواست نظرسنجی شما حاوی نشانه‌هایی است که برنامه شما برای مجاز کردن درخواست‌ها ازطرف کاربر به آنها نیاز دارد. (اگر کاربر دسترسی به برنامه شما را رد کرده باشد، پاسخ حاوی کد نیست.)
تصویر این فرایند را نشان می‌دهد:
بخش‌های زیر این مراحل را به‌طور مفصل توضیح می‌دهند. با توجه به طیف قابلیت‌ها و محیط‌های زمان اجرای
که دستگاه‌ها ممکن است داشته باشند، مثال‌های نشان‌داده‌شده در این سند از ابزار کمکی خط فرمان curl
استفاده می‌کنند. این نمونه‌ها را می‌توان به زبان‌ها و زمان‌های اجرای مختلف منتقل کرد.
مرحله ۱: درخواست کدهای دستگاه و کاربر
در این مرحله، دستگاه شما درخواست HTTP POST را به سرور مجوز Google در
https://oauth2.googleapis.com/device/code ارسال می‌کند که برنامه شما
و همچنین دامنه‌های دسترسی را که برنامه شما می‌خواهد ازطرف کاربر به آنها دسترسی داشته باشد شناسایی می‌کند.
باید این نشانی وب را از
سند «اکتشاف» بااستفاده از
مقدار فراداده device_authorization_endpoint بازیابی کنید. پارامترهای درخواست HTTP زیر را اضافه کنید:
پارامترهای درخواست HTTP زیر را اضافه کنید:
| پارامترها | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
الزامی
شناسه کارخواه برای برنامه شما. می‌توانید این مقدار را در صفحه «کارخواه‌ها» در «کنسول Cloud» پیدا کنید. |
||||||||||||||||
scope |
الزامی
فهرستی از حوزه‌ها که با فاصله از هم جدا شده‌اند و منابعی را که برنامه شما می‌تواند ازطرف کاربر به آنها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه موافقت که Google به کاربر نمایش می‌دهد اطلاع می‌دهد. فهرست محدوده‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید. گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی داشته باشد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، رابطه‌ای معکوس بین تعداد دامنه‌های درخواستی و احتمال کسب رضایت کاربر وجود دارد. YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
سند OAuth 2.0 API Scopes فهرست کاملی از دامنه‌هایی را که ممکن است برای دسترسی به Google APIs استفاده کنید ارائه می‌دهد. |
||||||||||||||||
مثال‌ها
قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:
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 |
مقدار منحصربه‌فردی که Google برای شناسایی دستگاهی که برنامه درخواست‌کننده
صدور مجوز را اجرا می‌کند اختصاص می‌دهد. کاربر آن دستگاه را از دستگاه دیگری با قابلیت‌های ورودی غنی‌تر
مجاز خواهد کرد. برای مثال، کاربر ممکن است از رایانه کیفی یا تلفن همراه برای صدور مجوز برای
برنامه‌ای که در تلویزیون اجرا می‌شود استفاده کند. در این مورد، device_code تلویزیون را شناسایی می‌کند.
این کد به دستگاهی که برنامه را اجرا می‌کند اجازه می‌دهد به‌طور ایمن تعیین کند که آیا کاربر دسترسی را اعطا کرده است یا رد کرده است. |
expires_in |
مدت زمانی که device_code و
user_code معتبر هستند، برحسب ثانیه. اگر در این مدت کاربر جریان صدور مجوز را تکمیل نکند و دستگاه شما نیز برای بازیابی اطلاعات مربوط به تصمیم کاربر نظرسنجی نکند، ممکن است لازم باشد این فرایند را از مرحله ۱ دوباره شروع کنید. |
interval |
مدت زمانی که دستگاه شما باید بین درخواست‌های نظرسنجی منتظر بماند، برحسب ثانیه. برای
مثال، اگر مقدار 5 باشد، دستگاه شما باید هر پنج ثانیه یک درخواست
نظرسنجی به سرور مجوز Google ارسال کند. برای جزئیات بیشتر،
مرحله ۳ را ببینید. |
user_code |
مقداری حساس به حروف بزرگ و کوچک که دامنه‌هایی را که برنامه درخواست دسترسی به آنها را دارد برای Google مشخص می‌کند. میانای کاربر شما به کاربر دستور می‌دهد این مقدار را در دستگاه جداگانه‌ای با قابلیت‌های ورودی غنی‌تر وارد کند. سپس Google از این مقدار برای نمایش مجموعه صحیح محدوده‌ها هنگام درخواست از کاربر برای اعطای دسترسی به برنامه شما استفاده می‌کند. |
verification_url |
نشانی وبی که کاربر باید در دستگاهی جداگانه به آن پیمایش کند تا
user_code را وارد کند و دسترسی به برنامه شما را اعطا یا رد کند. میانای کاربر شما
نیز این مقدار را نمایش خواهد داد. |
تکه‌کد زیر پاسخ نمونه‌ای را نشان می‌دهد:
{ "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_codeuser_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 است. درخواست نظرسنجی
شامل پارامترهای زیر است:
| پارامترها | |
|---|---|
client_id |
شناسه کارخواه برای برنامه شما. این مقدار را می‌توانید در «کنسول Cloud» صفحه «کارخواه‌ها» پیدا کنید. |
client_secret |
رمز کارخواه برای client_id ارائه‌شده. این مقدار را می‌توانید در
«کنسول Cloud»
صفحه «کارخواه‌ها» پیدا کنید. |
device_code |
device_code که توسط سرور صدور مجوز در
مرحله ۲ برگردانده شده است. |
grant_type |
این مقدار را روی urn:ietf:params:oauth:grant-type:device_code تنظیم کنید. |
مثال‌ها
قطعه کد زیر یک درخواست نمونه را نشان می‌دهد:
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
در پاسخ تعیین می‌کند که دستگاه
به کدام APIها می‌تواند دسترسی داشته باشد.)
در این حالت، پاسخ میانای برنامه‌سازی کاربردی حاوی فیلدهای زیر است:
| فیلدها | |
|---|---|
access_token |
کدی که برنامه شما برای مجاز کردن درخواست Google API ارسال می‌کند. |
expires_in |
مدت‌زمان باقی‌مانده کد دسترسی برحسب ثانیه. |
refresh_token |
کدی که می‌توانید از آن برای دریافت کد دسترسی جدید استفاده کنید. ژتون‌های بازآوری تا زمانی معتبر هستند که کاربر دسترسی را لغو کند یا ژتون بازآوری منقضی شود. توجه داشته باشید که ژتون‌های بازآوری همیشه برای دستگاه‌ها برگردانده می‌شوند. |
scope |
دامنه‌های دسترسی اعطاشده توسط access_token به‌صورت فهرستی از
رشته‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند بیان می‌شود. |
token_type |
نوع کد برگردانده‌شده. این مقدار همیشه Bearer است. |
قطعه کد زیر نمونه‌ای از پاسخ را نشان می‌دهد:
{ "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) دارند. این خطاها عبارت‌اند از:
| خطا | رمز وضعیت HTTP | شرح |
|---|---|---|
admin_policy_enforced |
400 |
«حساب Google» به‌دلیل خط‌مشی‌های سرپرست Google Workspace نمی‌تواند یک یا چند دامنه درخواستی را مجاز کند. برای اطلاعات بیشتر درباره اینکه سرپرست چگونه می‌تواند دسترسی به دامنه‌ها را تا زمانی که دسترسی صریحاً به شناسه کارخواه OAuth شما اعطا شود محدود کند، به مقاله راهنمای سرپرست Google Workspace با عنوان کنترل اینکه کدام برنامه‌های داخلی و طرف سوم به داده‌های Google Workspace دسترسی داشته باشند مراجعه کنید. |
invalid_client |
401 |
کارخواه OAuth پیدا نشد. برای مثال، این خطا زمانی رخ می‌دهد که
مقدار پارامتر نوع کارخواه OAuth نادرست است. مطمئن شوید که نوع برنامه برای شناسه کارخواه روی تلویزیون‌ها و دستگاه‌های ورودی محدود تنظیم شده باشد. |
invalid_grant |
400 |
مقدار پارامتر code نامعتبر است، قبلاً ادعا شده است، یا نمی‌تواند
تجزیه شود. |
unsupported_grant_type |
400 |
مقدار پارامتر grant_type نامعتبر است. |
org_internal |
403 |
شناسه کارخواه OAuth در درخواست بخشی از پروژه‌ای است که دسترسی به «حساب‌های Google» را در سازمان Google Cloud خاصی محدود می‌کند. پیکربندی نوع کاربر را برای برنامه OAuth خود تأیید کنید. |
فراخوانی میاناهای برنامه‌سازی کاربردی Google
پس‌از اینکه برنامه شما کد دسترسی را دریافت کرد، می‌توانید از این کد برای تماس با «میانای برنامه‌سازی کاربردی Google» ازطرف حساب کاربری معینی استفاده کنید، به‌شرطی که محدوده(های) دسترسی موردنیاز میانای برنامه‌سازی کاربردی اعطا شده باشد. برای انجام این کار،
کد دسترسی را در درخواست به میانای برنامه‌سازی کاربردی با افزودن پارامتر access_token پُرسمان
یا مقدار Authorization سرصفحه HTTP Bearer اضافه کنید. درصورت امکان،
سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در اکثر موارد می‌توانید از کتابخانه کارخواه برای راه‌اندازی تماس‌هایتان با Google APIs استفاده کنید (برای مثال، هنگام فراخواندن YouTube Data API).
توجه داشته باشید که «میانای برنامه‌سازی کاربردی داده‌های YouTube» از حساب‌های خدماتی فقط برای مالکان محتوای 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
در اینجا فراخوانی به همان API برای کاربر اصیل بااستفاده از پارامتر رشته پُرسمان 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) ارسال می‌کند که
شامل پارامترهای زیر در بدنه درخواست است:
| نام | مقدار |
|---|---|
client_id |
شناسه مشتری به‌دست‌آمده از کنسول API. |
client_secret |
اختیاری
رمز کارخواه دریافت‌شده از کنسول API. |
grant_type |
همان‌طور که
در
مشخصات OAuth 2.0 تعریف شده است،
مقدار این فیلد باید روی refresh_token تنظیم شود. |
refresh_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 برای دستگاه‌ها فقط برای دامنه‌های زیر پشتیبانی می‌شود:
OpenID Connect, ورود به سیستم با Google
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly
دسترسی زمان‌محور
دسترسی زمان‌محور به کاربر اجازه می‌دهد برای مدت محدودی به برنامه شما اجازه دسترسی به داده‌هایش را بدهد تا کنشی را تکمیل کند. دسترسی زمان‌محور در محصولات منتخب Google درطول جریان رضایت دردسترس است و به کاربران این امکان را می‌دهد که دسترسی را برای مدت محدودی اعطا کنند. یک نمونه از این ابزارها Data Portability API است که امکان انتقال یک‌باره داده‌ها را فراهم می‌کند.
وقتی کاربری به برنامه شما دسترسی زمان‌دار اعطا می‌کند، ژتون بازآوری پس‌از مدت مشخص‌شده منقضی می‌شود. توجه داشته باشید که ممکن است نشان‌های بازآوری تحت شرایط خاص زودتر نامعتبر شوند؛ برای جزئیات بیشتر، این موارد را ببینید. فیلد refresh_token_expires_in که در پاسخ
تبادل کد
مجوز برگردانده می‌شود، نشان‌دهنده زمان باقی‌مانده تا انقضای ژتون بازآوری در چنین مواردی است.
پیاده‌سازی «محافظت بین‌حسابی»
اقدام دیگری که باید برای محافظت از حساب‌های کاربرانتان انجام دهید، پیاده‌سازی «محافظت بین‌حسابی» بااستفاده از «سرویس محافظت بین‌حسابی» Google است. این سرویس به شما امکان می‌دهد در اعلان‌های رویداد امنیتی که اطلاعاتی درباره تغییرات عمده در حساب کاربر به برنامه شما ارائه می‌دهد مشترک شوید. سپس می‌توانید از این اطلاعات برای اقدام کردن براساس نحوه تصمیم‌گیری‌تان برای پاسخ دادن به رویدادها استفاده کنید.
برخی‌از نمونه‌های انواع رویدادهایی که «سرویس محافظت بین‌حسابی» Google به برنامه‌تان ارسال می‌کند عبارت‌اند از:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
برای اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربر با «محافظت بین‌حسابی»» مراجعه کنید.