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

نکته مهم: این جریان OAuth 2.0 از مجموعه محدودی از دامنه‌ها پشتیبانی می‌کند.

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

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

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

جایگزین‌ها

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

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

پیش‌نیازها

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

پارامترها
client_id	الزامی شناسه کارخواه برای برنامه شما. این مقدار را می‌توانید در «کنسول Cloud» صفحه «کارخواه‌ها» پیدا کنید.
scope	الزامی فهرستی از حوزه‌ها که با فاصله از هم جدا شده‌اند و منابعی را که برنامه شما می‌تواند ازطرف کاربر به آن‌ها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه رضایت که Google به کاربر نمایش می‌دهد اطلاع‌رسانی می‌کند. فهرست دامنه‌های مجاز را برای برنامه‌ها یا دستگاه‌های نصب‌شده ببینید. محدوده‌ها به برنامه شما امکان می‌دهند فقط برای دسترسی به منابعی که نیاز دارد درخواست دهد و درعین‌حال به کاربران امکان می‌دهد میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، بین تعداد محدوده‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود دارد.

مثال‌ها

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

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

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

مرحله ۴: نظرسنجی از سرور مجوز 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 دسترسی داشته باشد، می‌تواند از کد بازآوری برای دریافت کد دسترسی جدید استفاده کند. اگر برنامه شما به این نوع دسترسی نیاز دارد، باید ژتون بازآوری را برای استفاده بعدی ذخیره کند.

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

اگر کاربر از اعطای دسترسی به دستگاه خودداری کند، پاسخ سرور دارای 403 کد وضعیت پاسخ HTTP (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 پیدا نشد. برای مثال، این خطا زمانی رخ می‌دهد که مقدار پارامتر client_id نامعتبر باشد. نوع کارخواه OAuth نادرست است. مطمئن شوید که نوع برنامه برای شناسه کارخواه روی تلویزیون‌ها و دستگاه‌های ورودی محدود تنظیم شده باشد.
invalid_grant	400	مقدار پارامتر code نامعتبر است، قبلاً مطالبه شده است، یا نمی‌تواند تجزیه شود.
unsupported_grant_type	400	مقدار پارامتر grant_type نامعتبر است.
org_internal	403	شناسه کارخواه OAuth در درخواست بخشی از پروژه‌ای است که دسترسی به «حساب‌های Google» را در سازمان Google Cloud خاصی محدود می‌کند. پیکربندی نوع کاربر را برای برنامه OAuth خود تأیید کنید.

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

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

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

نمونه‌های HTTP GET

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

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

در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان 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 به سرور مجوز 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/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 را که قبلاً به پروژه‌ای اعطا شده است برمی‌دارد و همه نشان‌های دسترسی یا بازآوری صادرشده برای همه کارخواه‌های ثبت‌شده تحت آن پروژه را نامعتبر می‌کند.

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

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

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

OpenID Connect, ورود به سیستم با Google

• email
• openid
• profile

Drive API

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

YouTube API

• https://www.googleapis.com/auth/youtube
• https://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

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