این سند نحوه پیاده‌سازی مجوز OAuth 2.0 برای دسترسی به YouTube Data API از یک برنامه وب جاوا اسکریپت را توضیح می‌دهد. OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه‌ای هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و دیگر اطلاعاتشان را خصوصی نگه دارند. برای مثال، یک برنامه می‌تواند از OAuth 2.0 برای دریافت اجازه برای بارگذاری ویدیوها در کانال YouTube کاربر استفاده کند.
این جریان OAuth 2.0 جریان اعطای ضمنی نامیده می‌شود. این نوع برای برنامه‌هایی طراحی شده است که فقط وقتی کاربر در برنامه حضور دارد به میاناهای برنامه‌سازی کاربردی دسترسی پیدا می‌کنند. این برنامه‌ها نمی‌توانند اطلاعات محرمانه را ذخیره کنند.
در این جریان، برنامه شما نشانی وب Google را باز می‌کند که از پارامترهای پُرسمان برای شناسایی برنامه شما و نوع دسترسی به میانای برنامه‌سازی کاربردی که برنامه نیاز دارد استفاده می‌کند. می‌توانید نشانی وب را در پنجره مرورگر فعلی یا یک چارگوش باز کنید. کاربر می‌تواند با Google اصالت‌سنجی کند و اجازه‌های درخواست‌شده را اعطا کند. سپس Google کاربر را به برنامه شما هدایت می‌کند. این هدایت شامل یک کد دسترسی است که برنامه شما آن را درستی‌سنجی می‌کند و سپس از آن برای ارسال درخواست‌های API استفاده می‌کند.
کتابخانه کارخواه Google APIs و سرویس‌های مدیریت هویت Google
اگر از کتابخانه کارخواه Google APIs برای جاوا اسکریپت برای برقراری تماس‌های مجاز با Google استفاده می‌کنید، باید از کتابخانه جاوا اسکریپت سرویس‌های مدیریت هویت‌سنجی Google برای مدیریت جریان صدور مجوز استفاده کنید. قویاً توصیه می‌کنیم از مدل کد «سرویس‌های مدیریت هویت‌سنجی Google» استفاده کنید که براساس جریان کد مجوز ایمن‌تر با PKCE است.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:
- کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
- اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
- برای یافتن و فعال کردن YouTube Data API، از صفحه کتابخانه استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google APIs استفاده می‌کند باید اطلاعات اعتباری مجوز داشته باشد که برنامه را به سرور 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 |
الزامی
تعیین می‌کند که سرور API کاربر را پس‌از تکمیل جریان
مجوز به کجا هدایت کند. این مقدار باید دقیقاً با یکی از 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
نمونه نشانی وب زیر دسترسی آفلاین (access_type=offline) به دامنه‌ای را درخواست می‌کند که اجازه دسترسی برای مشاهده حساب YouTube کاربر را می‌دهد. از اصالت‌سنجی افزایشی استفاده می‌کند تا مطمئن شود
رمز دسترسی جدید همه حوزه‌هایی را که کاربر قبلاً به
برنامه اجازه دسترسی داده است پوشش می‌دهد. این نشانی وب همچنین مقادیری را برای پارامترهای الزامی
redirect_uri، response_type، و
client_id و همچنین برای پارامتر state
تنظیم می‌کند. نشانی وب برای خوانایی بیشتر حاوی شکست خط و فاصله است.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=token&
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', '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
طرح، دامنه، و/یا درگاه جاوا اسکریپت که درخواست مجوز را آغاز می‌کند ممکن است با URI مبدأ جاوا اسکریپت مجاز ثبت‌شده برای شناسه کارخواه OAuth مطابقت نداشته باشد. مبدأهای جاوا اسکریپت مجاز را در «کنسول Google Cloud» صفحه «کارخواه‌ها» مرور کنید.
redirect_uri_mismatch
redirect_uri ارسال‌شده در درخواست مجوز با نشانی وب هدایت مجاز برای شناسه کارخواه OAuth مطابقت ندارد. نشانی‌های وب هدایت مجاز را در
Google Cloud Console
صفحه «کارخواه‌ها» مرور کنید.
طرح، دامنه، و/یا درگاه جاوا اسکریپت که درخواست مجوز را آغاز می‌کند ممکن است با URI مبدأ جاوا اسکریپت مجاز ثبت‌شده برای شناسه کارخواه 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%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=token& 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 به‌صورت فهرستی از رشته‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند.
برای مثال، پاسخ نمونه کد دسترسی زیر نشان می‌دهد که کاربر به برنامه شما اجازه داده است ویدیوها، رتبه‌بندی‌ها، نظرات، و زیرنویس‌های ناشنوایان YouTube کاربر را ببیند، ویرایش کند، و برای همیشه حذف کند:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/youtube.force-ssl", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
فراخوانی میاناهای برنامه‌سازی کاربردی Google
نقطه‌های پایانی OAuth 2.0
پس‌از اینکه برنامه‌تان کد دسترسی را دریافت کرد، می‌توانید از این کد برای برقراری تماس با Google API ازطرف حساب کاربری مشخصی استفاده کنید، به‌شرطی که گستره(های) دسترسی موردنیاز API اعطا شده باشد. برای انجام این کار،
کد دسترسی را در درخواست به میانای برنامه‌سازی کاربردی با افزودن پارامتر access_token پُرسمان
یا مقدار Authorization سرصفحه HTTP Bearer اضافه کنید. درصورت امکان،
سرصفحه HTTP ترجیح داده می‌شود، زیرا رشته‌های پرسمان معمولاً در گزارش‌های سرور قابل‌مشاهده هستند. در اکثر موارد، می‌توانید از کتابخانه کارخواه برای راه‌اندازی فراخوانی‌هایتان به Google APIs استفاده کنید (برای مثال، هنگام فراخوانی YouTube Data API).
توجه داشته باشید که «میانای برنامه‌سازی کاربردی داده‌های YouTube» از حساب‌های خدماتی فقط برای مالکان محتوای YouTube که مالک و مدیر چندین کانال YouTube هستند، مانند ناشران موسیقی و استودیوهای فیلم‌سازی، پشتیبانی می‌کند.
می‌توانید همه میاناهای برنامه‌سازی کاربردی Google را امتحان کنید و دامنه‌های آنها را در OAuth 2.0 Playground مشاهده کنید.
نمونه‌های HTTP GET
فراخوانی نقطه پایانی
youtube.channels (YouTube Data API) بااستفاده از سرصفحه Authorization: Bearer HTTP
ممکن است به‌صورت زیر باشد. توجه داشته باشید که باید کد دسترسی خودتان را مشخص کنید:
GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
در اینجا فراخوانی برای همان میانای برنامه‌سازی کاربردی برای کاربر اصالت‌سنجی‌شده بااستفاده از پارامتر رشته پُرسمان access_token ارائه شده است:
GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
curl مثال
می‌توانید این فرمان‌ها را با برنامه خط فرمان curl آزمایش کنید. در اینجا مثالی از
گزینه سرصفحه HTTP (ترجیحی) آورده شده است:
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true
یا، به‌عنوان گزینه جایگزین، گزینه پارامتر رشته پُرسمان:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true
کد نمونه جاوا اسکریپت
تکه‌کد زیر نشان می‌دهد که چگونه از CORS (هم‌رسانی منبع میان‌مبدئی) برای ارسال درخواست به Google API استفاده کنید. این مثال از «کتابخانه کارخواه میاناهای برنامه‌سازی کاربردی Google» برای جاوا اسکریپت استفاده نمی‌کند. بااین‌حال، حتی اگر از کتابخانه مشتری استفاده نمی‌کنید، راهنمای پشتیبانی از CORS در مستندات آن کتابخانه احتمالاً به شما کمک می‌کند این درخواست‌ها را بهتر درک کنید.
در این تکه‌کد، متغیر access_token نشان‌دهنده رمزی است که برای درخواست‌های API ازطرف کاربر مجاز دریافت کرده‌اید. نمونه کامل نشان می‌دهد که چگونه آن توکن را در فضای ذخیره‌سازی محلی مرورگر ذخیره کنید و آن را هنگام درخواست API بازیابی کنید.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/youtube/v3/channels?part=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را درخواست می‌کند. - پس‌از اعطای (یا رد کردن) دسترسی به یک یا چند حوزه درخواست‌شده، کاربر به صفحه اصلی هدایت می‌شود که نشانه دسترسی را از رشته شناسه تکه‌تکه تجزیه می‌کند.
- این صفحه بررسی می‌کند که کاربر به کدام دامنه‌ها اجازه دسترسی به برنامه را داده است.
اگر کاربر به دامنه(های) درخواستی دسترسی داده باشد، صفحه از کد دسترسی برای ایجاد درخواست نمونه API استفاده می‌کند.
این درخواست API، روش
channels.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']) {
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/v3/channels?part=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 {
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',
'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» خود استفاده کنند.
در این حالت، در زمان ورود به سیستم، برنامه ممکن است به هیچ دامنه‌ای نیاز نداشته باشد یا درخواست دسترسی به آن را نکند. بااین‌حال، اگر کاربر سعی کند ویدیویی را رده‌بندی کند، ویدیویی را به
فهرست پخش اضافه کند، یا اقدام دیگری در YouTube انجام دهد، برنامه می‌تواند دسترسی به
دامنه https://www.googleapis.com/auth/youtube.force-ssl را درخواست کند.
به‌طور مشابه، اگر کاربر بخواهد رویداد تقویم اضافه کند، برنامه می‌تواند درخواست دسترسی به دامنه https://www.googleapis.com/auth/calendar را بدهد.
قوانین زیر برای یک کد دسترسی که از یک مجوز افزایشی به‌دست آمده است، اعمال می‌شود:
- از این کد می‌توان برای دسترسی به منابع مربوط به هریک از محدوده‌هایی که در مجوز ترکیبی جدید ادغام شده‌اند استفاده کرد.
- وقتی از ژتون بازآوری برای مجوز ترکیبی جهت دریافت کد دسترسی استفاده می‌کنید، کد دسترسی نشان‌دهنده مجوز ترکیبی است و می‌تواند برای هریک از مقادیر
scopeموجود در پاسخ استفاده شود. - مجوز ترکیبی شامل همه محدوده‌هایی است که کاربر به پروژه API اعطا کرده است، حتی اگر اعطاها از کارخواه‌های مختلف درخواست شده باشند. برای مثال، اگر کاربری بااستفاده از کلاینت رایانه برنامه به یک حوزه دسترسی اعطا کند و سپس حوزه دیگری را ازطریق کلاینت تلفن همراه به همان برنامه اعطا کند، مجوز ترکیبی شامل هر دو حوزه خواهد بود.
- اگر نشانهای را که نشان‌دهنده مجوز ترکیبی است باطل کنید، دسترسی به همه حوزه‌های آن مجوز ازطرف کاربر مرتبط به‌طور هم‌زمان باطل می‌شود.
نمونه‌های کد زیر نحوه افزودن گستره به کد دسترسی موجود را نشان می‌دهد. این رویکرد به برنامه شما امکان می‌دهد از مدیریت چندین کد دسترسی اجتناب کند.
نقطه‌های پایانی OAuth 2.0
در این مثال، برنامه فراخواننده علاوه‌بر دسترسی‌های دیگری که کاربر قبلاً به برنامه اعطا کرده است، درخواست دسترسی برای بازیابی داده‌های YouTube Analytics کاربر را دارد.
برای افزودن دامنه به کد دسترسی موجود، پارامتر 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
برای کسب اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربری با محافظت بین‌حسابی» مراجعه کنید.