استفاده از OAuth 2.0 برای برنامه های وب سرور

این سند توضیح می‌دهد که چگونه برنامه‌های وب سرور از Google API Client Libraries یا Google OAuth 2.0 برای اجرای مجوز OAuth 2.0 برای دسترسی به Google API استفاده می‌کنند.

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

این جریان OAuth 2.0 به طور خاص برای مجوز کاربر است. این برای برنامه هایی طراحی شده است که می توانند اطلاعات محرمانه را ذخیره کرده و وضعیت را حفظ کنند. یک برنامه وب سرور مجاز به درستی می تواند به یک API دسترسی داشته باشد در حالی که کاربر با برنامه تعامل دارد یا بعد از اینکه کاربر برنامه را ترک کرد.

برنامه‌های کاربردی وب سرور اغلب از حساب‌های سرویس برای تأیید درخواست‌های API استفاده می‌کنند، به‌ویژه زمانی که برای دسترسی به داده‌های مبتنی بر پروژه به‌جای داده‌های خاص کاربر، API‌های Cloud را فراخوانی می‌کنند. برنامه های کاربردی وب سرور می توانند از حساب های خدماتی در ارتباط با مجوز کاربر استفاده کنند.

کتابخانه های مشتری

نمونه‌های مخصوص زبان در این صفحه از کتابخانه‌های سرویس گیرنده Google API برای اجرای مجوز OAuth 2.0 استفاده می‌کنند. برای اجرای نمونه کد، ابتدا باید کتابخانه کلاینت را برای زبان خود نصب کنید.

وقتی از Google API Client Library برای مدیریت جریان OAuth 2.0 برنامه خود استفاده می کنید، کتابخانه سرویس گیرنده اقدامات زیادی را انجام می دهد که در غیر این صورت برنامه به تنهایی باید آنها را مدیریت کند. برای مثال، تعیین می‌کند که برنامه چه زمانی می‌تواند از نشانه‌های دسترسی ذخیره‌شده یا بازخوانی آن استفاده کند و همچنین زمانی که برنامه باید مجدداً رضایت خود را دریافت کند. کتابخانه مشتری همچنین URLهای تغییر مسیر صحیحی را تولید می کند و به پیاده سازی کنترل کننده های تغییر مسیر که کدهای مجوز را برای توکن های دسترسی مبادله می کنند، کمک می کند.

کتابخانه های Google API Client برای برنامه های سمت سرور برای زبان های زیر در دسترس هستند:

پیش نیازها

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

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

    برای آزمایش، می توانید URI هایی را مشخص کنید که به ماشین محلی اشاره می کنند، مانند http://localhost:8080 . با در نظر گرفتن این موضوع، لطفاً توجه داشته باشید که همه نمونه‌های این سند از http://localhost:8080 به عنوان URI تغییر مسیر استفاده می‌کنند.

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

پس از ایجاد اعتبار، فایل client_secret.json را از API Consoleدانلود کنید. فایل را در مکانی ایمن ذخیره کنید که فقط برنامه شما بتواند به آن دسترسی داشته باشد.

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

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

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

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

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

الزامات خاص زبان

برای اجرای هر یک از نمونه کدهای موجود در این سند، به یک حساب Google، دسترسی به اینترنت و یک مرورگر وب نیاز دارید. اگر از یکی از کتابخانه های سرویس گیرنده API استفاده می کنید، شرایط خاص زبان را نیز در زیر ببینید.

PHP

برای اجرای نمونه کدهای PHP در این سند، به موارد زیر نیاز دارید:

  • PHP 5.6 یا بالاتر با رابط خط فرمان (CLI) و پسوند JSON نصب شده است.
  • ابزار مدیریت وابستگی Composer .

  • Google APIs Client Library برای PHP:

    composer require google/apiclient:^2.10

پایتون

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

  • پایتون 2.6 یا بالاتر
  • ابزار مدیریت بسته پیپ .
  • کتابخانه سرویس گیرنده Google APIs برای پایتون: 
    pip install --upgrade google-api-python-client
  • google-auth ، google-auth-oauthlib و google-auth-httplib2 برای مجوز کاربر. 
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • چارچوب برنامه وب Flask Python. 
    pip install --upgrade flask
  • کتابخانه HTTP requests 
    pip install --upgrade requests

روبی

برای اجرای نمونه کد روبی در این سند، به موارد زیر نیاز دارید:

  • روبی 2.6 یا بالاتر

  • کتابخانه Google Auth برای روبی:

    gem install googleauth

  • چارچوب برنامه وب سیناترا روبی.

    gem install sinatra

Node.js

برای اجرای نمونه کد Node.js در این سند، به موارد زیر نیاز دارید:

  • LTS تعمیر و نگهداری، LTS فعال یا نسخه فعلی Node.js.

  • Google APIs Node.js Client:

    npm install googleapis

HTTP/REST

برای اینکه بتوانید مستقیماً با نقاط پایانی OAuth 2.0 تماس بگیرید، نیازی به نصب هیچ کتابخانه ای ندارید.

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

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

لیست زیر به سرعت این مراحل را خلاصه می کند:

  1. برنامه شما مجوزهای مورد نیاز خود را شناسایی می کند.
  2. برنامه شما کاربر را به همراه لیست مجوزهای درخواستی به Google هدایت می کند.
  3. کاربر تصمیم می گیرد که آیا مجوزها را به برنامه شما اعطا کند یا خیر.
  4. برنامه شما متوجه می شود که کاربر چه تصمیمی گرفته است.
  5. اگر کاربر مجوزهای درخواستی را اعطا کرده باشد، برنامه شما نشانه های مورد نیاز برای درخواست های API را از طرف کاربر بازیابی می کند.

مرحله 1: پارامترهای مجوز را تنظیم کنید

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

  • اگر از کتابخانه سرویس گیرنده Google برای احراز هویت و مجوز OAuth 2.0 استفاده می کنید، شیئی را ایجاد و پیکربندی می کنید که این پارامترها را تعریف می کند.
  • اگر مستقیماً با نقطه پایانی Google OAuth 2.0 تماس بگیرید، یک URL ایجاد می‌کنید و پارامترها را روی آن URL تنظیم می‌کنید.

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

PHP

قطعه کد زیر یک شی Google\Client() ایجاد می کند که پارامترهای درخواست مجوز را تعریف می کند.

آن شی از اطلاعات فایل client_secret.json شما برای شناسایی برنامه شما استفاده می کند. (برای اطلاعات بیشتر درباره آن فایل، به ایجاد اعتبارنامه مجوز مراجعه کنید.) شی همچنین محدوده هایی را که برنامه شما برای دسترسی به آنها درخواست مجوز می کند و نشانی اینترنتی نقطه پایانی تأیید برنامه شما را شناسایی می کند، که پاسخ سرور OAuth 2.0 Google را مدیریت می کند. در نهایت، کد پارامترهای access_type اختیاری و include_granted_scopes را تنظیم می کند.

به عنوان مثال، این کد دسترسی آفلاین و فقط خواندنی به Google Drive کاربر را درخواست می کند:

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" will prompt the user for consent
$client->setPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

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

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

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

در PHP، تابع setAuthConfig را فراخوانی کنید تا اعتبارنامه مجوز از یک فایل client_secret.json بارگیری شود.

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
redirect_uri ضروری

تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در API ConsoleCredentials pageمشتری خود پیکربندی کرده اید. اگر این مقدار با URI تغییر مسیر مجاز برای client_id ارائه شده مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد.

توجه داشته باشید که طرح http یا https ، حروف کوچک و اسلش انتهایی (' / ') همه باید مطابقت داشته باشند.

برای تنظیم این مقدار در PHP، تابع setRedirectUri را فراخوانی کنید. توجه داشته باشید که باید یک URI تغییر مسیر معتبر برای client_id ارائه شده مشخص کنید.

$client->setRedirectUri('https://oauth2.example.com/code');
scope ضروری

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

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

برای تنظیم این مقدار در PHP، تابع addScope را فراخوانی کنید:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

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

access_type توصیه شده

نشان می دهد که آیا برنامه شما می تواند نشانه های دسترسی را در زمانی که کاربر در مرورگر حضور ندارد بازخوانی کند یا خیر. مقادیر پارامترهای معتبر online هستند که مقدار پیش‌فرض است و offline .

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

برای تنظیم این مقدار در PHP، تابع setAccessType را فراخوانی کنید:

$client->setAccessType('offline');
state توصیه شده

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

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

برای تنظیم این مقدار در PHP، تابع setState را فراخوانی کنید:

$client->setState($sample_passthrough_value);
include_granted_scopes اختیاری

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

برای تنظیم این مقدار در PHP، تابع setIncludeGrantedScopes را فراخوانی کنید:

$client->setIncludeGrantedScopes(true);
login_hint اختیاری

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

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

برای تنظیم این مقدار در PHP، تابع setLoginHint را فراخوانی کنید:

$client->setLoginHint('None');
prompt اختیاری

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

برای تنظیم این مقدار در PHP، تابع setPrompt را فراخوانی کنید:

$client->setPrompt('consent');

مقادیر ممکن عبارتند از:

none هیچ صفحه تایید یا رضایتی را نمایش ندهید. نباید با مقادیر دیگر مشخص شود.
consent درخواست رضایت از کاربر
select_account از کاربر بخواهید یک حساب کاربری را انتخاب کند.

پایتون

قطعه کد زیر از ماژول google-auth-oauthlib.flow برای ساخت درخواست مجوز استفاده می کند.

کد یک شی Flow می سازد که برنامه شما را با استفاده از اطلاعات فایل client_secret.json که پس از ایجاد اعتبارنامه های مجوز دانلود کرده اید شناسایی می کند. این شیء همچنین محدوده‌هایی را که برنامه شما برای دسترسی به آنها درخواست مجوز می‌کند و نشانی اینترنتی نقطه پایانی تأیید برنامه شما را مشخص می‌کند، که پاسخ سرور OAuth 2.0 Google را مدیریت می‌کند. در نهایت، کد پارامترهای access_type اختیاری و include_granted_scopes را تنظیم می کند.

به عنوان مثال، این کد دسترسی آفلاین و فقط خواندنی به Google Drive کاربر را درخواست می کند:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

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

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

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

در پایتون، متد from_client_secrets_file را برای بازیابی شناسه مشتری از فایل client_secret.json فراخوانی کنید. (همچنین می‌توانید از روش from_client_config استفاده کنید، که پیکربندی کلاینت را همانطور که در ابتدا در فایل مخفی کلاینت ظاهر می‌شد، منتقل می‌کند، اما به خود فایل دسترسی ندارد.)

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
redirect_uri ضروری

تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در API ConsoleCredentials pageمشتری خود پیکربندی کرده اید. اگر این مقدار با URI تغییر مسیر مجاز برای client_id ارائه شده مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد.

توجه داشته باشید که طرح http یا https ، حروف کوچک و اسلش انتهایی (' / ') همه باید مطابقت داشته باشند.

برای تنظیم این مقدار در پایتون، ویژگی redirect_uri شی flow را تنظیم کنید:

flow.redirect_uri = 'https://oauth2.example.com/code'
scope ضروری

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

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

در پایتون، از همان روشی استفاده کنید که برای تعیین لیست دامنه ها client_id تنظیم می کنید. 

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

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

access_type توصیه شده

نشان می دهد که آیا برنامه شما می تواند نشانه های دسترسی را در زمانی که کاربر در مرورگر حضور ندارد بازخوانی کند یا خیر. مقادیر پارامترهای معتبر online هستند که مقدار پیش‌فرض است و offline .

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

در پایتون، هنگام فراخوانی متد flow.authorization_url ، پارامتر access_type را با تعیین access_type به عنوان آرگومان کلمه کلیدی تنظیم کنید:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
state توصیه شده

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

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

در پایتون، هنگام فراخوانی متد flow.authorization_url ، با تعیین state به عنوان آرگومان کلمه کلیدی، پارامتر state را تنظیم کنید:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    state=sample_passthrough_value,
    include_granted_scopes='true')
include_granted_scopes اختیاری

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

در پایتون، هنگام فراخوانی متد flow.authorization_url ، پارامتر include_granted_scopes را با مشخص کردن include_granted_scopes به عنوان آرگومان کلمه کلیدی تنظیم کنید:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
login_hint اختیاری

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

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

در پایتون، هنگام فراخوانی متد flow.authorization_url ، با تعیین login_hint به عنوان آرگومان کلمه کلیدی، پارامتر login_hint را تنظیم کنید:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    login_hint='None',
    include_granted_scopes='true')
prompt اختیاری

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

در پایتون، هنگام فراخوانی متد flow.authorization_url ، با تعیین prompt به عنوان آرگومان کلمه کلیدی، پارامتر prompt را تنظیم کنید:

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

مقادیر ممکن عبارتند از:

none هیچ صفحه تایید یا رضایتی را نمایش ندهید. نباید با مقادیر دیگر مشخص شود.
consent درخواست رضایت از کاربر
select_account از کاربر بخواهید یک حساب کاربری را انتخاب کند.

روبی

از فایل client_secrets.json که ایجاد کرده اید برای پیکربندی یک شی کلاینت در برنامه خود استفاده کنید. هنگامی که یک شی کلاینت را پیکربندی می‌کنید، دامنه‌هایی را که برنامه شما باید به آن دسترسی داشته باشد، به همراه URL به نقطه پایانی تأیید برنامه خود، که پاسخ سرور OAuth 2.0 را مدیریت می‌کند، مشخص می‌کنید.

به عنوان مثال، این کد دسترسی آفلاین و فقط خواندنی به Google Drive کاربر را درخواست می کند:

require 'google/apis/drive_v3'
require "googleauth"
require 'googleauth/stores/redis_token_store'

client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')
scope = 'https://www.googleapis.com/auth/drive.metadata.readonly'
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, '/oauth2callback')


Your application uses the client object to perform OAuth 2.0 operations, such as generating
  authorization request URLs and applying access tokens to HTTP requests.

Node.js

The code snippet below creates a google.auth.OAuth2 object, which defines the parameters in the authorization request.

That object uses information from your client_secret.json file to identify your application. To ask for permissions from a user to retrieve an access token, you redirect them to a consent page. To create a consent page URL:

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

نکته مهم - refresh_token فقط در اولین مجوز بازگردانده می شود. جزئیات بیشتر در اینجا .

HTTP/REST

نقطه پایانی OAuth 2.0 Google در https://accounts.google.com/o/oauth2/v2/auth است. این نقطه پایانی فقط از طریق HTTPS قابل دسترسی است. اتصالات HTTP ساده رد می شود.

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

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

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

redirect_uri ضروری

تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در API ConsoleCredentials pageمشتری خود پیکربندی کرده اید. اگر این مقدار با URI تغییر مسیر مجاز برای client_id ارائه شده مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد.

توجه داشته باشید که طرح http یا https ، حروف کوچک و اسلش انتهایی (' / ') همه باید مطابقت داشته باشند.

response_type ضروری

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

مقدار پارامتر را برای code برنامه های وب سرور تنظیم کنید.

scope ضروری

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

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

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

access_type توصیه شده

نشان می دهد که آیا برنامه شما می تواند نشانه های دسترسی را در زمانی که کاربر در مرورگر حضور ندارد بازخوانی کند یا خیر. مقادیر پارامترهای معتبر online هستند که مقدار پیش‌فرض است و offline .

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

state توصیه شده

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

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

include_granted_scopes اختیاری

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

login_hint اختیاری

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

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

prompt اختیاری

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

مقادیر ممکن عبارتند از:

none هیچ صفحه تایید یا رضایتی را نمایش ندهید. نباید با مقادیر دیگر مشخص شود.
consent درخواست رضایت از کاربر
select_account از کاربر بخواهید یک حساب کاربری را انتخاب کند.

مرحله 2: به سرور OAuth 2.0 گوگل هدایت شوید

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

PHP

  1. ایجاد یک URL برای درخواست دسترسی از سرور OAuth 2.0 Google: 
    $auth_url = $client->createAuthUrl();
  2. کاربر را به $auth_url : 
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
    هدایت کنید

پایتون

این مثال نحوه هدایت کاربر را به URL مجوز با استفاده از چارچوب برنامه وب Flask نشان می دهد:

return flask.redirect(authorization_url)

روبی

  1. ایجاد یک URL برای درخواست دسترسی از سرور OAuth 2.0 Google: 
    auth_uri = authorizer.get_authorization_url(login_hint: user_id, request: request)
  2. کاربر را به auth_uri هدایت کنید.

Node.js

  1. برای درخواست دسترسی از سرور OAuth 2.0، از URL authorizationUrl ایجاد شده از روش generateAuthUrl مرحله 1 استفاده کنید.
  2. کاربر را به authorizationUrl هدایت کنید. 
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

پس از ایجاد URL درخواست، کاربر را به آن هدایت کنید.

سرور OAuth 2.0 Google کاربر را احراز هویت می کند و از کاربر رضایت می گیرد تا برنامه شما به محدوده های درخواستی دسترسی پیدا کند. پاسخ با استفاده از URL تغییر مسیری که مشخص کرده اید به برنامه شما ارسال می شود.

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

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

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

خطاها

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

admin_policy_enforced

حساب Google به دلیل خط‌مشی‌های سرپرست Google Workspace نمی‌تواند یک یا چند محدوده درخواستی را تأیید کند. برای اطلاعات بیشتر در مورد اینکه چگونه یک سرپرست می‌تواند دسترسی به همه حوزه‌ها یا محدوده‌های حساس و محدود را تا زمانی که صراحتاً به شناسه مشتری OAuth شما اعطا نشود، به مقاله راهنمای Google Workspace Admin مراجعه کنید.

disallowed_useragent

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

اندروید

برنامه‌نویسان Android ممکن است هنگام باز کردن درخواست‌های مجوز در android.webkit.WebView با این پیام خطا مواجه شوند. توسعه‌دهندگان باید در عوض از کتابخانه‌های Android مانند Google Sign-In برای Android یا OpenID Foundation's AppAuth for Android استفاده کنند.

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

iOS

توسعه دهندگان iOS و macOS ممکن است هنگام باز کردن درخواست های مجوز در WKWebView با این خطا مواجه شوند. توسعه‌دهندگان باید در عوض از کتابخانه‌های iOS مانند Google Sign-In برای iOS یا OpenID Foundations AppAuth برای iOS استفاده کنند.

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

org_internal

شناسه مشتری OAuth در درخواست بخشی از پروژه ای است که دسترسی به حساب های Google را در یک سازمان Google Cloud خاص محدود می کند. برای اطلاعات بیشتر در مورد این گزینه پیکربندی، بخش نوع کاربر را در مقاله راهنمای تنظیم صفحه رضایت OAuth خود ببینید.

invalid_client

راز مشتری OAuth نادرست است. پیکربندی سرویس گیرنده OAuth را مرور کنید، از جمله شناسه مشتری و راز استفاده شده برای این درخواست.

invalid_grant

هنگام بازخوانی یک نشانه دسترسی یا استفاده از مجوز افزایشی ، ممکن است نشانه منقضی شده باشد یا باطل شده باشد. مجدداً کاربر را احراز هویت کنید و برای دریافت توکن های جدید رضایت کاربر را بخواهید. If you are continuing to see this error, ensure that your application has been configured correctly and that you are using the correct tokens and parameters in your request. Otherwise, the user account may have been deleted or disabled.

redirect_uri_mismatch

The redirect_uri passed in the authorization request does not match an authorized redirect URI for the OAuth client ID. Review authorized redirect URIs in the Google API Console Credentials page.

The redirect_uri parameter may refer to the OAuth out-of-band (OOB) flow that has been deprecated and is no longer supported. Refer to the migration guide to update your integration.

invalid_request

There was something wrong with the request you made. This could be due to a number of reasons:

  • The request was not properly formatted
  • The request was missing required parameters
  • The request uses an authorization method that Google doesn't support. Verify your OAuth integration uses a recommended integration method

Step 4: Handle the OAuth 2.0 server response

The OAuth 2.0 server responds to your application's access request by using the URL specified in the request.

If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message that is returned to the web server appears on the query string, as shown below:

An error response:

https://oauth2.example.com/auth?error=access_denied

An authorization code response:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Sample OAuth 2.0 server response

You can test this flow by clicking on the following sample URL, which requests read-only access to view metadata for files in your Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

After completing the OAuth 2.0 flow, you should be redirected to http://localhost/oauth2callback , which will likely yield a 404 NOT FOUND error unless your local machine serves a file at that address. The next step provides more detail about the information returned in the URI when the user is redirected back to your application.

Step 5: Exchange authorization code for refresh and access tokens

After the web server receives the authorization code, it can exchange the authorization code for an access token.

PHP

To exchange an authorization code for an access token, use the authenticate method:

$client->authenticate($_GET['code']);

You can retrieve the access token with the getAccessToken method:

$access_token = $client->getAccessToken();

Python

On your callback page, use the google-auth library to verify the authorization server response. Then, use the flow.fetch_token method to exchange the authorization code in that response for an access token:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

On your callback page, use the googleauth library to verify the authorization server response. Use the authorizer.handle_auth_callback_deferred method to save the authorization code and redirect back to the URL that originally requested authorization. This defers the exchange of the code by temporarily stashing the results in the user's session.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

To exchange an authorization code for an access token, use the getToken method:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

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

زمینه های
client_id The client ID obtained from the API ConsoleCredentials page.
client_secret The client secret obtained from the API ConsoleCredentials page.
code The authorization code returned from the initial request.
grant_type As defined in the OAuth 2.0 specification , this field's value must be set to authorization_code .
redirect_uri One of the redirect URIs listed for your project in the API ConsoleCredentials page for the given client_id .

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=https%3A//oauth2.example.com/code&
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. Note that the refresh token is only returned if your application set the access_type parameter to offline in the initial request to Google's authorization server .

The response contains the following fields:

زمینه های
access_token The token that your application sends to authorize a Google API request.
expires_in The remaining lifetime of the access token in seconds.
refresh_token A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access. Again, this field is only present in this response if you set the access_type parameter to offline in the initial request to Google's authorization server.
scope The scopes of access granted by the access_token expressed as a list of space-delimited, case-sensitive strings.
token_type The type of token returned. At this time, this field's value is always set to Bearer .

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",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

خطاها

When exchanging the authorization code for an access token you may encounter the following error instead of the expected response. Common error codes and suggested resolutions are listed below.

invalid_grant

The supplied authorization code is invalid or in the wrong format. Request a new code by restarting the OAuth process to prompt the user for consent again.

Calling Google APIs

PHP

Use the access token to call Google APIs by completing the following steps:

  1. If you need to apply an access token to a new Google\Client object — for example, if you stored the access token in a user session — use the setAccessToken method: 
    $client->setAccessToken($access_token);
  2. Build a service object for the API that you want to call. You build a service object by providing an authorized Google\Client object to the constructor for the API you want to call. For example, to call the Drive API: 
    $drive = new Google\Service\Drive($client);
  3. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive: 
    $files = $drive->files->listFiles(array())->getItems();

Python

After obtaining an access token, your application can use that token to authorize API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

  1. Build a service object for the API that you want to call. You build a service object by calling the googleapiclient.discovery library's build method with the name and version of the API and the user credentials: For example, to call version 3 of the Drive API: 
    from googleapiclient.discovery import build

drive = build('drive', 'v2', credentials=credentials)
  2. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive: 
    files = drive.files().list().execute()

Ruby

After obtaining an access token, your application can use that token to make API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

  1. Build a service object for the API that you want to call. For example, to call version 3 of the Drive API: 
    drive = Google::Apis::DriveV3::DriveService.new
  2. Set the credentials on the service: 
    drive.authorization = credentials
  3. Make requests to the API service using the interface provided by the service object . For example, to list the files in the authenticated user's Google Drive: 
    files = drive.list_files

Alternately, authorization can be provided on a per-method basis by supplying the options parameter to a method:

files = drive.list_files(options: { authorization: credentials })

Node.js

After obtaining an access token and setting it to the OAuth2 object, use the object to call Google APIs. Your application can use that token to authorize API requests on behalf of a given user account or service account. Build a service object for the API that you want to call.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

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

Complete example

The following example prints a JSON-formatted list of files in a user's Google Drive after the user authenticates and gives consent for the application to access the user's Drive metadata.

PHP

To run this example:

  1. In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add http://localhost:8080 .
  2. Create a new directory and change to it. For example: 
    mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
  3. Install the Google API Client Library for PHP using Composer : 
    composer require google/apiclient:^2.10
  4. Create the files index.php and oauth2callback.php with the content below.
  5. Run the example with a web server configured to serve PHP. If you use PHP 5.6 or newer, you can use PHP's built-in test web server: 
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

This example uses the Flask framework. It runs a web application at http://localhost:8080 that lets you test the OAuth 2.0 flow. If you go to that URL, you should see four links:

  • Test an API request: This link points to a page that tries to execute a sample API request. If necessary, it starts the authorization flow. If successful, the page displays the API response.
  • Test the auth flow directly: This link points to a page that tries to send the user through the authorization flow . The app requests permission to submit authorized API requests on the user's behalf.
  • Revoke current credentials: This link points to a page that revokes permissions that the user has already granted to the application.
  • Clear Flask session credentials: This link clears authorization credentials that are stored in the Flask session. This lets you see what would happen if a user who had already granted permission to your app tried to execute an API request in a new session. It also lets you see the API response your app would get if a user had revoked permissions granted to your app, and your app still tried to authorize a request with a revoked access token.
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

This example uses the Sinatra framework.

require 'google/apis/drive_v3'
require 'sinatra'
require 'googleauth'
require 'googleauth/stores/redis_token_store'

configure do
  enable :sessions

  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')
  set :scope, Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, '/oauth2callback')
end

get '/' do
  user_id = settings.client_id.id
  credentials = settings.authorizer.get_credentials(user_id, request)
  if credentials.nil?
    redirect settings.authorizer.get_authorization_url(login_hint: user_id, request: request)
  end
  drive = Google::Apis::DriveV3::DriveService.new
  files = drive.list_files(options: { authorization: credentials })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

To run this example:

  1. In the API Console, add the URL of the local machine to the list of redirect URLs. For example, add http://localhost .
  2. Make sure you have maintenance LTS, active LTS, or current release of Node.js installed.
  3. Create a new directory and change to it. For example: 
    mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm: 
    npm install googleapis
  5. Create the files main.js with the content below.
  6. Run the example: 
    node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

This Python example uses the Flask framework and the Requests library to demonstrate the OAuth 2.0 web flow. We recommend using the Google API Client Library for Python for this flow. (The example in the Python tab does use the client library.)

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Redirect URI validation rules

Google applies the following validation rules to redirect URIs in order to help developers keep their applications secure. Your redirect URIs must adhere to these rules. See RFC 3986 section 3 for the definition of domain, host, path, query, scheme and userinfo, mentioned below.

Validation rules
Scheme

Redirect URIs must use the HTTPS scheme, not plain HTTP. Localhost URIs (including localhost IP address URIs) are exempt from this rule.

Host

Hosts cannot be raw IP addresses. Localhost IP addresses are exempted from this rule.

Domain
  • Host TLDs ( Top Level Domains ) must belong to the public suffix list .
  • Host domains cannot be “googleusercontent.com” .
  • Redirect URIs cannot contain URL shortener domains (eg goo.gl ) unless the app owns the domain. Furthermore, if an app that owns a shortener domain chooses to redirect to that domain, that redirect URI must either contain “/google-callback/” in its path or end with “/google-callback” .
    • Userinfo

    Redirect URIs cannot contain the userinfo subcomponent.

    Path

    Redirect URIs cannot contain a path traversal (also called directory backtracking), which is represented by an “/..” or “\..” or their URL encoding.

    Query

    Redirect URIs cannot contain open redirects .

    Fragment

    Redirect URIs cannot contain the fragment component.

    Characters Redirect URIs cannot contain certain characters including:
    • Wildcard characters ( '*' )
    • Non-printable ASCII characters
    • Invalid percent encodings (any percent encoding that does not follow URL-encoding form of a percent sign followed by two hexadecimal digits)
    • Null characters (an encoded NULL character, eg, %00 , %C0%80 )

    Incremental authorization

    In the OAuth 2.0 protocol, your app requests authorization to access resources, which are identified by scopes. It is considered a best user-experience practice to request authorization for resources at the time you need them. To enable that practice, Google's authorization server supports incremental authorization. This feature lets you request scopes as they are needed and, if the user grants permission for the new scope, returns an authorization code that may be exchanged for a token containing all scopes the user has granted the project.

    For example, an app that lets people sample music tracks and create mixes might need very few resources at sign-in time, perhaps nothing more than the name of the person signing in. However, saving a completed mix would require access to their Google Drive. Most people would find it natural if they only were asked for access to their Google Drive at the time the app actually needed it.

    In this case, at sign-in time the app might request the openid and profile scopes to perform basic sign-in, and then later request the https://www.googleapis.com/auth/drive.file scope at the time of the first request to save a mix.

    To implement incremental authorization, you complete the normal flow for requesting an access token but make sure that the authorization request includes previously granted scopes. This approach allows your app to avoid having to manage multiple access tokens.

    The following rules apply to an access token obtained from an incremental authorization:

    • The token can be used to access resources corresponding to any of the scopes rolled into the new, combined authorization.
    • When you use the refresh token for the combined authorization to obtain an access token, the access token represents the combined authorization and can be used for any of the scope values included in the response.
    • The combined authorization includes all scopes that the user granted to the API project even if the grants were requested from different clients. For example, if a user granted access to one scope using an application's desktop client and then granted another scope to the same application via a mobile client, the combined authorization would include both scopes.
    • If you revoke a token that represents a combined authorization, access to all of that authorization's scopes on behalf of the associated user are revoked simultaneously.

    The language-specific code samples in Step 1: Set authorization parameters and the sample HTTP/REST redirect URL in Step 2: Redirect to Google's OAuth 2.0 server all use incremental authorization. The code samples below also show the code that you need to add to use incremental authorization.

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

    In Python, set the include_granted_scopes keyword argument to true to ensure that an authorization request includes previously granted scopes. It is very possible that include_granted_scopes will not be the only keyword argument that you set, as shown in the example below.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Ruby

    auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.file&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

    Refreshing an access token (offline access)

    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.

    • If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
    • If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server . In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

    Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online .

    Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

    PHP

    If your application needs offline access to a Google API, set the API client's access type to offline :

    $client->setAccessType("offline");

    After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

    Python

    In Python, set the access_type keyword argument to offline to ensure that you will be able to refresh the access token without having to re-prompt the user for permission. It is very possible that access_type will not be the only keyword argument that you set, as shown in the example below.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

    Ruby

    If your application needs offline access to a Google API, set the API client's access type to offline :

    auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

    After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

    Node.js

    If your application needs offline access to a Google API, set the API client's access type to offline :

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    After a user grants offline access to the requested scopes, you can continue to use the API client to access Google APIs on the user's behalf when the user is offline. The client object will refresh the access token as needed.

    Access tokens expire. This library will automatically use a refresh token to obtain a new access token if it is about to expire. An easy way to make sure you always store the most recent tokens is to use the tokens event:

    oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

    This tokens event only occurs in the first authorization, and you need to have set your access_type to offline when calling the generateAuthUrl method to receive the refresh token. If you have already given your app the requisiste permissions without setting the appropriate constraints for receiving a refresh token, you will need to re-authorize the application to receive a fresh refresh token.

    To set the refresh_token at a later time, you can use the setCredentials method:

    oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

    Once the client has a refresh token, access tokens will be acquired and refreshed automatically in the next call to the API.

    HTTP/REST

    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:

    زمینه های
    client_id The client ID obtained from the API Console.
    client_secret The client secret obtained from the API Console.
    grant_type As defined in the OAuth 2.0 specification , this field's value must be set to refresh_token .
    refresh_token The refresh token returned from the authorization code exchange.

    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",
  "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.

    PHP

    To programmatically revoke a token, call revokeToken() :

    $client->revokeToken();

    Python

    To programmatically revoke a token, make a request to https://oauth2.googleapis.com/revoke that includes the token as a parameter and sets the Content-Type header:

    requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    To programmatically revoke a token, make an HTTP request to the oauth2.revoke endpoint:

    uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_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 status code of the response is 200 . For error conditions, a status code 400 is returned along with an error code.

    Node.js

    To programmatically revoke a token, make an HTTPS POST request to /revoke endpoint:

    const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

    The token parameter 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 status code of the response is 200 . For error conditions, a status code 400 is returned along with an error code.

    HTTP/REST

    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.