Google is committed to advancing racial equity for Black communities. See how.
این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.
Switch to English

OAuth 2.0 برای برنامه های موبایل و دسک تاپ

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

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

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

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

جایگزین، گزینه ها

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

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

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

ما کتابخانه ها و نمونه های زیر را برای کمک به شما در اجرای جریان OAuth 2.0 توصیف شده در این سند توصیه می کنیم:

پیش نیازها

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

هر برنامه ای که با API های Google تماس بگیرد ، باید این 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 مورد نظر برای فعال کردن را انتخاب کنید ، سپس روی دکمه Enable کلیک کنید.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

اعتبارنامه ایجاد کنید

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

  1. Go to the Credentials page.
  2. روی ایجاد اعتبارنامه> شناسه مشتری OAuth کلیک کنید.
  3. بخشهای زیر انواع سرویس گیرنده و روشهای هدایت مجدد را پشتیبانی می کند که سرور مجوز Google از آنها پشتیبانی می کند. نوع مشتری را که برای برنامه شما توصیه می شود انتخاب کنید ، مشتری OAuth خود را نامگذاری کنید و سایر قسمتها را در فرم مناسب تنظیم کنید.

طرح URI سفارشی (Android ، iOS ، UWP)

یک برنامه URI سفارشی برای برنامه های Android ، برنامه های iOS و برنامه های جهانی Windows Platform (UWP) توصیه می شود.

اندروید
  1. نوع برنامه Android را انتخاب کنید.
  2. نامی برای مشتری OAuth وارد کنید. این نام برای شناسایی مشتری در شماره Credentials page پروژه شما نمایش داده می شود.
  3. نام بسته برنامه Android خود را وارد کنید. این مقدار در ویژگی package عنصر <manifest> در پرونده مانیفست برنامه شما تعریف شده است.
  4. اثر انگشت توزیع برنامه را وارد کنید SHA-1.
    • اگر برنامه شما از امضای برنامه توسط Google Play استفاده می کند ، اثر انگشت SHA-1 را از صفحه امضای برنامه کنسول Play کپی کنید.
    • اگر keystore و کلیدهای امضای خود را مدیریت می کنید ، از ابزار keytool همراه Java استفاده کنید تا اطلاعات گواهینامه را در قالب قابل خواندن توسط انسان چاپ کنید. مقدار SHA1 را در قسمت Certificate fingerprints در خروجی keytool کپی کنید. برای کسب اطلاعات بیشتر به احراز هویت مشتری خود در Google APIs برای اسناد Android مراجعه کنید.
  5. روی ایجاد کلیک کنید.
iOS
  1. نوع برنامه iOS را انتخاب کنید.
  2. نامی برای مشتری OAuth وارد کنید. این نام برای شناسایی مشتری در شماره Credentials page پروژه شما نمایش داده می شود.
  3. شناسه بسته نرم افزار را وارد کنید. شناسه بسته به مقدار کلید CFBundleIdentifier در پرونده منابع لیست ویژگی اطلاعات برنامه شما ( info.plist ) است. این مقدار معمولاً در پنجره عمومی یا صفحه Signing & Capunities ویرایشگر پروژه Xcode نمایش داده می شود. شناسه بسته نیز در بخش اطلاعات عمومی صفحه اطلاعات برنامه برای برنامه در سایت App Store Apple اپل نمایش داده می شود.
  4. (اختیاری)

    اگر برنامه در فروشگاه App اپل منتشر شده است ، شناسه App Store برنامه خود را وارد کنید. Store ID یک رشته عددی است که در هر URL فروشگاه App Apple موجود است.

    1. برنامه Apple App Store را در دستگاه iOS یا iPadOS خود باز کنید.
    2. برنامه خود را جستجو کنید.
    3. دکمه اشتراک گذاری (نماد مربع و فلش به بالا) را انتخاب کنید.
    4. کپی پیوند را انتخاب کنید .
    5. پیوند را در ویرایشگر متن جایگذاری کنید. شناسه App Store قسمت نهایی URL است.

      مثال: https://apps.apple.com/app/google/id 284815942

  5. (اختیاری)

    شناسه تیم خود را وارد کنید. برای اطلاعات بیشتر به یافتن شناسه تیم خود در اسناد حساب توسعه دهنده اپل مراجعه کنید.

  6. روی ایجاد کلیک کنید.
UWP
  1. نوع برنامه Universal Windows Platform را انتخاب کنید.
  2. نامی برای مشتری OAuth وارد کنید. این نام برای شناسایی مشتری در شماره Credentials page پروژه شما نمایش داده می شود.
  3. شناسه فروشگاه 12 مایکروسافت برنامه خود را وارد کنید. این مقدار را می توانید در Microsoft Partner Center در صفحه شناسه برنامه در بخش مدیریت برنامه پیدا کنید.
  4. روی ایجاد کلیک کنید.

برای برنامه های UWP ، طرح URI سفارشی نمی تواند بیش از 39 نویسه باشد.

آدرس IP Loopback (macOS ، Linux ، دسکتاپ ویندوز)

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

وقتی برنامه شما پاسخ مجوز را دریافت می کند ، برای بهترین کاربرد باید با نمایش یک صفحه HTML که به کاربر دستور می دهد مرورگر را ببندد و به برنامه شما برگردد ، پاسخ دهد.

استفاده توصیه شده برنامه های macOS ، Linux و Windows desktop (اما نه Universal Windows Platform)
مقادیر فرم نوع برنامه را روی برنامه دسک تاپ تنظیم کنید.

کپی / چسباندن دستی

استخراج برنامه ای

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

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

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

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

دریافت نشانه های دسترسی OAuth 2.0

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

مرحله 1: ایجاد یک تأیید کننده کد و چالش

Google از پروتکل Proof Key for Code Exchange (PKCE) پشتیبانی می کند تا جریان نصب شده برنامه از امنیت بیشتری برخوردار شود. برای هر درخواست مجوز ، یک تأیید کننده کد منحصر به فرد ایجاد می شود و مقدار تغییر یافته آن ، "code_challenge" نامیده می شود ، برای دریافت کد مجوز به سرور مجوز ارسال می شود.

تأیید کننده کد ایجاد کنید

یک code_verifier یک رشته تصادفی رمزنگاری با آنتروپی بالا است که از نویسه های ذخیره نشده [AZ] / [az] / [0-9] / "-" / "استفاده می کند." / "_" / "" ، با حداقل 43 حرف و حداکثر طول 128 کاراکتر.

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

چالش کد را ایجاد کنید

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

روش های تولید چالش کد
S256 (توصیه می شود) چالش کد هش SHA256 رمزگذار Base64URL (بدون بالشتک) رمزگذار تأیید کننده کد است.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
جلگه چالش کد همان مقداری است که تأیید کننده کد تولید شده در بالا.
code_challenge = code_verifier

مرحله 2: درخواستی را به سرور OAuth 2.0 Google ارسال کنید

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

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

مولفه های
client_id ضروری

شناسه مشتری برنامه شما. این مقدار را می توانید در API Console Credentials page پیدا کنید.

redirect_uri ضروری

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

این مقدار باید دقیقاً مطابق با یکی از URI های تغییر مسیر تغییر مسیر مجاز برای مشتری OAuth 2.0 باشد که شما در API Console Credentials page مشتری خود پیکربندی کرده اید. اگر این مقدار با URI مجاز مطابقت نداشته باشد ، با خطای redirect_uri_mismatch مواجه خواهید شد.

جدول زیر مقدار پارامتر redirect_uri مناسب را برای هر روش نشان می دهد:

مقادیر redirect_uri
طرح URI سفارشی com.example.app : redirect_uri_path

یا

com.googleusercontent.apps.123 : redirect_uri_path
  • com.example.app علامت گذاری معکوس DNS از یک دامنه تحت کنترل شما است. طرح سفارشی باید معتبر باشد.
  • com.googleusercontent.apps.123 علامت DNS معکوس شناسه مشتری است.
  • redirect_uri_path یک جز path مسیر اختیاری است ، مانند /oauth2redirect . توجه داشته باشید که مسیر باید با یک بریدگی منفرد شروع شود ، که با URL های معمولی HTTP متفاوت است.
آدرس IP Loopback http://127.0.0.1: port یا http://[::1]: port

از سیستم عامل خود برای آدرس IP loopback مربوطه س Quال کنید و یک شنونده HTTP را در یک درگاه تصادفی موجود شروع کنید. port با شماره پورت واقعی که برنامه شما گوش می دهد جایگزین کنید.

کپی / چسباندن دستی urn:ietf:wg:oauth:2.0:oob
استخراج برنامه ای urn:ietf:wg:oauth:2.0:oob:auto
response_type ضروری

تعیین می کند که آیا نقطه پایانی Google OAuth 2.0 کد مجوز را برمی گرداند.

مقدار پارامتر را برای برنامه های نصب شده code .

scope ضروری

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

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

code_challenge توصیه شده

یک code_verifier کدگذاری شده را مشخص می code_verifier که به عنوان یک چالش سمت سرور در هنگام تبادل کد مجوز استفاده می شود. این پارامتر باید با پارامتر code_challenge بالا توضیح داده شود. برای اطلاعات بیشتر به بخش ایجاد کد چالش در بالا مراجعه کنید.

code_challenge_method توصیه شده

مشخص می کند که از چه روشی برای رمزگذاری یک code_verifier استفاده شده است که در هنگام تبادل کد مجاز استفاده خواهد شد این پارامتر باید با پارامتر code_challenge استفاده شود. مقدار code_challenge_method صورت عدم وجود در درخواست که شامل code_challenge باشد ، به plain پیش فرض plain شود. تنها مقادیر پشتیبانی شده برای این پارامتر S256 یا plain .

state توصیه شده

مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند ، مشخص می کند. بعد از رضایت کاربر یا رد درخواست دسترسی به برنامه شما ، سرور مقدار دقیقی را که شما به عنوان جفت name=value در شناسه قطعه URL ( # ) از redirect_uri ارسال می کنید ، برمی گرداند.

شما می توانید از این پارامتر برای اهداف مختلفی استفاده کنید ، مانند هدایت کاربر به منبع صحیح در برنامه خود ، ارسال موارد غیر مجاز و کاهش جعل درخواست بین سایت. از آنجا که می توان redirect_uri شما را حدس زد ، استفاده از یک مقدار state می تواند اطمینان شما را از اینکه اتصال ورودی نتیجه درخواست احراز هویت است ، افزایش دهد. اگر یک رشته تصادفی ایجاد کنید یا هش کوکی یا مقدار دیگری را که وضعیت مشتری را ضبط می کند رمزگذاری کنید ، می توانید پاسخ را تأیید کنید تا علاوه بر این اطمینان حاصل کنید که درخواست و پاسخ از همان مرورگر منشأ گرفته است ، در برابر حملاتی مانند cross-site محافظت می کند درخواست جعل برای نمونه ای از نحوه ایجاد و تأیید رمز state اسناد OpenID Connect مراجعه کنید.

login_hint اختیاری

اگر برنامه شما می داند کدام کاربر در تلاش است تا احراز هویت شود ، می تواند از این پارامتر برای ارائه راهنمایی به سرور تأیید اعتبار Google استفاده کند. سرور از راهنمایی برای ساده سازی جریان ورود به سیستم یا با پر کردن قسمت ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چند ورود به سیستم مناسب استفاده می کند.

مقدار پارامتر را روی آدرس ایمیل یا شناسه sub ، که معادل شناسه Google کاربر است.

نمونه URL های مجوز

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

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

طرح URI سفارشی

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

آدرس IP Loopback

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

کپی / چسباندن

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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 client_id=client_id

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

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

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

مرحله 4: پاسخ سرور OAuth 2.0 را مدیریت کنید

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

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

مرحله 5: کد مجوز را برای تازه کردن و دسترسی به نشانه ها مبادله کنید

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

زمینه های
client_id شناسه مشتری از API Console Credentials page به دست آمده است.
client_secret راز مشتری از API Console Credentials page بدست آمده است.
code کد مجوز از درخواست اولیه برگشت.
code_verifier تأیید کننده کد که در مرحله 1 ایجاد کرده اید.
grant_type همانطور که در مشخصات OAuth 2.0 تعریف شده است ، مقدار این فیلد باید روی کد authorization_code تنظیم شود.
redirect_uri یکی از URI های ریدایرکتینگ ذکر شده برای پروژه شما در API Console Credentials page برای client_id داده شده است.

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

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

Google با بازگرداندن یک شی J JSON که شامل یک رمز دسترسی کوتاه مدت و یک نشانه تازه سازی است ، به این درخواست پاسخ می دهد.

پاسخ شامل زمینه های زیر است:

زمینه های
access_token نشانه ای که برنامه شما برای تأیید درخواست Google API ارسال می کند.
expires_in طول عمر باقی مانده از رمز دسترسی در چند ثانیه.
id_token توجه: این ویژگی فقط در صورتی برگردانده می شود که درخواست شما دارای دامنه هویتی باشد مانند openid ، profile یا email . مقدار یک JSON Web Token (JWT) است که شامل اطلاعات هویتی امضا شده دیجیتالی درباره کاربر است.
refresh_token نشانه ای که می توانید برای بدست آوردن رمز دسترسی جدید از آن استفاده کنید. نشانه های تازه سازی معتبر هستند تا زمانی که کاربر دسترسی را لغو کند. توجه داشته باشید که نشانه های تازه سازی همیشه برای برنامه های نصب شده بازگردانده می شوند.
scope محدوده های دسترسی که توسط access_token اعطا می شود به صورت لیستی از رشته های فضای محدود و حساس به حروف بزرگ بیان می شود.
token_type نوع رمز برگشتی در این زمان ، مقدار این قسمت همیشه روی Bearer تنظیم می شود.

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

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

تماس با API های Google

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

می توانید تمام API های Google را امتحان کنید و دامنه های آنها را در OAuth 2.0 Playground مشاهده کنید .

مثالهای HTTP GET

تماس با نقطه پایان drive.files (API فایلهای Drive) با استفاده از Authorization: Bearer سربرگ 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 به سرور مجوز Google ( https://oauth2.googleapis.com/token ) ارسال می کند که شامل پارامترهای زیر است:

زمینه های
client_id شناسه مشتری از API Console اخذ شده است.
client_secret راز مشتری از API Console بدست آمده است. ( client_secret در مورد درخواست مشتریانی که به عنوان برنامه های Android ، iOS یا Chrome ثبت شده اند قابل استفاده نیست.)
grant_type همانطور که در مشخصات OAuth 2.0 تعریف شده است ، مقدار این قسمت باید به صورت refresh_token تنظیم 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&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

تا زمانی که کاربر دسترسی اعطا شده به برنامه را لغو نکرده باشد ، سرور token یک شی JSON را که حاوی رمز دسترسی جدید است ، برمی گرداند. قطعه زیر نمونه ای از پاسخ را نشان می دهد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.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 همراه با کد خطا بازگردانده می شود.

بیشتر خواندن

IETF بهترین روش فعلی OAuth 2.0 برای برنامه های بومی بسیاری از بهترین روش های ثبت شده در اینجا را نشان می دهد.