این سند نحوه پیاده‌سازی مجوز OAuth 2.0 برای دسترسی به YouTube Data API از یک برنامه وب جاوا اسکریپت را توضیح می‌دهد. OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و سایر اطلاعاتشان را خصوصی نگه دارند. برای مثال، یک برنامه می‌تواند از OAuth 2.0 برای دریافت اجازه برای بازیابی داده‌های YouTube یک کانال استفاده کند.
این جریان OAuth 2.0 جریان اعطای ضمنی نامیده می‌شود. این نوع برای برنامه‌هایی طراحی شده است که فقط وقتی کاربر در برنامه حضور دارد به میاناهای برنامه‌سازی کاربردی دسترسی پیدا می‌کنند. این برنامه‌ها نمی‌توانند اطلاعات محرمانه را ذخیره کنند.
در این جریان، برنامه شما نشانی وب Google را باز می‌کند که از پارامترهای پُرسمان برای شناسایی برنامه شما و نوع دسترسی به API که برنامه نیاز دارد استفاده می‌کند. می‌توانید نشانی وب را در پنجره مرورگر فعلی یا کادر گفتگویی باز کنید. کاربر می‌تواند با Google اصالت‌سنجی کند و اجازه‌های درخواستی را اعطا کند. سپس Google کاربر را به برنامه شما هدایت می‌کند. این هدایت شامل یک کد دسترسی است که برنامه شما آن را درستی‌سنجی می‌کند و سپس از آن برای ارسال درخواست‌های API استفاده می‌کند.
کتابخانه کارخواه Google APIs و سرویس‌های مدیریت هویت Google
اگر از کتابخانه کارخواه Google APIs برای جاوا اسکریپت برای برقراری تماس‌های مجاز با Google استفاده می‌کنید، باید از کتابخانه جاوا اسکریپت سرویس‌های مدیریت هویت‌سنجی Google برای مدیریت جریان صدور مجوز استفاده کنید. قویاً توصیه می‌کنیم از مدل کد «سرویس‌های مدیریت هویت‌سنجی Google» استفاده کنید که براساس جریان کد مجوز ایمن‌تر با PKCE است.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه:
- کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
- اگر از شما درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی بسازید.
- از صفحه «کتابخانه» برای پیدا کردن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده می‌کند پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه‌های مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوز داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبارنامه برای پروژه‌تان را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه کارخواهان بروید.
- روی ایجاد کارخواه کلیک کنید.
- نوع برنامه برنامه وب را انتخاب کنید.
- فرم را تکمیل کنید. برنامه‌هایی که از جاوا اسکریپت برای ایجاد درخواست‌های مجاز Google API استفاده می‌کنند باید مبدأهای جاوا اسکریپت مجاز را مشخص کنند. مبدأها دامنه‌هایی را شناسایی می‌کنند که برنامه‌تان می‌تواند از آنها درخواست به سرور OAuth 2.0 ارسال کند. این مبدأها باید از قوانین اعتبارسنجی Google پیروی کنند.
شناسایی محدوده‌های دسترسی
گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد درخواست دسترسی دهد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما اعطا می‌کنند کنترل کنند. بنابراین، ممکن است بین تعداد گستره‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود داشته باشد.
قبل‌از شروع پیاده‌سازی مجوز OAuth 2.0، توصیه می‌کنیم دامنه‌هایی را که برنامه‌تان برای دسترسی به آنها نیاز به اجازه دارد شناسایی کنید.
YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
| دامنه | توضیحات |
|---|---|
https://www. googleapis. com/ auth/ youtube | حساب YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtube. channel-memberships. creator | فهرستی از اعضای فعال فعلی کانال خود، سطح فعلی آنها و زمان عضویت آنها را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. force-ssl | ویدیوها، رتبه‌بندی‌ها، نظرات و زیرنویس‌های YouTube خود را مشاهده، ویرایش و برای همیشه حذف کنید |
https://www. googleapis. com/ auth/ youtube. readonly | حساب YouTube خود را مشاهده کنید |
https://www. googleapis. com/ auth/ youtube. upload | ویدیوهای YouTube خود را مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner | دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید |
https://www. googleapis. com/ auth/ youtubepartner-channel-audit | اطلاعات خصوصی مربوط به کانال YouTube خود را در طول فرآیند ممیزی با شریک YouTube مشاهده کنید |
سند 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 به کاربر نمایش می‌دهد اطلاع می‌دهد. گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی داشته باشد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، بین تعداد محدوده‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود دارد. YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
سند OAuth 2.0 API Scopes فهرست کاملی از دامنه‌هایی که ممکن است برای دسترسی به Google APIs استفاده کنید ارائه می‌دهد. توصیه می‌کنیم برنامه‌تان درصورت امکان، دسترسی به گستره‌های مجوز را در بافت درخواست کند. با درخواست دسترسی به داده‌های کاربر در بافت، بااستفاده از مجوز فزاینده، به کاربران کمک می‌کنید متوجه شوند چرا برنامه‌تان به دسترسی‌ای که درخواست می‌کند نیاز دارد. |
||||||||||||||||
state |
توصیه‌شده
هر مقدار رشته‌ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می‌کند، مشخص می‌کند.
سرور مقدار دقیقی را که به‌عنوان جفت می‌توانید از این پارامتر برای اهداف مختلفی استفاده کنید، مثلاً هدایت کاربر به منبع صحیح در برنامه، ارسال اعداد یک‌بارمصرف، و کاهش جعل درخواست بین‌سایتی. ازآنجایی‌که |
||||||||||||||||
include_granted_scopes |
اختیاری
به برنامه‌ها امکان می‌دهد از صدور مجوز افزایشی برای درخواست دسترسی به
حوزه‌های اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی |
||||||||||||||||
enable_granular_consent |
اختیاری
پیش‌فرض وقتی Google اجازه‌های دقیق را برای برنامه‌ای فعال می‌کند، این پارامتر دیگر هیچ تأثیری نخواهد داشت. |
||||||||||||||||
login_hint |
اختیاری
اگر برنامه شما می‌داند کدام کاربر درحال تلاش برای اصالت‌سنجی است، می‌تواند از این پارامتر برای ارائه راهنمایی به «سرور اصالت‌سنجی Google» استفاده کند. سرور از این اشاره برای ساده کردن جریان ورود به سیستم استفاده می‌کند، یا با ازپیش پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه ورود به سیستم چندگانه مناسب. مقدار پارامتر را روی نشانی ایمیل یا شناسه |
||||||||||||||||
prompt |
اختیاری
فهرست پیام‌واره‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند و به کاربر ارائه می‌شود. اگر این پارامتر را مشخص نکنید، فقط اولین باری که پروژه شما درخواست دسترسی می‌کند، از کاربر درخواست خواهد شد. برای اطلاعات بیشتر، درخواست رضایت مجدد را ببینید. مقادیر ممکن عبارت‌اند از:
|
||||||||||||||||
نمونه هدایت به سرور مجوز Google
نمونه نشانی وب در زیر نشان داده شده است، با شکست خط و فاصله برای خوانایی. نشانی وب درخواست دسترسی به دامنه‌ای را دارد که اجازه دسترسی به بازیابی داده‌های YouTube کاربر را می‌دهد. این روش از مجوز افزایشی (include_granted_scopes=true) استفاده می‌کند تا اطمینان حاصل شود که کد دسترسی جدید هر دامنه‌ای را که کاربر قبلاً به برنامه دسترسی داده است، پوشش می‌دهد. چند پارامتر دیگر نیز در این مثال تنظیم شده است.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& 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/youtube.force-ssl 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 مشخص‌شده در درخواست
رمز دسترسی شما ارسال می‌کند.
اگر کاربر درخواست را تأیید کند، پاسخ حاوی کد دسترسی خواهد بود. اگر کاربر درخواست را تأیید نکند، پاسخ حاوی پیام خطا خواهد بود. کد دسترسی یا پیام خطا در قطعه درهم‌سازی 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%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& 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/youtube.force-ssl https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
فراخوانی میاناهای برنامه‌سازی کاربردی Google
نقطه‌های پایانی OAuth 2.0
پس‌از اینکه برنامه‌تان کد دسترسی را دریافت کرد، می‌توانید از این کد برای برقراری تماس با Google API ازطرف حساب کاربری مشخصی استفاده کنید، به‌شرطی که گستره(های) دسترسی موردنیاز API اعطا شده باشد. برای انجام این کار،
کد دسترسی را در درخواست به میانای برنامه‌سازی کاربردی با افزودن پارامتر access_token پُرسمان
یا مقدار Authorization سرصفحه HTTP Bearer اضافه کنید. درصورت امکان،
سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در اکثر موارد می‌توانید از کتابخانه کارخواه برای تنظیم تماس‌های خود با «میاناهای برنامه‌سازی کاربردی Google» استفاده کنید (برای مثال، هنگام فراخوانی «میانای برنامه‌سازی کاربردی جاری‌سازی زنده YouTube»).
توجه داشته باشید که YouTube Live Streaming API از جریان حساب سرویس پشتیبانی نمی‌کند. ازآنجایی‌که راهی برای پیوند دادن «حساب سرویس» به حساب YouTube وجود ندارد، تلاش برای صدور مجوز درخواست‌ها با این جریان، خطای NoLinkedYouTubeAccount را ایجاد می‌کند.
می‌توانید همه میاناهای برنامه‌سازی کاربردی Google را امتحان کنید و دامنه‌های آنها را در OAuth 2.0 Playground مشاهده کنید.
نمونه‌های HTTP GET
فراخوانی نقطه پایانی
liveBroadcasts.list (YouTube Live Streaming API) بااستفاده از سرصفحه Authorization: Bearer HTTP
ممکن است به‌صورت زیر باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:
GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:
GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
curl مثال
می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا
نمونه‌ای آورده شده است که از گزینه سرصفحه HTTP (ترجیحی) استفاده می‌کند:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true
یا، به‌طور جایگزین، گزینه پارامتر رشته پُرسمان:
curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true
کد نمونه جاوا اسکریپت
تکه‌کد زیر نشان می‌دهد که چگونه از CORS (هم‌رسانی منبع میان‌مبدئی) برای ارسال درخواست به Google API استفاده کنید. این مثال از «کتابخانه مشتری Google APIs برای جاوا اسکریپت» استفاده نمی‌کند. بااین‌حال، حتی اگر از کتابخانه کارخواه استفاده نمی‌کنید، راهنمای پشتیبانی CORS در اسناد آن کتابخانه احتمالاً به شما کمک می‌کند تا این درخواست‌ها را بهتر درک کنید.
در این تکه‌کد، متغیر access_token نشان‌دهنده توکنی است که برای درخواست‌های API ازطرف کاربر مجاز دریافت کرده‌اید. نمونه کامل نشان می‌دهد که چگونه آن توکن را در فضای ذخیره‌سازی محلی مرورگر ذخیره کنید و آن را هنگام درخواست API بازیابی کنید.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' + '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/youtube.force-sslوhttps://www.googleapis.com/auth/calendar.readonlyمحدوده‌ها را درخواست می‌کند. - پس‌از اعطا (یا رد) دسترسی به یک یا چند دامنه درخواستی، کاربر به صفحه اصلی هدایت می‌شود که کد دسترسی را از رشته شناسه قطعه تجزیه می‌کند.
- این صفحه بررسی می‌کند که کاربر به کدام محدوده‌ها دسترسی به برنامه را اعطا کرده است.
اگر کاربر به دامنه(های) درخواستی دسترسی داده باشد، صفحه از کد دسترسی برای ایجاد درخواست نمونه API استفاده می‌کند.
این درخواست API متد
liveBroadcasts.listدر YouTube Data API را برای بازیابی فهرست پخش‌های زنده ویدیو برای کانال YouTube کاربر مجاز فرا می‌خواند.- اگر درخواست باموفقیت اجرا شود، پاسخ میانای برنامه‌سازی کاربردی در کنسول اشکال‌زدایی مرورگر ثبت می‌شود.
می‌توانید دسترسی به برنامه را ازطریق صفحه اجازه‌ها برای «حساب 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/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
'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/youtube.force-ssl 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 ساده. URIهای Localhost (ازجمله URIهای نشانی IP در localhost) از این قانون مستثنی هستند. |
| میزبان |
میزبان‌ها نمی‌توانند نشانی‌های IP خام باشند. نشانی‌های IP میزبان محلی از این قانون مستثنا هستند. |
| دامنه |
“googleusercontent.com” باشد.goo.gl) باشند،
مگر اینکه برنامه مالک دامنه باشد. |
| Userinfo |
مبدأهای جاوا اسکریپت نمی‌تواند حاوی زیرمؤلفه userinfo باشد. |
| مسیر |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی مؤلفه مسیر باشند. |
| پُرسمان |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی مؤلفه پُرسمان باشند. |
| تکه |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی مؤلفه قطعه باشند. |
| شخصیت‌ها |
مبدأهای جاوا اسکریپت نمی‌توانند حاوی نویسه‌های خاصی باشند، ازجمله:
|
مجوز افزایشی
در پروتکل OAuth 2.0، برنامه شما برای دسترسی به منابعی که با گستره‌ها شناسایی می‌شوند، درخواست مجوز می‌کند. بهترین روش تجربه کاربری این است که درخواست مجوز برای منابع را در زمانی که به آنها نیاز دارید انجام دهید. برای فعال کردن این رویه، سرور مجوز Google از مجوز افزایشی پشتیبانی می‌کند. این ویژگی به شما امکان می‌دهد تا دامنه‌ها را درصورت نیاز درخواست کنید و، اگر کاربر اجازه را برای دامنه جدید اعطا کند، یک کد مجوز برمی‌گرداند که ممکن است با یک کد حاوی همه دامنه‌هایی که کاربر به پروژه اعطا کرده است مبادله شود.
برای مثال، فرض کنید برنامه‌ای داده‌های کانال YouTube کاربر اصیل‌سازی‌شده را بازیابی می‌کند و همچنین
به کاربر امکان می‌دهد داده‌های YouTube Analytics را ازطریق یک جریان ویژه بازیابی کند. در این حالت، هنگام ورود به سیستم، برنامه ممکن است فقط برای https://www.googleapis.com/auth/youtube.force-ssl
دامنه درخواست دسترسی کند. بااین‌حال، اگر کاربر سعی کند به داده‌های Analytics برای کانال خود دسترسی پیدا کند، برنامه می‌تواند دسترسی به محدوده https://www.googleapis.com/auth/yt-analytics.readonly را نیز درخواست کند.
قوانین زیر برای کد دسترسی به‌دست‌آمده از مجوز افزایشی اعمال می‌شود:
- از این کد می‌توان برای دسترسی به منابع مربوط به هریک از محدوده‌هایی که در مجوز ترکیبی جدید ادغام شده‌اند استفاده کرد.
- وقتی از ژتون بازآوری برای مجوز ترکیبی جهت دریافت کد دسترسی استفاده می‌کنید، کد دسترسی نشان‌دهنده مجوز ترکیبی است و می‌تواند برای هریک از مقادیر
scopeموجود در پاسخ استفاده شود. - مجوز ترکیبی شامل همه دامنه‌هایی است که کاربر به پروژه میانای برنامه‌سازی کاربردی اعطا کرده است، حتی اگر این اعطاها از کارخواه‌های مختلف درخواست شده باشد. برای مثال، اگر کاربری بااستفاده از کلاینت رایانه برنامه به یک حوزه دسترسی اعطا کند و سپس حوزه دیگری را ازطریق کلاینت تلفن همراه به همان برنامه اعطا کند، مجوز ترکیبی شامل هر دو حوزه خواهد بود.
- اگر نشانه‌ای را که نشان‌دهنده مجوز ترکیبی است باطل کنید، دسترسی به همه حوزه‌های آن مجوز ازطرف کاربر مرتبط به‌طور هم‌زمان باطل می‌شود.
نمونه‌های کد زیر نحوه افزودن گستره به کد دسترسی موجود را نشان می‌دهد. این رویکرد به برنامه شما امکان می‌دهد از مدیریت چندین کد دسترسی اجتناب کند.
نقطه‌های پایانی OAuth 2.0
در این مثال، برنامه تماس‌گیرنده درخواست دسترسی برای بازیابی داده‌های YouTube کاربر را علاوه بر هر دسترسی دیگری که کاربر قبلاً به برنامه اعطا کرده است دارد.
برای افزودن دامنه به کد دسترسی موجود، پارامتر include_granted_scopes را در درخواستتان به سرور OAuth 2.0 در Google اضافه کنید.
تکه‌کد زیر نحوه انجام این کار را نشان می‌دهد. این قطعه کد فرض می‌کند که شما
دامنه‌هایی را که کد دسترسی شما برای آنها معتبر است در فضای ذخیره‌سازی محلی مرورگر ذخیره کرده‌اید. (کد
مثال کامل فهرستی از محدوده‌هایی را که
نشان دسترسی برای آنها معتبر است با تنظیم کردن دارایی oauth2-test-params.scope در فضای ذخیره‌سازی محلی
مرورگر ذخیره می‌کند.)
این گزیده، دامنه‌هایی را که کد دسترسی برای آنها معتبر است با دامنه‌ای که می‌خواهید برای پُرسمان خاصی استفاده کنید مقایسه می‌کند. اگر کد دسترسی آن محدوده را پوشش ندهد، جریان OAuth 2.0 شروع می‌شود.
در اینجا، تابع oauth2SignIn همان تابعی است که در
مرحله ۲ ارائه شد (و بعداً در نمونه
کامل ارائه می‌شود).
var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl'; 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
برای اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربر با «محافظت بین‌حسابی»» مراجعه کنید.