OAuth 2.0 برای برنامه‌های iOS و رایانه

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

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

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

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

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

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

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

پیش‌نیازها

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

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

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

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

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

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

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

ms-app://YOUR_APP_PACKAGE_SID

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

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

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

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

دریافت کدهای دسترسی 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=email%20profile&
 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=email%20profile&
 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-encoded را به این قالب خام تبدیل کنید.

تبادل موفق با پاسخ 200 OK حاوی نشان‌ها مشخص می‌شود. اگر درطول تبادل از اثبات DPoP معتبری استفاده شود، کد بازآوری که Google برمی‌گرداند به کلید شما محدود به DPoP خواهد بود، اما کدهای دسترسی محدود به DPoP نخواهند بود. کدهای دسترسی به‌جای DPoP، token_type مربوط به Bearer را حفظ خواهند کرد. علاوه‌براین، 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/drive.metadata.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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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

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

هرچند استفاده از 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 با کد بازآوری، باید یک مدرک DPoP جدید و منحصربه‌فرد JWT برای درخواست تولید کنید. برای دریافت دستورالعمل‌های گام‌به‌گام درباره تولید جفت کلید و ساختن JWT، به ساختن مدرک DPoP مراجعه کنید.

تبادل موفق با پاسخ 200 OK حاوی یک کد دسترسی جدید نشان داده می‌شود. وقتی از DPoP استفاده می‌شود، token_type Bearer است. پاسخ موفق تأیید می‌کند مدرک DPoP برای کد نوسازی پذیرفته شده است. ‫Google ممکن است سرصفحه HTTP جدیدی DPoP-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 برای برنامه‌های بومی بسیاری از روال‌های مطلوب مستندشده در اینجا را ایجاد می‌کند.