این سند توضیح می‌دهد که چگونه مجوز OAuth 2.0 را برای دسترسی به میاناهای برنامه‌سازی کاربردی Google از برنامه وب جاوا اسکریپت پیاده‌سازی کنید. OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و سایر اطلاعاتشان را خصوصی نگه دارند. برای مثال، یک برنامه می‌تواند از OAuth 2.0 برای دریافت اجازه از کاربران برای ذخیره فایل‌ها در Google Drive آن‌ها استفاده کند.
این جریان OAuth 2.0 جریان اعطای ضمنی نامیده می‌شود. این نوع برای برنامه‌هایی طراحی شده است که فقط وقتی کاربر در برنامه حضور دارد به میاناهای برنامه‌سازی کاربردی دسترسی پیدا می‌کنند. این برنامه‌ها نمی‌توانند اطلاعات محرمانه را ذخیره کنند.
در این جریان، برنامه شما نشانی وب Google را باز می‌کند که از پارامترهای پُرسمان برای شناسایی برنامه شما و نوع دسترسی به API که برنامه نیاز دارد استفاده می‌کند. می‌توانید نشانی وب را در پنجره مرورگر فعلی یا کادر گفتگویی باز کنید. کاربر می‌تواند با Google اصالت‌سنجی کند و اجازه‌های درخواست‌شده را اعطا کند. سپس Google کاربر را به برنامه شما هدایت می‌کند. این هدایت شامل یک کد دسترسی است که برنامه شما آن را درستی‌سنجی می‌کند و سپس از آن برای ارسال درخواست‌های API استفاده می‌کند.
کتابخانه کارخواه Google APIs و سرویس‌های مدیریت هویت Google
اگر از کتابخانه مشتری Google APIs برای جاوا اسکریپت برای برقراری تماس‌های مجاز با Google استفاده می‌کنید، باید از کتابخانه جاوا اسکریپت سرویس‌های هویتی Google برای مدیریت جریان مجوز استفاده کنید. به‌شدت توصیه می‌کنیم از مدل کد «سرویس‌های هویت Google» استفاده کنید که براساس جریان کد مجوز امن‌تر با PKCE است.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:
- در «کنسول Google API»، کتابخانه API را باز کنید.
- اگر از شما درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی بسازید.
- «کتابخانه API» همه میاناهای برنامه‌سازی کاربردی دردسترس را فهرست می‌کند و آن‌ها را براساس خانواده محصول و محبوبیت گروه‌بندی می‌کند. اگر API موردنظرتان برای فعال کردن در فهرست قابل‌مشاهده نیست، از جستجو برای یافتن آن استفاده کنید، یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
- میانای برنامه‌سازی کاربردی موردنظر را برای فعال کردن انتخاب کنید، سپس روی دکمه فعال کردن کلیک کنید.
- اگر درخواست شد، صدور صورت‌حساب را فعال کنید.
- درصورت درخواست، «شرایط خدمات» API را بخوانید و بپذیرید.
ایجاد اعتبارنامه مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google APIs استفاده می‌کند باید اطلاعات اعتباری مجوز داشته باشد که برنامه را به سرور OAuth 2.0 Google معرفی کند. مراحل زیر نحوه ایجاد اعتبارنامه برای پروژه‌تان را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه «کارخواهان» بروید.
- روی ایجاد مشتری کلیک کنید.
- نوع برنامه برنامه وب را انتخاب کنید.
- فرم را تکمیل کنید. برنامه‌هایی که از جاوا اسکریپت برای ایجاد درخواست‌های مجاز Google API استفاده می‌کنند باید مبدأهای جاوا اسکریپت مجاز را مشخص کنند. مبدأها دامنه‌هایی را که برنامه شما می‌تواند از آن‌ها درخواست به سرور OAuth 2.0 ارسال کند شناسایی می‌کنند. این مبدأها باید از قوانین اعتبارسنجی Google پیروی کنند.
شناسایی محدوده‌های دسترسی
گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد درخواست دسترسی دهد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما اعطا می‌کنند کنترل کنند. بنابراین، ممکن است بین تعداد گستره‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود داشته باشد.
قبل‌از شروع پیاده‌سازی مجوز OAuth 2.0، توصیه می‌کنیم دامنه‌هایی را که برنامه‌تان برای دسترسی به آن‌ها نیاز به اجازه دارد شناسایی کنید.
سند OAuth 2.0 API Scopes حاوی فهرست کاملی از دامنه‌هایی است که ممکن است برای دسترسی به Google API استفاده کنید.
دریافت کدهای دسترسی OAuth 2.0
مراحل زیر نشان می‌دهد که برنامه شما چگونه با سرور OAuth 2.0 Google تعامل می‌کند تا رضایت کاربر را برای انجام درخواست API ازطرف کاربر دریافت کند. برنامه شما باید قبل‌از اجرای درخواست Google API که به مجوز کاربر نیاز دارد، این رضایت را داشته باشد.
مرحله ۱: هدایت به سرور OAuth 2.0 Google
برای درخواست اجازه دسترسی به داده‌های کاربر، کاربر را به سرور OAuth 2.0 Google هدایت کنید.
نقطه‌های پایانی OAuth 2.0
نشانی وبی برای درخواست دسترسی از نقطه پایان OAuth 2.0 در Google در
https://accounts.google.com/o/oauth2/v2/auth تولید کنید. این نقطه پایان ازطریق HTTPS قابل‌دسترس است؛
اتصال‌های HTTP ساده رد می‌شود.
سرور مجوز Google از پارامترهای رشته پُرسمان زیر برای برنامه‌های سرور وب پشتیبانی می‌کند:
| پارامترها | |||||||
|---|---|---|---|---|---|---|---|
client_id |
الزامی
شناسه کارخواه برای برنامه شما. این مقدار را می‌توانید در «کنسول Cloud» صفحه «کارخواه‌ها» پیدا کنید. |
||||||
redirect_uri |
الزامی
تعیین می‌کند که سرور میانای برنامه‌سازی کاربردی پس‌از تکمیل جریان مجوز توسط کاربر، او را به کجا هدایت کند. این مقدار باید دقیقاً با یکی از URIهای هدایت مجاز برای کارخواه OAuth 2.0 که در صفحه «کارخواه‌ها» در Cloud Console کارخواه پیکربندی کرده‌اید مطابقت داشته باشد. اگر این مقدار با شناسه منبع یکسان هدایت مجاز برای توجه داشته باشید که طرح |
||||||
response_type |
الزامی
برنامه‌های جاوا اسکریپت باید مقدار پارامتر را روی |
||||||
scope |
الزامی
فهرست جداشده با فاصله از حوزه‌هایی که منابعی را که برنامه شما می‌تواند ازطرف کاربر به آن‌ها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه رضایت که Google به کاربر نمایش می‌دهد اطلاع‌رسانی می‌کند. گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی داشته باشد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، رابطه‌ای معکوس بین تعداد دامنه‌های درخواستی و احتمال کسب رضایت کاربر وجود دارد. توصیه می‌کنیم برنامه‌تان درصورت امکان، دسترسی به گستره‌های مجوز را در بافت درخواست کند. با درخواست دسترسی به داده‌های کاربر در بافت، بااستفاده از مجوز فزاینده، به کاربران کمک می‌کنید متوجه شوند چرا برنامه‌تان به دسترسی‌ای که درخواست می‌کند نیاز دارد. |
||||||
state |
توصیه‌شده
هر مقدار رشته‌ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می‌کند، مشخص می‌کند.
سرور مقدار دقیقی را که به‌عنوان جفت می‌توانید از این پارامتر برای اهداف مختلفی استفاده کنید، مثلاً هدایت کاربر به منبع صحیح در برنامه، ارسال اعداد یک‌بارمصرف، و کاهش جعل درخواست بین‌سایتی. ازآنجایی‌که |
||||||
include_granted_scopes |
اختیاری
به برنامه‌ها امکان می‌دهد از صدور مجوز افزایشی برای درخواست دسترسی به
حوزه‌های اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی |
||||||
enable_granular_consent |
اختیاری
پیش‌فرض وقتی Google اجازه‌های ریزدانه را برای برنامه‌ای فعال می‌کند، این پارامتر دیگر تأثیری نخواهد داشت. |
||||||
login_hint |
اختیاری
اگر برنامه شما می‌داند کدام کاربر درحال تلاش برای اصالت‌سنجی است، می‌تواند از این پارامتر برای ارائه راهنمایی به «سرور اصالت‌سنجی Google» استفاده کند. سرور از این راهنمایی برای ساده کردن جریان ورود به سیستم استفاده می‌کند، یا با پیش‌تکمیل کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چندورودی مناسب. مقدار پارامتر را روی نشانی ایمیل یا شناسه |
||||||
prompt |
اختیاری
فهرست پیام‌واره‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند و به کاربر ارائه می‌شود. اگر این پارامتر را مشخص نکنید، کاربر فقط اولین‌باری که پروژه شما درخواست دسترسی می‌کند از او درخواست می‌شود. برای اطلاعات بیشتر، درخواست رضایت مجدد را ببینید. مقادیر ممکن عبارت‌اند از:
|
||||||
نمونه هدایت به سرور مجوز Google
نمونه نشانی وب در زیر نشان داده شده است، با شکست خط و فاصله برای خوانایی.
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//developers.google.com/oauthplayground& client_id=client_id
پس‌از ایجاد نشانی وب درخواست، کاربر را به آن هدایت کنید.
کد نمونه جاوا اسکریپت
قطعه کد جاوا اسکریپت زیر نشان می‌دهد که چگونه جریان مجوز را در جاوا اسکریپت بدون استفاده از کتابخانه مشتری Google APIs برای جاوا اسکریپت آغاز کنید. ازآنجایی‌که این نقطه پایانی 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(); }
مرحله ۲: Google از کاربر درخواست موافقت می‌کند
در این مرحله، کاربر تصمیم می‌گیرد که دسترسی درخواستی را به برنامه شما اعطا کند یا نه. در این مرحله، Google پنجره رضایتی را نمایش می‌دهد که نام برنامه شما و سرویس‌های Google API را که برنامه برای دسترسی به آن‌ها با اطلاعات اعتباری مجوز کاربر درخواست اجازه می‌کند و خلاصه‌ای از دامنه‌های دسترسی که باید اعطا شود نشان می‌دهد. سپس کاربر می‌تواند با اعطای دسترسی به یک یا چند دامنه درخواست‌شده توسط برنامه شما موافقت کند یا درخواست را رد کند.
برنامه شما در این مرحله لازم نیست کاری انجام دهد زیرا منتظر پاسخ از سرور OAuth 2.0 در Google است که نشان می‌دهد آیا دسترسی اعطا شده است یا نه. آن پاسخ در مرحله زیر توضیح داده شده است.
خطاها
درخواست‌ها به نقطه پایانی مجوز OAuth 2.0 در Google ممکن است به‌جای جریان‌های اصالت‌سنجی و مجوز موردانتظار، پیام‌های خطای روبه‌کاربر نمایش دهند. کدهای خطای رایج و راه‌حل‌های پیشنهادی عبارت‌اند از:
admin_policy_enforced
«حساب Google» به‌دلیل خط‌مشی‌های سرپرست Google Workspace خود نمی‌تواند یک یا چند حوزه درخواستی را مجاز کند. برای اطلاعات بیشتر درباره اینکه سرپرست چگونه می‌تواند دسترسی به همه حوزه‌ها یا حوزه‌های حساس و محدودشده را تا زمانی که دسترسی به‌طور صریح به شناسه مشتری OAuth شما اعطا شود محدود کند، به مقاله راهنمای «سرپرست Google Workspace» مراجعه کنید کنترل کنید کدام برنامه‌های طرف سوم و داخلی به داده‌های Google Workspace دسترسی داشته باشند.
disallowed_useragent
نقطه پایان مجوز در یک عامل کاربر جاسازی‌شده نمایش داده می‌شود که توسط خط‌مشی‌های OAuth 2.0 Google مجاز نیست.
توسعه‌دهندگان iOS و macOS ممکن است هنگام باز کردن درخواست‌های مجوز در
WKWebView با این خطا مواجه شوند.
توسعه‌دهندگان باید به‌جای آن از کتابخانه‌های iOS مانند
ورود به سیستم با Google برای iOS یا
AppAuth برای iOS از OpenID Foundation استفاده کنند.
توسعه‌دهندگان وب ممکن است زمانی با این خطا مواجه شوند که برنامه iOS یا macOS پیوند وب عمومی را در
عامل کاربر جاسازی‌شده باز کند و کاربر از سایت شما به نقطه پایانی مجوز OAuth 2.0 در Google
پیمایش کند. توسعه‌دهندگان باید اجازه دهند پیوندهای عمومی در مدیریت‌کننده پیوند پیش‌فرض سیستم‌عامل باز شوند، که شامل هر دو مدیریت‌کننده پیوندهای جهانی یا برنامه مرورگر پیش‌فرض می‌شود. کتابخانه SFSafariViewController نیز گزینه پشتیبانی‌شده‌ای است.
org_internal
شناسه کارخواه OAuth در درخواست بخشی از پروژه‌ای است که دسترسی به «حساب‌های Google» را در سازمان Google Cloud خاصی محدود می‌کند. برای اطلاعات بیشتر درباره این گزینه پیکربندی، به بخش نوع کاربر در مقاله راهنمای «راه‌اندازی صفحه رضایت OAuth» مراجعه کنید.
invalid_client
منشأیی که درخواست از آن ارسال شده است برای این کارخواه مجاز نیست. به
origin_mismatch مراجعه کنید.
deleted_client
کارخواه OAuth که برای درخواست استفاده می‌شود حذف شده است. حذف می‌تواند به‌صورت دستی یا به‌طور خودکار درصورت استفاده نشدن از کارخواه‌ها انجام شود. مشتریان حذف‌شده را می‌توان ظرف ۳۰ روز پس‌از حذف بازیابی کرد. بیشتر بدانید .
invalid_grant
هنگام استفاده از مجوز افزایشی، ممکن است توکن منقضی شده باشد یا نامعتبر شده باشد. کاربر را دوباره اصالت‌سنجی کنید و برای دریافت نشان‌های جدید، از کاربر بخواهید رضایت دهد. اگر همچنان این خطا را می‌بینید، مطمئن شوید که برنامه‌تان به‌درستی پیکربندی شده است و از نشان‌ها و پارامترهای صحیح در درخواستتان استفاده می‌کنید. درغیراین‌صورت، ممکن است حساب کاربر حذف یا غیرفعال شده باشد.
origin_mismatch
طرح، دامنه، و/یا درگاه JavaScript که درخواست مجوز را آغاز می‌کند ممکن است با URI مبدأ JavaScript مجاز ثبت‌شده برای شناسه کارخواه OAuth مطابقت نداشته باشد. مبدأهای مجاز جاوا اسکریپت را در صفحه کارخواه‌ها در Google Cloud Console مرور کنید.
redirect_uri_mismatch
redirect_uri ارسال‌شده در درخواست مجوز با نشانی وب هدایت مجاز برای شناسه کارخواه OAuth مطابقت ندارد. نشانی‌های وب هدایت مجاز را در
Google Cloud Console
صفحه «کارخواه‌ها» مرور کنید.
طرح، دامنه، و/یا درگاه JavaScript که درخواست مجوز را آغاز می‌کند ممکن است با URI مبدأ JavaScript مجاز ثبت‌شده برای شناسه کارخواه OAuth مطابقت نداشته باشد. مبدأهای جاوا اسکریپت مجاز را در صفحه «کارخواه‌ها» در Google Cloud Console مرور کنید.
پارامتر redirect_uri ممکن است به جریان خارج از باند OAuth (OOB) اشاره کند که
منسوخ شده است و دیگر پشتیبانی نمی‌شود. برای به‌روزرسانی ادغام، به
راهنمای انتقال مراجعه کنید.
invalid_request
مشکلی در درخواست شما وجود داشت. این مشکل ممکن است به چند دلیل باشد:
- درخواست به‌درستی قالب‌بندی نشده بود
- پارامترهای الزامی در درخواست وجود نداشت
- درخواست از روش صدور مجوزی استفاده می‌کند که Google از آن پشتیبانی نمی‌کند. تأیید کنید که ادغام OAuth شما از روش ادغام توصیه‌شده استفاده می‌کند
مرحله ۳: رسیدگی به پاسخ سرور OAuth 2.0
نقطه‌های پایانی OAuth 2.0
سرور OAuth 2.0 پاسخی به redirect_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» شما را درخواست می‌کند:
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//developers.google.com/oauthplayground& client_id=client_id
پس‌از تکمیل جریان OAuth 2.0، مرورگرتان شما را به OAuth 2.0 Playground، ابزاری برای آزمایش جریان‌های OAuth، هدایت می‌کند. خواهید دید که OAuth 2.0 Playground به‌طور خودکار کد مجوز را ضبط کرده است.
مرحله ۴: بررسی کنید کاربران کدام محدوده‌ها را اعطا کرده‌اند
هنگام درخواست چندین اجازه (محدوده)، ممکن است کاربران به برنامه شما اجازه دسترسی به همه آن‌ها را ندهند. برنامه شما باید تأیید کند که کدام دامنه‌ها واقعاً اعطا شده‌اند و موقعیت‌هایی را که برخی‌از اجازه‌ها رد شده‌اند به‌درستی مدیریت کند، معمولاً با غیرفعال کردن ویژگی‌هایی که به آن دامنه‌های ردشده متکی هستند.
بااین‌حال، چند استثنا وجود دارد. برنامه‌های Google Workspace Enterprise با واگذاری اختیارات در سراسر دامنه، یا برنامه‌هایی که به‌عنوان مورد اعتماد علامت‌گذاری شده‌اند، صفحه رضایت اجازه‌های ریزدانه را دور می‌زنند. برای این برنامه‌ها، کاربران صفحه رضایت اجازه دانه‌ای را نخواهند دید. درعوض، برنامه‌تان یا همه گستره‌های درخواست‌شده را دریافت می‌کند یا هیچ‌کدام را دریافت نمی‌کند.
برای اطلاعات دقیق‌تر، نحوه مدیریت اجازه‌های ریزدانه را ببینید.
نقطه‌های پایانی 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
نقطه‌های پایانی OAuth 2.0
پس‌از اینکه برنامه شما کد دسترسی را دریافت کرد، می‌توانید از این کد برای تماس با «میانای برنامه‌سازی کاربردی Google» ازطرف حساب کاربری معینی استفاده کنید، به‌شرطی که محدوده(های) دسترسی موردنیاز میانای برنامه‌سازی کاربردی اعطا شده باشد. برای انجام این کار،
کد دسترسی را با گنجاندن پارامتر پُرسمان access_token یا مقدار سرصفحه HTTP Authorization در درخواست به میانای برنامه‌سازی کاربردی بگنجانید.Bearer درصورت امکان،
سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در بیشتر موارد می‌توانید از کتابخانه کارخواه برای راه‌اندازی فراخوانی‌هایتان به Google APIs استفاده کنید (برای مثال، هنگام فراخوانی Drive Files API).
می‌توانید همه «میاناهای برنامه‌سازی کاربردی Google» را امتحان کنید و دامنه‌های آن‌ها را در OAuth 2.0 Playground مشاهده کنید.
مثال‌های HTTP GET
فراخوانی نقطه پایانی
drive.files (میانای برنامه‌سازی کاربردی «فایل‌های Drive») بااستفاده از سرایند Authorization: Bearer HTTP
ممکن است به‌شکل زیر باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl مثال
می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا مثالی از
گزینه سرصفحه HTTP (ترجیحی) آورده شده است:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
یا، به‌طور جایگزین، گزینه پارامتر رشته پُرسمان:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
نمونه کد جاوا اسکریپت
تکه‌کد زیر نشان می‌دهد که چگونه از CORS (هم‌رسانی منبع میان‌مبدئی) برای ارسال درخواست به Google API استفاده کنید. این مثال از «کتابخانه مشتری Google APIs برای جاوا اسکریپت» استفاده نمی‌کند. بااین‌حال، حتی اگر از کتابخانه کارخواه استفاده نمی‌کنید، راهنمای پشتیبانی 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 برای جاوا اسکریپت تکمیل کنید. این کد برای صفحه 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را دارد. - پس‌از اعطا (یا رد) دسترسی به یک یا چند دامنه درخواستی، کاربر به صفحه اصلی هدایت می‌شود که کد دسترسی را از رشته شناسه قطعه تجزیه می‌کند.
- این صفحه بررسی می‌کند که کاربر به کدام دامنه‌ها اجازه دسترسی به برنامه را داده است.
اگر کاربر دسترسی به محدوده(های) درخواستی را اعطا کرده باشد، صفحه از رمز دسترسی برای انجام درخواست نمونه API استفاده می‌کند.
درخواست میانای برنامه‌سازی کاربردی، روش
about.getمیانای برنامه‌سازی کاربردی Drive را برای بازیابی اطلاعات مربوط به حساب Google Drive کاربر مجاز فراخوانی می‌کند.- اگر درخواست باموفقیت اجرا شود، پاسخ API در کنسول اشکال‌زدایی مرورگر ثبت می‌شود.
می‌توانید دسترسی به برنامه را ازطریق صفحه اجازه‌ها برای «حساب Google» خود لغو کنید. برنامه به‌عنوان نام برنامه ارائه‌شده در صفحه نمانام‌سازی در صفحه رضایت OAuth درطول ایجاد شناسه کارخواه فهرست می‌شود.
برای اجرای این کد به‌صورت محلی، باید مقادیری را برای متغیرهای YOUR_CLIENT_ID و YOUR_REDIRECT_URI تنظیم کنید که با اعتبارنامه‌های مجوز شما مطابقت داشته باشند. متغیر YOUR_REDIRECT_URI
باید روی همان نشانی وبی تنظیم شود که صفحه در آن ارائه می‌شود. این مقدار باید دقیقاً با یکی از
URIهای هدایت مجاز برای کارخواه OAuth 2.0 که در صفحه «کارخواه‌های Cloud Console» پیکربندی کرده‌اید
مطابقت داشته باشد. اگر
این مقدار با شناسه منبع یکسان مجاز مطابقت نداشته باشد، خطای redirect_uri_mismatch
دریافت خواهید کرد. پروژه شما باید
میانای برنامه‌سازی کاربردی مناسب را برای این درخواست فعال کرده باشد.
<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 مراجعه کنید.
| قوانین اعتبارسنجی | |
|---|---|
| طرح |
مبدأهای جاوا اسکریپت باید از طرح HTTPS استفاده کنند، نه HTTP ساده. نشانی‌های وب Localhost (ازجمله نشانی‌های وب نشانی IP localhost) از این قانون مستثنا هستند. |
| میزبان |
میزبان‌ها نمی‌توانند نشانی‌های IP خام باشند. نشانی‌های IP میزبان محلی از این قانون مستثنا هستند. |
| دامنه |
“googleusercontent.com” باشد.goo.gl) باشند،
مگر اینکه برنامه مالک دامنه باشد. |
| Userinfo |
مبدأهای جاوا اسکریپت نمی‌تواند حاوی زیرمؤلفه userinfo باشد. |
| مسیر |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی مؤلفه مسیر باشند. |
| پُرسمان |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی مؤلفه پُرسمان باشند. |
| تکه |
مبدأهای جاوا اسکریپت نمی‌توانند عنصر بخش داشته باشند. |
| شخصیت‌ها |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی نویسه‌های خاصی باشند، ازجمله:
|
مجوزدهی افزایشی
در پروتکل OAuth 2.0، برنامه شما برای دسترسی به منابعی که با گستره‌ها شناسایی می‌شوند، درخواست مجوز می‌کند. بهترین روش تجربه کاربری این است که درخواست مجوز برای منابع را در زمانی که به آن‌ها نیاز دارید انجام دهید. برای فعال کردن این رویه، سرور مجوز Google از مجوز افزایشی پشتیبانی می‌کند. این ویژگی به شما امکان می‌دهد دامنه‌ها را درصورت نیاز درخواست کنید و اگر کاربر اجازه دامنه جدید را بدهد، کد تأییدی برمی‌گرداند که می‌تواند با رمز حاوی همه دامنه‌هایی که کاربر به پروژه اعطا کرده است مبادله شود.
برای مثال، برنامه‌ای که به افراد امکان می‌دهد قطعه‌های موسیقی را نمونه‌برداری کنند و میکس بسازند ممکن است در زمان ورود به سیستم به منابع بسیار کمی نیاز داشته باشد، شاید فقط نام فردی که به سیستم وارد می‌شود. بااین‌حال، ذخیره کردن ترکیب کامل‌شده مستلزم دسترسی به 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 همان تابعی است که در
مرحله ۲ ارائه شد (و بعداً در نمونه
کامل ارائه می‌شود).
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 برای جاوا اسکریپت لغو کنید. ازآنجایی‌که نقطه پایانی OAuth 2.0 متعلق به Google برای لغو کردن
توکن‌ها از «هم‌رسانی منابع میان‌مبدئی» (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
برای کسب اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربری با محافظت بین‌حسابی» مراجعه کنید.