این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

Google APIs Client Library و Google Identity Services

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

پیش نیازها

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

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن APIها را در آن فعال کند API Console.

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

Open the API Library در Google API Console.
If prompted, select a project, or create a new one.
را API Library همه API های موجود را فهرست می کند که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند. اگر API که می‌خواهید فعال کنید در لیست قابل مشاهده نیست، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
API را که می خواهید فعال کنید انتخاب کنید، سپس روی دکمه Enable کلیک کنید.
If prompted, enable billing.
If prompted, read and accept the API's Terms of Service.

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

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

Go to the Credentials page.
روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
نوع برنامه کاربردی وب را انتخاب کنید.
فرم را تکمیل کنید. برنامه‌هایی که از جاوا اسکریپت برای ایجاد درخواست‌های مجاز Google API استفاده می‌کنند، باید مبداهای مجاز جاوا اسکریپت را مشخص کنند. مبدا دامنه هایی را مشخص می کند که برنامه شما می تواند از آنها درخواست ها را به سرور OAuth 2.0 ارسال کند. این منابع باید از قوانین اعتبارسنجی Google پیروی کنند.

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

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

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

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

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

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

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

برای درخواست اجازه دسترسی به داده‌های کاربر، کاربر را به سرور OAuth 2.0 Google هدایت کنید.

نقاط پایانی OAuth 2.0

یک URL برای درخواست دسترسی از نقطه پایانی 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

مورد نیاز

برنامه های جاوا اسکریپت باید مقدار پارامتر را روی token تنظیم کنند. این مقدار به سرور مجوز Google دستور می دهد تا رمز دسترسی را به عنوان یک جفت name=value در شناسه قطعه URI ( # ) که کاربر پس از تکمیل فرآیند مجوز به آن هدایت می شود، بازگرداند.

scope

مورد نیاز

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

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

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

state

توصیه می شود

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

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

مهم: مشتری OAuth باید از CSRF همانطور که در مشخصات OAuth2 نامیده شده است جلوگیری کند. یکی از راه‌های رسیدن به این هدف، استفاده از پارامتر state برای حفظ حالت بین درخواست مجوز شما و پاسخ سرور مجوز است.

include_granted_scopes

اختیاری

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

enable_granular_consent

اختیاری

پیش فرض ها به true اگر روی false تنظیم شود، مجوزهای دقیق‌تر حساب Google برای شناسه‌های سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال می‌شود. برای شناسه‌های سرویس گیرنده OAuth جدیدتر تأثیری ندارد، زیرا مجوزهای دقیق‌تر همیشه برای آنها فعال است.

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

login_hint

اختیاری

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

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

prompt

اختیاری

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

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

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

تغییر مسیر نمونه به سرور مجوز Google

یک URL مثال در زیر نشان داده شده است، با خطوط شکسته و فاصله برای خوانایی.

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

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

کد نمونه جاوا اسکریپت

قطعه جاوا اسکریپت زیر نشان می دهد که چگونه می توان جریان مجوز در جاوا اسکریپت را بدون استفاده از Google APIs Client Library برای جاوا اسکریپت آغاز کرد. از آنجایی که این نقطه پایانی OAuth 2.0 از اشتراک‌گذاری منابع متقاطع (CORS) پشتیبانی نمی‌کند، قطعه فرمی ایجاد می‌کند که درخواست را به آن نقطه پایانی باز می‌کند.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

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

در این مرحله، کاربر تصمیم می گیرد که آیا به اپلیکیشن شما دسترسی درخواستی را بدهد یا خیر. در این مرحله، گوگل یک پنجره رضایت را نمایش می دهد که نام برنامه شما و سرویس های 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`

منبعی که درخواست از آنجا انجام شده است برای این مشتری مجاز نیست. origin_mismatch ببینید.

`invalid_grant`

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

`origin_mismatch`

طرح، دامنه و/یا پورت جاوا اسکریپت مبدأ درخواست مجوز ممکن است با URI مبدأ جاوا اسکریپت مجاز ثبت شده برای شناسه مشتری OAuth مطابقت نداشته باشد. منابع مجاز جاوا اسکریپت را بررسی کنید Google API ConsoleCredentials page.

`redirect_uri_mismatch`

redirect_uri ارسال شده در درخواست مجوز با URI تغییر مسیر مجاز برای شناسه مشتری OAuth مطابقت ندارد. URIهای مجاز تغییر مسیر را در Google API Console Credentials page.

پارامتر redirect_uri ممکن است به جریان OAuth خارج از باند (OOB) اشاره داشته باشد که منسوخ شده است و دیگر پشتیبانی نمی شود. برای به روز رسانی ادغام خود به راهنمای مهاجرت مراجعه کنید.

`invalid_request`

مشکلی در درخواستی که دادید وجود داشت. این می تواند به دلایل مختلفی باشد:

درخواست به درستی قالب بندی نشده بود
درخواست فاقد پارامترهای لازم بود
این درخواست از روش مجوزی استفاده می‌کند که Google از آن پشتیبانی نمی‌کند. بررسی کنید که ادغام OAuth شما از یک روش ادغام توصیه شده استفاده می کند

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

نقاط پایانی OAuth 2.0

مهم: قبل از رسیدگی به پاسخ OAuth 2.0، باید تأیید کنید که state دریافتی از Google با state ارسال شده در درخواست مجوز مطابقت دارد. این تأیید کمک می کند تا اطمینان حاصل شود که کاربر، نه یک اسکریپت مخرب، درخواست را انجام می دهد و خطر حملات CSRF را کاهش می دهد.

سرور OAuth 2.0 پاسخی را به redirect_uri مشخص شده در درخواست نشانه دسترسی شما ارسال می کند.

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

پاسخ نشانه دسترسی:
```
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
```
علاوه بر پارامتر access_token ، رشته قطعه همچنین شامل پارامتر token_type است که همیشه روی Bearer تنظیم می‌شود و پارامتر expires_in که طول عمر توکن را بر حسب ثانیه مشخص می‌کند. اگر پارامتر state در درخواست نشانه دسترسی مشخص شده بود، مقدار آن نیز در پاسخ لحاظ می شود.

یک پاسخ خطا:

https://oauth2.example.com/callback#error=access_denied

نمونه پاسخ سرور OAuth 2.0

می‌توانید این جریان را با کلیک بر روی نشانی اینترنتی نمونه زیر آزمایش کنید، که درخواست دسترسی فقط خواندنی برای مشاهده فراداده فایل‌ها در Google Drive شما و دسترسی فقط خواندنی برای مشاهده رویدادهای Google Calendar شما را دارد:

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

پس از تکمیل جریان OAuth 2.0، به http://localhost/oauth2callback هدایت خواهید شد. آن URL یک خطای 404 NOT FOUND را نشان می دهد مگر اینکه دستگاه محلی شما فایلی را در آن آدرس ارائه کند. مرحله بعدی جزئیات بیشتری را در مورد اطلاعات بازگردانده شده در URI هنگامی که کاربر به برنامه شما هدایت می شود ارائه می دهد.

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

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

نقاط پایانی OAuth 2.0

برای بررسی اینکه آیا کاربر به برنامه شما اجازه دسترسی به یک محدوده خاص را داده است یا خیر، فیلد 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

نقاط پایانی OAuth 2.0

پس از اینکه برنامه شما یک نشانه دسترسی به دست آورد، در صورتی که دامنه دسترسی مورد نیاز توسط 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

کد نمونه جاوا اسکریپت

قطعه کد زیر نحوه استفاده از CORS (اشتراک‌گذاری منابع متقاطع) را برای ارسال درخواست به Google API نشان می‌دهد. این مثال از Google APIs Client Library برای جاوا اسکریپت استفاده نمی کند. با این حال، حتی اگر از کتابخانه مشتری استفاده نمی کنید، راهنمای پشتیبانی CORS در اسناد آن کتابخانه احتمالاً به شما در درک بهتر این درخواست ها کمک می کند.

در این قطعه کد، متغیر access_token نشان دهنده نشانه ای است که شما برای درخواست API از طرف کاربر مجاز به دست آورده اید. مثال کامل نحوه ذخیره آن توکن در حافظه محلی مرورگر و بازیابی آن هنگام درخواست API را نشان می دهد.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

مثال کامل

نقاط پایانی OAuth 2.0

این نمونه کد نحوه تکمیل جریان OAuth 2.0 در جاوا اسکریپت را بدون استفاده از Google APIs Client Library برای جاوا اسکریپت نشان می دهد. کد مربوط به یک صفحه HTML است که دکمه ای را برای امتحان درخواست API نمایش می دهد. اگر روی دکمه کلیک کنید، کد بررسی می کند که آیا صفحه نشانه دسترسی API را در حافظه محلی مرورگر شما ذخیره کرده است یا خیر. اگر چنین است، درخواست API را اجرا می کند. در غیر این صورت، جریان OAuth 2.0 را آغاز می کند.

برای جریان OAuth 2.0، صفحه این مراحل را دنبال می کند:

کاربر را به سرور OAuth 2.0 Google هدایت می کند، که درخواست دسترسی به حوزه های https://www.googleapis.com/auth/drive.metadata.readonly و https://www.googleapis.com/auth/calendar.readonly را می کند.
پس از اعطای (یا رد کردن) دسترسی به یک یا چند محدوده درخواستی، کاربر به صفحه اصلی هدایت می شود که رمز دسترسی را از رشته شناسه قطعه تجزیه می کند.
صفحه بررسی می‌کند که کاربر به کدام حوزه دسترسی به برنامه را داده است.
اگر کاربر اجازه دسترسی به scope()های درخواستی را داده باشد، صفحه از نشانه دسترسی برای ایجاد نمونه درخواست API استفاده می کند.
درخواست API برای بازیابی اطلاعات مربوط به حساب Google Drive کاربر مجاز، روش about.get درایو API را فراخوانی می‌کند.
اگر درخواست با موفقیت اجرا شود، پاسخ API در کنسول اشکال زدایی مرورگر ثبت می شود.

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

برای اجرای این کد به صورت محلی، باید مقادیری را برای متغیرهای YOUR_CLIENT_ID و YOUR_REDIRECT_URI تنظیم کنید که مطابق با اعتبار مجوز شما باشد. متغیر YOUR_REDIRECT_URI باید روی همان URL که صفحه در حال ارائه است تنظیم شود. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در آن پیکربندی کرده اید. API Console Credentials page. اگر این مقدار با یک URI مجاز مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد. پروژه شما باید API مناسب برای این درخواست را نیز فعال کرده باشد.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        var xhr = new XMLHttpRequest();
        xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
        xhr.onreadystatechange = function (e) {
          if (xhr.readyState === 4 && xhr.status === 200) {
            console.log(xhr.response);
          } else if (xhr.readyState === 4 && xhr.status === 401) {
            // Token invalid, so prompt for user permission.
            oauth2SignIn();
          }
        };
        xhr.send(null);
      }
      else {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

قوانین اعتبارسنجی مبدا جاوا اسکریپت

Google قوانین اعتبارسنجی زیر را برای مبداهای جاوا اسکریپت اعمال می کند تا به توسعه دهندگان کمک کند تا برنامه های خود را ایمن نگه دارند. مبدا جاوا اسکریپت شما باید از این قوانین پیروی کند. RFC 3986 بخش 3 را برای تعریف دامنه، میزبان و طرح، که در زیر ذکر شده است، ببینید.

قوانین اعتبارسنجی
طرح	مبدا جاوا اسکریپت باید از طرح HTTPS استفاده کند، نه از HTTP ساده. URI های لوکال هاست (از جمله URI های IP آدرس لوکال هاست) از این قانون مستثنی هستند.
میزبان	هاست ها نمی توانند آدرس IP خام باشند. آدرس های IP Localhost از این قانون مستثنی هستند.
دامنه	میزبان TLD ( دامنه های سطح بالا ) باید به لیست پسوند عمومی تعلق داشته باشد. دامنه میزبان نمی تواند `“googleusercontent.com”` باشد. مبدا جاوا اسکریپت نمی‌تواند شامل دامنه‌های کوتاه‌کننده URL (به عنوان مثال `goo.gl` ) باشد، مگر اینکه برنامه مالک دامنه باشد.
اطلاعات کاربری	مبدا جاوا اسکریپت نمی تواند شامل زیرمجموعه اطلاعات کاربر باشد.
مسیر	مبدا جاوا اسکریپت نمی تواند شامل مولفه مسیر باشد.
پرس و جو	مبدا جاوا اسکریپت نمی تواند شامل مولفه پرس و جو باشد.
قطعه	مبدا جاوا اسکریپت نمی تواند شامل جزء قطعه باشد.
شخصیت ها	ریشه های جاوا اسکریپت نمی تواند شامل کاراکترهای خاصی باشد از جمله: کاراکترهای عام ( `'*'` ) کاراکترهای ASCII غیر قابل چاپ درصد رمزگذاری نامعتبر است (هر درصد رمزگذاری که از فرم رمزگذاری URL از علامت درصد و به دنبال آن دو رقم هگزا دسیمال پیروی نمی کند) کاراکترهای پوچ (یک نویسه NULL کدگذاری شده، به عنوان مثال، `%00` ، `%C0%80` )

مجوز افزایشی

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

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

در این حالت، در زمان ورود به سیستم، برنامه ممکن است از محدوده openid و profile درخواست کند تا ورود اولیه را انجام دهند، و سپس بعداً دامنه https://www.googleapis.com/auth/drive.file را در زمان ورود درخواست کند. اولین درخواست برای ذخیره یک میکس

قوانین زیر برای یک نشانه دسترسی به دست آمده از مجوز افزایشی اعمال می شود:

توکن را می توان برای دسترسی به منابع مربوط به هر یک از حوزه های موجود در مجوز جدید ترکیبی استفاده کرد.
هنگامی که از نشانه بازخوانی برای مجوز ترکیبی برای به دست آوردن یک نشانه دسترسی استفاده می کنید، نشانه دسترسی نشان دهنده مجوز ترکیبی است و می تواند برای هر یک از مقادیر scope موجود در پاسخ استفاده شود.
مجوز ترکیبی شامل تمام حوزه هایی است که کاربر به پروژه API اعطا کرده است، حتی اگر کمک هزینه ها از مشتریان مختلف درخواست شده باشد. به عنوان مثال، اگر کاربری با استفاده از کلاینت دسکتاپ یک برنامه به یک محدوده دسترسی داشته باشد و سپس از طریق یک کلاینت تلفن همراه به همان برنامه دسترسی داشته باشد، مجوز ترکیبی شامل هر دو حوزه می شود.
اگر توکنی را لغو کنید که نشان دهنده یک مجوز ترکیبی است، دسترسی به تمام حوزه های آن مجوز از طرف کاربر مرتبط به طور همزمان لغو می شود.

نمونه کدهای زیر نحوه افزودن دامنه به یک نشانه دسترسی موجود را نشان می دهد. این رویکرد به برنامه شما اجازه می دهد تا از مدیریت توکن های دسترسی چندگانه اجتناب کند.

نقاط پایانی OAuth 2.0

برای افزودن دامنه به یک نشانه دسترسی موجود، پارامتر include_granted_scopes را در درخواست خود به سرور OAuth 2.0 Google اضافه کنید.

قطعه کد زیر نحوه انجام این کار را نشان می دهد. قطعه فرض می کند که شما محدوده هایی را که رمز دسترسی شما برای آنها معتبر است در حافظه محلی مرورگر ذخیره کرده اید. (کد مثال کامل ، فهرستی از حوزه هایی را که نشانه دسترسی برای آنها معتبر است، با تنظیم ویژگی oauth2-test-params.scope در حافظه محلی مرورگر ذخیره می کند.)

اسنیپت محدوده هایی را که نشانه دسترسی برای آنها معتبر است با محدوده ای که می خواهید برای یک پرس و جوی خاص استفاده کنید مقایسه می کند. اگر نشانه دسترسی آن محدوده را پوشش ندهد، جریان OAuth 2.0 شروع می شود. در اینجا، تابع oauth2SignIn همان تابعی است که در مرحله 2 ارائه شد (و در ادامه در مثال کامل ارائه شده است).

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

باطل کردن یک نشانه

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

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

نقاط پایانی OAuth 2.0

برای لغو برنامه‌ای یک نشانه، برنامه شما درخواستی به 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 APIs Client Library برای جاوا اسکریپت باطل کرد. از آنجایی که نقطه پایانی Google OAuth 2.0 برای باطل کردن توکن‌ها از اشتراک‌گذاری منابع متقاطع (CORS) پشتیبانی نمی‌کند، کد به جای استفاده از روش XMLHttpRequest() برای ارسال درخواست، فرمی را ایجاد می‌کند و فرم را به نقطه پایانی ارسال می‌کند.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}

اجرای حفاظت از حساب های متقابل

گام دیگری که باید برای محافظت از حساب‌های کاربران خود بردارید، اجرای «محافظت بین حساب‌ها» با استفاده از سرویس محافظت از حساب‌های متقابل Google است. این سرویس به شما امکان می دهد در اعلان های رویداد امنیتی مشترک شوید که اطلاعاتی را در مورد تغییرات عمده در حساب کاربری به برنامه شما ارائه می دهد. سپس می‌توانید بسته به نحوه پاسخگویی به رویدادها، از اطلاعات استفاده کنید.

برخی از نمونه‌هایی از انواع رویدادهایی که توسط سرویس محافظت از حساب‌های متقابل Google به برنامه شما ارسال می‌شود عبارتند از:

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

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

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

Google APIs Client Library و Google Identity Services

پیش نیازها

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

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

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

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

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

نقاط پایانی OAuth 2.0

تغییر مسیر نمونه به سرور مجوز Google

کد نمونه جاوا اسکریپت

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

خطاها

admin_policy_enforced

disallowed_useragent

اندروید

iOS

org_internal

invalid_client

invalid_grant

origin_mismatch

redirect_uri_mismatch

invalid_request

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

نقاط پایانی OAuth 2.0

نمونه پاسخ سرور OAuth 2.0

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

نقاط پایانی OAuth 2.0

فراخوانی Google API

نقاط پایانی OAuth 2.0

نمونه های HTTP GET

نمونه های curl

کد نمونه جاوا اسکریپت

مثال کامل

نقاط پایانی OAuth 2.0

قوانین اعتبارسنجی مبدا جاوا اسکریپت

مجوز افزایشی

نقاط پایانی OAuth 2.0

باطل کردن یک نشانه

نقاط پایانی OAuth 2.0

اجرای حفاظت از حساب های متقابل

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_client`

`invalid_grant`

`origin_mismatch`

`redirect_uri_mismatch`

`invalid_request`

نمونه های `curl`