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

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

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

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

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

جایگزین ها

برای برنامه‌های تلفن همراه، ممکن است ترجیح دهید از Google Sign-in برای Android یا iOS استفاده کنید. کتابخانه‌های سرویس گیرنده Google Sign-in، احراز هویت و مجوز کاربر را کنترل می‌کنند، و ممکن است اجرای آنها ساده‌تر از پروتکل سطح پایین‌تر توضیح داده شده در اینجا باشد.

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

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

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

• AppAuth برای کتابخانه اندروید
• AppAuth برای کتابخانه iOS
• OAuth برای برنامه ها: نمونه های ویندوز

پیش نیازها

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

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن 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 برای دسترسی به APIهای Google استفاده می‌کند، باید دارای اعتبارنامه مجوز باشد که برنامه را در سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه ها برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.

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

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

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

قبل از شروع اجرای مجوز 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 کاراکتر.

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

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

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

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

code_challenge = code_verifier

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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=http://127.0.0.1:9004&
grant_type=authorization_code

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

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

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

{
  "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"
}

مرحله 6: بررسی کنید که کاربران چه محدوده هایی را اعطا کرده اند

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

با این حال، استثناهایی وجود دارد. برنامه‌های 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 API

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

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

نمونه های HTTP GET

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

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

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query 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

یا، گزینه پارامتر query string:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

در حال بازخوانی نشانه دسترسی

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

برای تازه کردن یک نشانه دسترسی، برنامه شما یک درخواست HTTPS POST به سرور مجوز Google ( https://oauth2.googleapis.com/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

تا زمانی که کاربر دسترسی اعطا شده به برنامه را لغو نکرده باشد، سرور توکن یک شی 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 به همراه یک کد خطا برگردانده می شود.

روش های تغییر مسیر برنامه

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

دسترسی مبتنی بر زمان

دسترسی مبتنی بر زمان به کاربر اجازه می دهد تا برنامه خود را برای مدت زمان محدود به داده های خود دسترسی دهد تا یک عمل را انجام دهد. دسترسی مبتنی بر زمان در محصولات Google Select در طول جریان رضایت در دسترس است و به کاربران این امکان را می دهد که برای مدت زمان محدود دسترسی را اعطا کنند. به عنوان مثال ، API قابلیت حمل داده است که انتقال یک بار داده را امکان پذیر می کند.

هنگامی که یک کاربر دسترسی مبتنی بر زمان برنامه شما را اعطا می کند ، Token Refresh پس از مدت زمان مشخص منقضی می شود. توجه داشته باشید که نشانه های تازه سازی ممکن است قبلاً در شرایط خاص باطل شوند. برای جزئیات بیشتر به این موارد مراجعه کنید. قسمت refresh_token_expires_in در پاسخ مبادله کد مجوز بازگشت ، زمان باقی مانده را تا زمانی که توکن تازه در چنین مواردی منقضی می شود ، نشان می دهد.

ادامه مطلب

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

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

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

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

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

جایگزین ها

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

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

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

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

• Appauth برای کتابخانه اندرویدی
• Appauth برای کتابخانه iOS
• OAUTH برای برنامه ها: نمونه های ویندوز

پیش نیازها

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

هر برنامه ای که Google API را فراخوانی کند ، باید آن 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 برای دسترسی به API های Google استفاده می کند ، باید دارای اعتبار مجوز باشد که برنامه را به سرور OAUTH 2.0 Google شناسایی می کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.

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

حوزه های دسترسی را شناسایی کنید

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

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

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

به دست آوردن نشانه های دسترسی OAUTH 2.0

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

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

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

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

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

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

Code Challenge را ایجاد کنید

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

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

code_challenge = code_verifier

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

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

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

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

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

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

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

مرحله 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 تماس بگیرید و پارامترهای زیر را تنظیم کنید:

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

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=http://127.0.0.1:9004&
grant_type=authorization_code

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

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

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

{
  "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"
}

مرحله ششم: بررسی کنید که کاربران Scopes اعطا کرده اند

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

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

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

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

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

  {
    "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 API

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

می توانید تمام API های Google را امتحان کرده و دامنه آنها را در زمین بازی OAUTH 2.0 مشاهده کنید.

http نمونه هایی دریافت کنید

A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:

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

Here is a call to the same API for the authenticated user using the access_token query string parameter:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl examples

You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Or, alternatively, the query string parameter option:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Refreshing an access token

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters:

The following snippet shows a sample request:

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

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

{
  "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"
}

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Revoking a token

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

App redirect methods

Protect your apps

Time-based access

Time-based access allows a user to grant your app access to their data for a limited duration to complete an action. Time-based access is available in select Google products during the consent flow, giving users the option to grant access for a limited period of time. An example is the Data Portability API which enables a one-time transfer of data.

When a user grants your application time-based access, the refresh token will expire after the specified duration. Note that refresh tokens may be invalidated earlier under specific circumstances; see these cases for details. The refresh_token_expires_in field returned in the authorization code exchange response represents the time remaining until the refresh token expires in such cases.

ادامه مطلب

The IETF Best Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.

This document explains how applications installed on devices like phones, tablets, and computers use Google's OAuth 2.0 endpoints to authorize access to Google APIs.

OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. For example, an application can use OAuth 2.0 to obtain permission from users to store files in their Google Drives.

Installed apps are distributed to individual devices, and it is assumed that these apps cannot keep secrets. They can access Google APIs while the user is present at the app or when the app is running in the background.

This authorization flow is similar to the one used for web server applications . The main difference is that installed apps must open the system browser and supply a local redirect URI to handle responses from Google's authorization server.

جایگزین ها

For mobile apps, you may prefer to use Google Sign-in for Android or iOS . The Google Sign-in client libraries handle authentication and user authorization, and they may be simpler to implement than the lower-level protocol described here.

For apps running on devices that do not support a system browser or that have limited input capabilities, such as TVs, game consoles, cameras, or printers, see OAuth 2.0 for TVs & Devices or Sign-In on TVs and Limited Input Devices .

Libraries and samples

We recommend the following libraries and samples to help you implement the OAuth 2.0 flow described in this document:

• AppAuth for Android library
• AppAuth for iOS library
• OAuth for Apps: Windows Samples

پیش نیازها

Enable APIs for your project

Any application that calls Google APIs needs to enable those APIs in the 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 lists all available APIs, grouped by product family and popularity. If the API you want to enable isn't visible in the list, use search to find it, or click View All in the product family it belongs to.
4. Select the API you want to enable, then click the Enable button.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Create authorization credentials

Any application that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth 2.0 server. The following steps explain how to create credentials for your project. Your applications can then use the credentials to access APIs that you have enabled for that project.

1. Go to the Credentials page.
2. Click Create client .
3. The following sections describe the client types that Google's authorization server supports. Choose the client type that is recommended for your application, name your OAuth client, and set the other fields in the form as appropriate.

Identify access scopes

Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. Thus, there may be an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent.

Before you start implementing OAuth 2.0 authorization, we recommend that you identify the scopes that your app will need permission to access.

The OAuth 2.0 API Scopes document contains a full list of scopes that you might use to access Google APIs.

Obtaining OAuth 2.0 access tokens

The following steps show how your application interacts with Google's OAuth 2.0 server to obtain a user's consent to perform an API request on the user's behalf. Your application must have that consent before it can execute a Google API request that requires user authorization.

Step 1: Generate a code verifier and challenge

Google supports the Proof Key for Code Exchange (PKCE) protocol to make the installed app flow more secure. A unique code verifier is created for every authorization request, and its transformed value, called "code_challenge", is sent to the authorization server to obtain the authorization code.

Create the code verifier

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

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

code_challenge = code_verifier

Step 2: Send a request to Google's OAuth 2.0 server

To obtain user authorization, send a request to Google's authorization server at https://accounts.google.com/o/oauth2/v2/auth . This endpoint handles active session lookup, authenticates the user, and obtains user consent. The endpoint is only accessible over SSL, and it refuses HTTP (non-SSL) connections.

The authorization server supports the following query string parameters for installed applications:

Sample authorization URLs

The tabs below show sample authorization URLs for the different redirect URI options.

The URLs are identical except for the value of the redirect_uri parameter. The URLs also contain the required response_type and client_id parameters as well as the optional state parameter. Each URL contains line breaks and spaces for readability.

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

Step 3: Google prompts user for consent

In this step, the user decides whether to grant your application the requested access. At this stage, Google displays a consent window that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials and a summary of the scopes of access to be granted. The user can then consent to grant access to one or more scopes requested by your application or refuse the request.

Your application doesn't need to do anything at this stage as it waits for the response from Google's OAuth 2.0 server indicating whether any access was granted. That response is explained in the following step.

Step 4: Handle the OAuth 2.0 server response

The manner in which your application receives the authorization response depends on the redirect URI scheme that it uses. Regardless of the scheme, the response will either contain an authorization code ( code ) or an error ( error ). For example, error=access_denied indicates that the user declined the request.

If the user grants access to your application, you can exchange the authorization code for an access token and a refresh token as described in the next step.

Step 5: Exchange authorization code for refresh and access tokens

To exchange an authorization code for an access token, call the https://oauth2.googleapis.com/token endpoint and set the following parameters:

The following snippet shows a sample request:

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=http://127.0.0.1:9004&
grant_type=authorization_code

Google responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

The following snippet shows a sample response:

{
  "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"
}

Step 6: Check which scopes users granted

When requesting multiple permissions (scopes), users may not grant your app access to all of them. Your app must verify which scopes were actually granted and gracefully handle situations where some permissions are denied, typically by disabling the features that rely on those denied scopes.

با این حال، استثناهایی وجود دارد. Google Workspace Enterprise apps with domain-wide delegation of authority , or apps marked as Trusted , bypass the granular permissions consent screen. For these apps, users won't see the granular permission consent screen. Instead, your app will either receive all requested scopes or none.

For more detailed information, see How to handle granular permissions .

To check whether the user has granted your application access to a particular scope, exam the scope field in the access token response. The scopes of access granted by the access_token expressed as a list of space-delimited, case-sensitive strings.

For example, the following sample access token response indicates that the user has granted your application access to the read-only Drive activity and Calendar events permissions:

  {
    "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"
  }

Calling Google APIs

After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user account if the scope(s) of access required by the API have been granted. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the Drive Files API ).

You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground .

HTTP GET examples

A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:

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

Here is a call to the same API for the authenticated user using the access_token query string parameter:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl examples

You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Or, alternatively, the query string parameter option:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Refreshing an access token

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters:

The following snippet shows a sample request:

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

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

{
  "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"
}

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Revoking a token

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

App redirect methods

Protect your apps

Time-based access

Time-based access allows a user to grant your app access to their data for a limited duration to complete an action. Time-based access is available in select Google products during the consent flow, giving users the option to grant access for a limited period of time. An example is the Data Portability API which enables a one-time transfer of data.

When a user grants your application time-based access, the refresh token will expire after the specified duration. Note that refresh tokens may be invalidated earlier under specific circumstances; see these cases for details. The refresh_token_expires_in field returned in the authorization code exchange response represents the time remaining until the refresh token expires in such cases.

ادامه مطلب

The IETF Best Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.

This document explains how applications installed on devices like phones, tablets, and computers use Google's OAuth 2.0 endpoints to authorize access to Google APIs.

OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. For example, an application can use OAuth 2.0 to obtain permission from users to store files in their Google Drives.

Installed apps are distributed to individual devices, and it is assumed that these apps cannot keep secrets. They can access Google APIs while the user is present at the app or when the app is running in the background.

This authorization flow is similar to the one used for web server applications . The main difference is that installed apps must open the system browser and supply a local redirect URI to handle responses from Google's authorization server.

جایگزین ها

For mobile apps, you may prefer to use Google Sign-in for Android or iOS . The Google Sign-in client libraries handle authentication and user authorization, and they may be simpler to implement than the lower-level protocol described here.

For apps running on devices that do not support a system browser or that have limited input capabilities, such as TVs, game consoles, cameras, or printers, see OAuth 2.0 for TVs & Devices or Sign-In on TVs and Limited Input Devices .

Libraries and samples

We recommend the following libraries and samples to help you implement the OAuth 2.0 flow described in this document:

• AppAuth for Android library
• AppAuth for iOS library
• OAuth for Apps: Windows Samples

پیش نیازها

Enable APIs for your project

Any application that calls Google APIs needs to enable those APIs in the 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 lists all available APIs, grouped by product family and popularity. If the API you want to enable isn't visible in the list, use search to find it, or click View All in the product family it belongs to.
4. Select the API you want to enable, then click the Enable button.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Create authorization credentials

Any application that uses OAuth 2.0 to access Google APIs must have authorization credentials that identify the application to Google's OAuth 2.0 server. The following steps explain how to create credentials for your project. Your applications can then use the credentials to access APIs that you have enabled for that project.

1. Go to the Credentials page.
2. Click Create client .
3. The following sections describe the client types that Google's authorization server supports. Choose the client type that is recommended for your application, name your OAuth client, and set the other fields in the form as appropriate.

Identify access scopes

Scopes enable your application to only request access to the resources that it needs while also enabling users to control the amount of access that they grant to your application. Thus, there may be an inverse relationship between the number of scopes requested and the likelihood of obtaining user consent.

Before you start implementing OAuth 2.0 authorization, we recommend that you identify the scopes that your app will need permission to access.

The OAuth 2.0 API Scopes document contains a full list of scopes that you might use to access Google APIs.

Obtaining OAuth 2.0 access tokens

The following steps show how your application interacts with Google's OAuth 2.0 server to obtain a user's consent to perform an API request on the user's behalf. Your application must have that consent before it can execute a Google API request that requires user authorization.

Step 1: Generate a code verifier and challenge

Google supports the Proof Key for Code Exchange (PKCE) protocol to make the installed app flow more secure. A unique code verifier is created for every authorization request, and its transformed value, called "code_challenge", is sent to the authorization server to obtain the authorization code.

Create the code verifier

A code_verifier is a high-entropy cryptographic random string using the unreserved characters [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", with a minimum length of 43 characters and a maximum length of 128 characters.

The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

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

code_challenge = code_verifier

Step 2: Send a request to Google's OAuth 2.0 server

To obtain user authorization, send a request to Google's authorization server at https://accounts.google.com/o/oauth2/v2/auth . This endpoint handles active session lookup, authenticates the user, and obtains user consent. The endpoint is only accessible over SSL, and it refuses HTTP (non-SSL) connections.

The authorization server supports the following query string parameters for installed applications:

Sample authorization URLs

The tabs below show sample authorization URLs for the different redirect URI options.

The URLs are identical except for the value of the redirect_uri parameter. The URLs also contain the required response_type and client_id parameters as well as the optional state parameter. Each URL contains line breaks and spaces for readability.

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

Step 3: Google prompts user for consent

In this step, the user decides whether to grant your application the requested access. At this stage, Google displays a consent window that shows the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials and a summary of the scopes of access to be granted. The user can then consent to grant access to one or more scopes requested by your application or refuse the request.

Your application doesn't need to do anything at this stage as it waits for the response from Google's OAuth 2.0 server indicating whether any access was granted. That response is explained in the following step.

Step 4: Handle the OAuth 2.0 server response

The manner in which your application receives the authorization response depends on the redirect URI scheme that it uses. Regardless of the scheme, the response will either contain an authorization code ( code ) or an error ( error ). For example, error=access_denied indicates that the user declined the request.

If the user grants access to your application, you can exchange the authorization code for an access token and a refresh token as described in the next step.

Step 5: Exchange authorization code for refresh and access tokens

To exchange an authorization code for an access token, call the https://oauth2.googleapis.com/token endpoint and set the following parameters:

The following snippet shows a sample request:

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=http://127.0.0.1:9004&
grant_type=authorization_code

Google responds to this request by returning a JSON object that contains a short-lived access token and a refresh token.

The response contains the following fields:

The following snippet shows a sample response:

{
  "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"
}

Step 6: Check which scopes users granted

When requesting multiple permissions (scopes), users may not grant your app access to all of them. Your app must verify which scopes were actually granted and gracefully handle situations where some permissions are denied, typically by disabling the features that rely on those denied scopes.

با این حال، استثناهایی وجود دارد. Google Workspace Enterprise apps with domain-wide delegation of authority , or apps marked as Trusted , bypass the granular permissions consent screen. For these apps, users won't see the granular permission consent screen. Instead, your app will either receive all requested scopes or none.

For more detailed information, see How to handle granular permissions .

To check whether the user has granted your application access to a particular scope, exam the scope field in the access token response. The scopes of access granted by the access_token expressed as a list of space-delimited, case-sensitive strings.

For example, the following sample access token response indicates that the user has granted your application access to the read-only Drive activity and Calendar events permissions:

  {
    "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"
  }

Calling Google APIs

After your application obtains an access token, you can use the token to make calls to a Google API on behalf of a given user account if the scope(s) of access required by the API have been granted. To do this, include the access token in a request to the API by including either an access_token query parameter or an Authorization HTTP header Bearer value. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In most cases you can use a client library to set up your calls to Google APIs (for example, when calling the Drive Files API ).

You can try out all the Google APIs and view their scopes at the OAuth 2.0 Playground .

HTTP GET examples

A call to the drive.files endpoint (the Drive Files API) using the Authorization: Bearer HTTP header might look like the following. Note that you need to specify your own access token:

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

Here is a call to the same API for the authenticated user using the access_token query string parameter:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl examples

You can test these commands with the curl command-line application. Here's an example that uses the HTTP header option (preferred):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Or, alternatively, the query string parameter option:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Refreshing an access token

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

To refresh an access token, your application sends an HTTPS POST request to Google's authorization server ( https://oauth2.googleapis.com/token ) that includes the following parameters:

The following snippet shows a sample request:

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

As long as the user has not revoked the access granted to the application, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:

{
  "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"
}

Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.

Revoking a token

In some cases a user may wish to revoke access given to an application. A user can revoke access by visiting Account Settings . See the Remove site or app access section of the Third-party sites & apps with access to your account support document for more information.

It is also possible for an application to programmatically revoke the access given to it. Programmatic revocation is important in instances where a user unsubscribes, removes an application, or the API resources required by an app have significantly changed. In other words, part of the removal process can include an API request to ensure the permissions previously granted to the application are removed.

To programmatically revoke a token, your application makes a request to https://oauth2.googleapis.com/revoke and includes the token as a parameter:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

App redirect methods

Protect your apps

Time-based access

Time-based access allows a user to grant your app access to their data for a limited duration to complete an action. Time-based access is available in select Google products during the consent flow, giving users the option to grant access for a limited period of time. An example is the Data Portability API which enables a one-time transfer of data.

When a user grants your application time-based access, the refresh token will expire after the specified duration. Note that refresh tokens may be invalidated earlier under specific circumstances; see these cases for details. The refresh_token_expires_in field returned in the authorization code exchange response represents the time remaining until the refresh token expires in such cases.

ادامه مطلب

The IETF Best Current Practice OAuth 2.0 for Native Apps establishes many of the best practices documented here.