OAuth 2.0 برای برنامه‌های تلفن همراه و رایانه

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

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

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

این جریان مجوز مشابه جریانی است که برای برنامه‌های سرور وب استفاده می‌شود. تفاوت اصلی این است که برنامه‌های نصب‌شده باید مرورگر سیستم را باز کنند و یک نشانی وب هدایت محلی برای مدیریت پاسخ‌های سرور مجوز Google ارائه دهند.

کتابخانه‌ها و نمونه‌ها

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

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

پیش‌نیازها

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

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

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

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

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

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

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

ms-app://YOUR_APP_PACKAGE_SID

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

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

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

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

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

سند OAuth 2.0 API Scopes حاوی فهرست کاملی از دامنه‌هایی است که ممکن است برای دسترسی به Google API استفاده کنید.

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

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

مرحله ۱: تولید یک کد درستی‌سنج و چالش

‫Google از پروتکل کلید اثبات برای مبادله کد (PKCE) برای ایمن‌تر کردن جریان برنامه نصب‌شده پشتیبانی می‌کند. برای هر درخواست مجوز، یک کد درستی‌سنج منحصربه‌فرد ایجاد می‌شود و مقدار تبدیل‌شده آن، که «code_challenge» نامیده می‌شود، برای دریافت کد مجوز به سرور مجوز ارسال می‌شود.

ایجاد کد درستی‌سنجی

‫code_verifier یک رشته تصادفی رمزنگاری‌شده با آنتروپی بالا است که از نویسه‌های غیررزروشده [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" استفاده می‌کند و حداقل طول آن ۴۳ نویسه و حداکثر طول آن ۱۲۸ نویسه است.

تأییدکننده کد باید از آنتروپی کافی برخوردار باشد تا حدس زدن مقدار آن غیرعملی شود.

ایجاد چالش کد

دو روش برای ایجاد چالش کد پشتیبانی می‌شود.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

مرحله ۲: ارسال درخواست به سرور OAuth 2.0 در Google

برای دریافت مجوز کاربر، درخواستی به سرور مجوز Google در https://accounts.google.com/o/oauth2/v2/auth ارسال کنید. این نقطه پایانی جستجوی جلسه فعال را مدیریت می‌کند، کاربر را اصالت‌سنجی می‌کند، و رضایت کاربر را دریافت می‌کند. نقطه پایان فقط ازطریق SSL قابل‌دسترسی است و اتصال‌های HTTP (غیر SSL) را رد می‌کند.

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

نشانی‌های وب مجوز نمونه

برگه‌های زیر نمونه نشانی‌های وب مجوز را برای گزینه‌های مختلف URI هدایت نشان می‌دهند.

نشانی‌های وب به‌جز مقدار پارامتر redirect_uri یکسان هستند. نشانی‌های وب همچنین حاوی پارامترهای الزامی response_type و client_id و پارامتر اختیاری state هستند. هر نشانی وب حاوی شکست خط و فاصله برای خوانایی است.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

مرحله ۳: Google از کاربر درخواست رضایت می‌کند

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

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

مرحله ۴: رسیدگی به پاسخ سرور OAuth 2.0

روشی که برنامه شما پاسخ مجوز را دریافت می‌کند به طرح‌واره URI تغییرمسیر که استفاده می‌کند بستگی دارد. صرف‌نظر از طرح، پاسخ حاوی کد مجوز (code) یا خطا (error) خواهد بود. برای مثال، error=access_denied نشان می‌دهد که کاربر درخواست را رد کرده است.

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

مرحله ۵: معاوضه کد مجوز با ژتون‌های بازآوری و دسترسی

برای معاوضه کد مجوز با کد دسترسی، نقطه پایانی https://oauth2.googleapis.com/token را فراخوانی کنید و پارامترهای زیر را تنظیم کنید:

هرچند استفاده از DPoP اختیاری است، اما برای افزایش امنیت توصیه می‌شود. امنیت DPoP به محدود بودن کلید خصوصی به یک دستگاه بستگی دارد؛ توصیه می‌کنیم آن را به‌گونه‌ای ذخیره کنید که نتوان آن را از دستگاه کپی کرد، مثلاً بااستفاده از TPM،‏ Secure Enclave، یا دیگر محل‌های ذخیره کلید با پشتیبانی سخت‌افزاری. برای استفاده از DPoP، برنامه شما باید برای هر درخواست به نقطه پایانی رمز، یک JWT اثبات DPoP جدید و منحصربه‌فرد تولید کند و آن را به‌عنوان سرصفحه درخواست HTTP اضافه کند.

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

ساختن اثبات DPoP

مراحل زیر نحوه ساختن اثبات DPoP بااستفاده از OpenSSL از خط فرمان را نشان می‌دهد:

1. تولید جفت کلید EC P-256:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. ایجاد سرایند DPoP:

   سرایند باید شامل ادعاهای typ، alg، و jwk (کلید عمومی) باشد. مقادیر x و y مختصات کدبندی‌شده Base64Url کلید عمومی EC شما هستند. این JSON را با Base64Url کدبندی کنید:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. ساختن محتوای DPoP:

   بار باید شامل jti (شناسه یکتای درخواست)، htm (روش HTTP، برای نمونه، POST)، htu (نشانی وب HTTP، برای نمونه، https://oauth2.googleapis.com/token)، و iat (زمان صدور) باشد. اگر در پاسخ به درخواست قبلی، یک nonce از سرور در سرصفحه DPoP-Nonce دریافت کردید، باید آن مقدار nonce را در ادعای nonce اضافه کنید. ادعای nonce برای تبادل کد مجوز اختیاری است و فقط زمانی استفاده می‌شود که سرایند DPoP-Nonce قبلاً دریافت شده باشد. این JSON را با Base64Url کدبندی کنید:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   مقدار jti به نوع مبادله بستگی دارد:

   • برای تبادل کد مجوز، jti باید درهم‌سازی SHA256 کد مجوز باشد که با Base64Url کدبندی شده است: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • برای تبادل‌های کد نوسازی، jti باید یک شناسه یکتای هر درخواست باشد: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. امضا کردن مدرک:

   سرصفحه و بار داده کدگذاری‌شده را با نقطه (.) به‌هم متصل کنید، سپس نتیجه را با کلید خصوصی‌تان بااستفاده از ES256 امضا کنید. توجه داشته باشید که JWS نیاز دارد امضا در قالب R | S به‌هم‌پیوسته خام (۶۴ بایت برای P-256) باشد. اگر مستقیماً از OpenSSL استفاده می‌کنید، باید امضای پیش‌فرض با کدبندی ASN.1 DER را به این قالب خام تبدیل کنید.

تبادل موفق با پاسخ 200 OK حاوی نشان‌ها مشخص می‌شود. اگر درطول تبادل از مدرک DPoP معتبری استفاده شود، رمز بازآوری که Google برمی‌گرداند به کلید شما محدود خواهد شد، اما رمزهای دسترسی محدود نخواهند شد. رمزهای دسترسی token_type مربوط به Bearer را به‌جای DPoP حفظ خواهند کرد. علاوه‌براین، Google سرصفحه HTTP DPoP-Nonce را در پاسخ برمی‌گرداند. کارخواه شما باید این nonce را در حافظه نهان ذخیره کند و آن را در ادعای nonce مدرک DPoP در درخواست‌های بعدی (مثلاً هنگام تبادل کردن کد نوسازی برای کد دسترسی جدید، یا هنگام فراخوانی کردن میاناهای برنامه‌سازی کاربردی محافظت‌شده با DPoP) بگنجاند. بااستفاده از این تک‌عنصر صادرشده زودرس، می‌توانید از خطای رفت‌وبرگشت اضافی (use_dpop_nonce) در درخواست بعدی‌تان جلوگیری کنید.

برای درخواست‌های تبادل ژتون که با ژتون‌های بازآوری محدودشده با DPoP انجام می‌شود، باید اثبات‌های DPoP اضافه شود.

اگر سرایند DPoP در زمان موردانتظار وجود نداشته باشد، نامعتبر باشد، یا اگر مدرک از کلیدی متفاوت با کلید محدودشده به کد استفاده کند، تبادل ناموفق رخ می‌دهد. در این موارد، سرور خطای 400 Bad Request برمی‌گرداند. اگر مدرک DPoP ادعاهای htm یا htu ناهماهنگ، iat منقضی، jti مجدداً استفاده‌شده، یا امضای نامعتبر داشته باشد، Google کد خطای invalid_dpop_proof برمی‌گرداند. اگر یک DPoP nonce لازم باشد، مثلاً درطول تبادل ژتون بازآوری، و اثبات DPoP فاقد ادعای nonce باشد، یا مقدار nonce برای سرور غیرقابل‌قبول باشد (مثلاً منقضی شده باشد، قبلاً استفاده شده باشد، یا نادرست باشد)، Google کد خطای use_dpop_nonce را به‌همراه سرصفحه HTTP‏ DPoP-Nonce حاوی یک nonce جدید برمی‌گرداند که می‌توانید در درخواست بعدی استفاده کنید. خطاهای دیگر ممکن است invalid_grant را برگرداند.

‫Google با برگرداندن یک شیء JSON که حاوی یک کد دسترسی کوتاه‌مدت و یک کد نوسازی است به این درخواست پاسخ می‌دهد.

پاسخ حاوی فیلدهای زیر است:

تکه کد زیر سرصفحه‌ها و متن پاسخ موفقیت‌آمیز نمونه‌ای را هنگام استفاده از DPoP نشان می‌دهد:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

مرحله ۶: بررسی کردن گستره‌هایی که کاربران اعطا کرده‌اند

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

بااین‌حال، چند استثنا وجود دارد. برنامه‌های Google Workspace Enterprise با واگذاری اختیار در سطح دامنه، یا برنامه‌هایی که به‌عنوان معتمد علامت‌گذاری شده‌اند، از صفحه موافقت با اجازه‌های دقیق عبور می‌کنند. برای این برنامه‌ها، کاربران صفحه رضایت اجازه دانه‌ای را نخواهند دید. درعوض، برنامه‌تان یا همه گستره‌های درخواست‌شده را دریافت می‌کند یا هیچ‌کدام را دریافت نمی‌کند.

برای اطلاعات دقیق‌تر، نحوه مدیریت اجازه‌های ریزدانه را ببینید.

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

برای مثال، پاسخ نمونه کد دسترسی زیر نشان می‌دهد که کاربر به برنامه شما اجازه دسترسی به فعالیت Drive فقط خواندنی و اجازه‌های رویدادهای «تقویم» را داده است:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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

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

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

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

مثال‌های HTTP GET

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

GET /youtube/v2/reports?ids=channel%3D%3DMINE&startDate=2016-05-01&endDate=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v2/reports?access_token=access_token&ids=channel%3D%3DMINE&startDate=2016-05-01&endDate=2016-06-30&metrics=views

‫curl مثال

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v2/reports?ids=channel%3D%3DMINE&startDate=2016-05-01&endDate=2016-06-30&metrics=views

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

curl https://www.googleapis.com/youtube/v2/reports?access_token=access_token&ids=channel%3D%3DMINE&startDate=2016-05-01&endDate=2016-06-30&metrics=views

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

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

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

هرچند استفاده از DPoP اختیاری است، اما برای افزایش امنیت توصیه می‌شود. برای استفاده از DPoP با ژتون بازآوری، برنامه شما باید برای هر درخواست به نقطه پایانی ژتون، یک JWT اثبات DPoP جدید و منحصربه‌فرد تولید کند. این مدرک باید با همان کلید خصوصی که درطول تبادل کد مجوز اولیه استفاده شده است امضا شود. برنامه شما مدرک را به‌عنوان سرایند درخواست HTTP اضافه می‌کند.

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

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

برای استفاده از DPoP با ژتون بازآوری، باید JWT اثبات DPoP جدید و منحصربه‌فردی برای درخواست تولید کنید. برای دستورالعمل‌های گام‌به‌گام درباره تولید جفت کلید و ساختن JWT، به ساختن اثبات DPoP مراجعه کنید.

تبادل موفق با پاسخ 200 OK حاوی کد دسترسی جدید نشان داده می‌شود. وقتی از DPoP استفاده می‌شود، token_type Bearer است. پاسخ موفق تأیید می‌کند مدرک DPoP برای کد نوسازی پذیرفته شده است. Google همچنین ممکن است سرصفحه HTTP جدید DPoP-Nonce را در پاسخ برگرداند؛ درصورت برگردانده شدن، کارخواه شما باید این nonce را در حافظه نهان ذخیره کند و آن را در ادعای nonce اثبات DPoP در درخواست‌های بعدی لحاظ کند.

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

تکه‌کد زیر نمونه‌ای از سرایندها و متن پاسخ موفقیت‌آمیز را هنگام استفاده از DPoP نشان می‌دهد:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "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 به‌همراه کد خطا برگردانده می‌شود.

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

از برنامه‌هایتان محافظت کنید

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

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

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

مطالعه بیشتر

«روال مطلوب فعلی» IETF با عنوان OAuth 2.0 برای برنامه‌های بومی بسیاری از روال‌های مطلوب مستندشده در اینجا را ایجاد می‌کند.