این سند توضیح می‌دهد که چگونه برنامه‌های نصب‌شده روی دستگاه‌هایی مانند تلفن، تبلت و رایانه از نقاط پایانی OAuth 2.0 Google برای مجاز کردن دسترسی به YouTube Data API استفاده می‌کنند.
OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و سایر اطلاعات خود را خصوصی نگه دارند. برای مثال، یک برنامه می‌تواند از OAuth 2.0 برای دریافت اجازه جهت بازیابی داده‌های YouTube یک کانال استفاده کند.
برنامه‌های نصب‌شده در دستگاه‌های شخصی توزیع می‌شوند و فرض بر این است که این برنامه‌ها نمی‌توانند اسرار را حفظ کنند. این برنامه‌ها می‌توانند وقتی کاربر در برنامه حضور دارد یا وقتی برنامه در پس‌زمینه اجرا می‌شود به Google APIs دسترسی داشته باشند.
این جریان مجوزدهی مشابه جریانی است که برای برنامه‌های سرور وب استفاده می‌شود. تفاوت اصلی این است که برنامه‌های نصب‌شده باید مرورگر سیستم را باز کنند و یک نشانی وب هدایت محلی برای مدیریت پاسخ‌های سرور مجوز Google ارائه دهند.
کتابخانه‌ها و نمونه‌ها
برای برنامه‌های iOS، توصیه می‌کنیم از جدیدترین نسخه کیت توسعه نرم‌افزار iOS «ورود به سیستم با Google» استفاده کنید. کیت توسعه نرم‌افزار مجوز کاربر را مدیریت می‌کند و پیاده‌سازی آن ساده‌تر از پروتکل سطح پایین‌تر شرح‌داده‌شده در این راهنما است.
برای برنامه‌هایی که در دستگاه‌هایی اجرا می‌شوند که از مرورگر سیستم پشتیبانی نمی‌کنند یا قابلیت‌های ورودی محدودی دارند، مانند تلویزیون‌ها، کنسول‌های بازی، دوربین‌ها، یا چاپگرها، به OAuth 2.0 برای تلویزیون‌ها و دستگاه‌ها یا ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود مراجعه کنید.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه:
- کتابخانه میانای برنامه‌سازی کاربردی را در «کنسول Google API» باز کنید.
- اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
- از صفحه «کتابخانه» برای پیدا کردن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوز داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبارنامه برای پروژه‌تان را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه کارخواهان بروید.
- روی ایجاد مشتری کلیک کنید.
- بخش‌های زیر انواع کارخواهی را که سرور مجوز Google پشتیبانی می‌کند شرح می‌دهد. نوع کاربری را که برای برنامه‌تان توصیه می‌شود انتخاب کنید، نام کاربری OAuth خود را بگذارید، و فیلدهای دیگر فرم را به‌صورت مناسب تنظیم کنید.
iOS
- نوع برنامه iOS را انتخاب کنید.
- نامی برای کارخواه OAuth وارد کنید. این نام در صفحه «کارخواهان» پروژه شما برای شناسایی کارخواه نمایش داده می‌شود.
- شناسه دسته‌ای برنامه‌تان را وارد کنید. شناسه دسته مقدار کلید
CFBundleIdentifier
در فایل منبع فهرست دارایی اطلاعات برنامه (info.plist) است. این مقدار معمولاً در قاب «عمومی» یا قاب «امضا و قابلیت‌ها» در
ویرایشگر پروژه Xcode نمایش داده می‌شود. شناسه دسته نرم‌افزاری در بخش «اطلاعات کلی»
صفحه «اطلاعات برنامه» برای برنامه در
سایت Apple App Store Connect نیز نمایش داده می‌شود.
تأیید کنید که از شناسه دسته‌ای صحیح برای برنامه‌تان استفاده می‌کنید، زیرا اگر از ویژگی «بررسی برنامه» استفاده می‌کنید نمی‌توانید آن را تغییر دهید.
- (اختیاری)
اگر برنامه در Apple App Store منتشر شده است، شناسه App Store برنامه‌تان را وارد کنید. «شناسه فروشگاه» رشته‌ای عددی است که در هر نشانی وب Apple App Store گنجانده شده است.
- برنامه Apple App Store را در دستگاه iOS یا iPadOS خود باز کنید.
- برنامه‌تان را جستجو کنید.
- دکمه «هم‌رسانی» (نماد مربع و پیکان رو به بالا) را انتخاب کنید.
- کپی کردن پیوند را انتخاب کنید.
- پیوند را در ویرایشگر نوشتار جای‌گذاری کنید. شناسه App Store بخش نهایی نشانی وب است.
مثال:
https://apps.apple.com/app/google/id284815942
- (اختیاری)
«شناسه تیم» خود را وارد کنید. برای اطلاعات بیشتر، مکان «شناسه تیم» را در اسناد «حساب توسعه‌دهنده Apple» ببینید.
توجه: اگر «بررسی برنامه» را برای کارخواهتان فعال می‌کنید، فیلد «شناسه تیم» الزامی است. - (اختیاری)
«بررسی برنامه» را برای برنامه iOS خود فعال کنید. وقتی «بررسی برنامه» را فعال می‌کنید، از سرویس App Attest Apple برای تأیید اینکه درخواست‌های OAuth 2.0 که از کارخواه OAuth شما منشأ می‌گیرند واقعی هستند و از برنامه شما می‌آیند استفاده می‌شود. این کار به کاهش خطر جعل هویت برنامه کمک می‌کند. درباره فعال کردن «بررسی برنامه» برای برنامه iOS خود بیشتر بدانید.
- روی ایجاد کردن کلیک کنید.
UWP
- نوع برنامه پلاتفرم جهانی Windows را انتخاب کنید.
- نامی برای کارخواه OAuth وارد کنید. این نام در پروژه‌تان نمایش داده می‌شود تا کارخواه را شناسایی کند.
- شناسه ۱۲ نویسه‌ای Microsoft Store برنامه‌تان را وارد کنید. این مقدار را می‌توانید در مرکز شریک Microsoft در صفحه هویت برنامه در بخش «مدیریت برنامه» پیدا کنید.
- روی ایجاد کردن کلیک کنید.
برای برنامه‌های UWP، شناسه منبع یکسان تغییرمسیر بااستفاده از «شناسه امنیتی بسته» (SID) منحصربه‌فرد برنامه‌تان تشکیل می‌شود. می‌توانید Package SID برنامه‌تان را در فایل Package.appxmanifest در پروژه Visual Studio پیدا کنید.
وقتی شناسه کارخواه خود را در کنسول Google Cloud ایجاد می‌کنید، باید شناسه «URI هدایت» را با قالب زیر و بااستفاده از مقدار حروف کوچک «شناسه امن بسته» خود مشخص کنید:
ms-app://YOUR_APP_PACKAGE_SID
برای برنامه‌های UWP، طرح‌واره URI سفارشی نمی‌تواند بیشتر از ۳۹ نویسه باشد، همان‌طور که در اسناد Microsoft مشخص شده است.
شناسایی محدوده‌های دسترسی
محدوده‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی پیدا کند و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، ممکن است بین تعداد دامنه‌های درخواستی و احتمال دریافت رضایت کاربر رابطه معکوس وجود داشته باشد.
قبل‌از شروع پیاده‌سازی مجوز 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 که به مجوز کاربر نیاز دارد، این رضایت را داشته باشد.
مرحله ۱: تولید کد درستی‌سنجی و چالش
Google از پروتکل کلید اثبات برای مبادله کد (PKCE) برای ایمن‌تر کردن جریان برنامه نصب‌شده پشتیبانی می‌کند. برای هر درخواست مجوز، یک کد درستی‌سنجی منحصربه‌فرد ایجاد می‌شود و مقدار تبدیل‌شده آن که «code_challenge» نامیده می‌شود، برای دریافت کد مجوز به سرور مجوز ارسال می‌شود.
ایجاد کردن کد درستی‌سنجی
code_verifier یک رشته تصادفی رمزنگاری با آنتروپی بالا است که از نویسه‌های غیررزروشده
[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" استفاده می‌کند و حداقل طول آن ۴۳ نویسه
و حداکثر طول آن ۱۲۸ نویسه است.
درستی‌سنج کد باید آنتروپی کافی داشته باشد تا حدس زدن مقدار آن غیرممکن شود.
ایجاد چالش کد
دو روش برای ایجاد چالش کد پشتیبانی می‌شود.
| روش‌های تولید چالش کد | |
|---|---|
| S256 (توصیه‌شده) | چالش کد، درهم‌سازی SHA256 کدبندی‌شده Base64URL (بدون لایه‌گذاری) از تأییدکننده کد است.
|
| ساده | چالش کد همان مقدار درستی‌سنج کد تولیدشده در بالا است.
|
مرحله ۲: ارسال درخواست به سرور OAuth 2.0 در Google
برای دریافت مجوز کاربر، درخواستی به سرور مجوز Google در
https://accounts.google.com/o/oauth2/v2/auth ارسال کنید. این نقطه پایانی جستجوی جلسه فعال را مدیریت می‌کند،
کاربر را اصالت‌سنجی می‌کند، و رضایت کاربر را دریافت می‌کند. نقطه پایان فقط ازطریق SSL قابل‌دسترس است و
اتصال‌های HTTP (غیر SSL) را نمی‌پذیرد.
سرور مجوز از پارامترهای رشته پُرسمان زیر برای برنامه‌های نصب‌شده پشتیبانی می‌کند: برنامه‌ها:
| پارامترها | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
الزامی
شناسه کارخواه برای برنامه شما. می‌توانید این مقدار را در صفحه «کارخواه‌ها» در «کنسول Cloud» پیدا کنید. |
||||||||||||||||
redirect_uri |
الزامی
تعیین می‌کند که سرور مجوز Google چگونه پاسخی به برنامه شما ارسال کند. چندین گزینه تغییرمسیر برای برنامه‌های نصب‌شده دردسترس است و شما باید اعتبارنامه‌های مجوز خود را با روش تغییرمسیر خاصی در ذهن تنظیم کنید. این مقدار باید دقیقاً با یکی از URIهای هدایت مجاز برای کارخواه OAuth 2.0 که در صفحه کارخواه‌ها در Cloud Console کارخواه پیکربندی کرده‌اید مطابقت داشته باشد. اگر این مقدار با شناسه منبع یکسان مجاز مطابقت نداشته باشد، خطای جدول زیر مقدار پارامتر
|
||||||||||||||||
response_type |
الزامی
تعیین می‌کند که آیا نقطه پایان Google OAuth 2.0 کد مجوز برمی‌گرداند یا نه. مقدار پارامتر را برای برنامه‌های نصب‌شده روی |
||||||||||||||||
scope |
الزامی
فهرستی از حوزه‌ها که با فاصله از هم جدا شده‌اند و منابعی را که برنامه شما می‌تواند ازطرف کاربر به آنها دسترسی داشته باشد شناسایی می‌کند. این مقادیر به صفحه موافقت که Google به کاربر نمایش می‌دهد اطلاع می‌دهد. گستره‌ها به برنامه شما امکان می‌دهند فقط به منابعی که نیاز دارد دسترسی داشته باشد و درعین‌حال به کاربران امکان می‌دهند میزان دسترسی‌ای را که به برنامه شما می‌دهند کنترل کنند. بنابراین، رابطه‌ای معکوس بین تعداد دامنه‌های درخواستی و احتمال کسب رضایت کاربر وجود دارد. YouTube Data API v3 از دامنه‌های زیر استفاده می‌کند:
سند OAuth 2.0 API Scopes فهرست کاملی از دامنه‌هایی را که ممکن است برای دسترسی به Google APIs استفاده کنید ارائه می‌دهد. |
||||||||||||||||
code_challenge |
توصیه‌شده
|
||||||||||||||||
code_challenge_method |
توصیه‌شده
مشخص می‌کند از چه روشی برای کدبندی |
||||||||||||||||
state |
توصیه‌شده
هر مقدار رشته‌ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می‌کند، مشخص می‌کند.
سرور مقدار دقیقی را که به‌عنوان جفت می‌توانید از این پارامتر برای اهداف مختلفی استفاده کنید، ازجمله هدایت کاربر به
منبع صحیح در برنامه‌تان، ارسال نانس، و کاهش جعل درخواست
بین‌سایتی. ازآنجایی‌که |
||||||||||||||||
login_hint |
اختیاری
اگر برنامه شما می‌داند کدام کاربر درحال تلاش برای اصالت‌سنجی است، می‌تواند از این پارامتر برای ارائه راهنمایی به «سرور اصالت‌سنجی Google» استفاده کند. سرور از این اشاره برای ساده کردن جریان ورود به سیستم استفاده می‌کند، یا با ازپیش پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه ورود به سیستم چندگانه مناسب. مقدار پارامتر را روی نشانی ایمیل یا شناسه |
||||||||||||||||
نشانی‌های وب مجوز نمونه
برگه‌های زیر نشانی‌های وب نمونه‌ای از مجوز برای گزینه‌های مختلف «شناسه URI هدایت» را نشان می‌دهد.
هر نشانی وب دسترسی به دامنه‌ای را درخواست می‌کند که اجازه دسترسی به بازیابی داده‌های YouTube کاربر را می‌دهد.نشانی‌های وب به‌جز مقدار پارامتر redirect_uri یکسان هستند. نشانی‌های وب
همچنین حاوی پارامترهای الزامی response_type و client_id و
پارامتر اختیاری state هستند. هر نشانی وب حاوی شکست خط و فاصله برای خوانایی است.
طرح‌واره URI سفارشی
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
نشانی IP مسیریابی بازگشتی
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
مرحله ۳: 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» مراجعه کنید.
deleted_client
کارخواه OAuth که برای درخواست استفاده می‌شود حذف شده است. حذف می‌تواند به‌صورت دستی یا به‌طور خودکار درصورت استفاده نشدن از کارخواه‌ها انجام شود. کاربران حذف‌شده را می‌توانید ظرف ۳۰ روز پس‌از حذف بازیابی کنید. بیشتر بدانید .
invalid_grant
اگر از
درستی‌سنج کد و
چالش استفاده می‌کنید، پارامتر code_callenge نامعتبر است یا وجود ندارد. مطمئن شوید که پارامتر
code_challenge به‌درستی تنظیم شده باشد.
هنگام بازآوری کد دسترسی، ممکن است کد منقضی شده باشد یا نامعتبر شده باشد. کاربر را دوباره اصالت‌سنجی کنید و برای دریافت نشانهای جدید، از کاربر بخواهید رضایت دهد. اگر همچنان این خطا را می‌بینید، مطمئن شوید که برنامه‌تان به‌درستی پیکربندی شده است و از نشان‌ها و پارامترهای صحیح در درخواستتان استفاده می‌کنید. درغیراین‌صورت، ممکن است حساب کاربر حذف یا غیرفعال شده باشد.
redirect_uri_mismatch
redirect_uri ارسال‌شده در درخواست مجوز با نشانی وب هدایت مجاز برای شناسه کارخواه OAuth مطابقت ندارد. نشانی‌های وب هدایت مجاز را در
Google Cloud Console
صفحه «کارخواه‌ها» مرور کنید.
redirect_uri ارسال‌شده ممکن است برای نوع کارخواه نامعتبر باشد.
پارامتر redirect_uri ممکن است به جریان خارج از باند OAuth (OOB) اشاره کند که
منسوخ شده است و دیگر پشتیبانی نمی‌شود. برای به‌روزرسانی یکپارچه‌سازی خود، به
راهنمای انتقال مراجعه کنید.
invalid_request
در درخواستی که ارائه کردید مشکلی وجود داشت. این مشکل ممکن است به چند دلیل باشد:
- درخواست به‌درستی قالب‌بندی نشده است
- پارامترهای الزامی در درخواست وجود نداشت
- درخواست از روش صدور مجوزی استفاده می‌کند که Google از آن پشتیبانی نمی‌کند. به‌تأیید رساندن اینکه یکپارچه‌سازی OAuth شما از روش یکپارچه‌سازی توصیه‌شده استفاده می‌کند
- از طرح سفارشی پشتیبانی‌نشده‌ای برای شناسه منبع یکسان تغییرمسیر استفاده شده است. اگر پیام خطای طرح‌واره URI سفارشی در برنامه‌های Android یا Chrome پشتیبانی نمی‌شود را می‌بینید، درباره جایگزین‌های طرح‌واره URI سفارشی بیشتر بدانید.
مرحله ۴: رسیدگی به پاسخ سرور OAuth 2.0
روشی که برنامه شما پاسخ مجوز را دریافت می‌کند به
طرح‌واره URI تغییرمسیر که استفاده می‌کند بستگی دارد. صرف‌نظر از طرح، پاسخ حاوی کد مجوز (code) یا خطا (error) خواهد بود. برای مثال، error=access_denied نشان می‌دهد که کاربر درخواست را رد کرده است.
اگر کاربر به برنامه شما دسترسی دهد، می‌توانید کد مجوز را با کد دسترسی و کد بازآوری همان‌طور که در مرحله بعد توضیح داده شده است معاوضه کنید.
مرحله ۵: معاوضه کد مجوز با ژتون‌های بازآوری و دسترسی
برای معاوضه کد مجوز با کد دسترسی، نقطه پایانی https://oauth2.googleapis.com/token را فراخوانی کنید و پارامترهای زیر را تنظیم کنید:
| فیلدها | |
|---|---|
client_id |
شناسه کارخواه به‌دست‌آمده از صفحه کارخواه‌ها در «کنسول Cloud». |
client_secret |
اختیاری
رمز کارخواه به‌دست‌آمده از صفحه کارخواه‌ها در «کنسول Cloud». |
code |
کد مجوز برگشت‌داده‌شده از درخواست اولیه. |
code_verifier |
در مرحله ۱، کد درستی‌سنجی ایجاد کردید. |
grant_type |
همان‌طور که در مشخصات OAuth 2.0
تعریف شده است، مقدار این فیلد باید روی authorization_code تنظیم شود. |
redirect_uri |
یکی از URIهای هدایت فهرست‌شده برای پروژه‌تان در
صفحه کارخواه‌ها در Cloud Console
برای
client_id داده‌شده. |
هرچند استفاده از DPoP اختیاری است، اما برای افزایش امنیت توصیه می‌شود. امنیت DPoP به محدود شدن کلید خصوصی به یک دستگاه واحد بستگی دارد؛ توصیه می‌کنیم آن را به‌گونه‌ای ذخیره کنید که نتوان آن را از دستگاه کپی کرد، برای مثال بااستفاده از TPM، Secure Enclaves، یا سایر محل‌های ذخیره کلید با پشتیبانی سخت‌افزار. برای استفاده از DPoP، برنامه شما باید برای هر درخواست به نقطه پایانی توکن، یک JWT اثبات DPoP جدید و منحصربه‌فرد تولید کند و آن را به‌عنوان سرصفحه درخواست HTTP اضافه کند.
| سرایند | الزامی | شرح |
|---|---|---|
DPoP |
اختیاری | اثبات DPoP یک JWT است که مالکیت کلید خصوصی را اثبات می‌کند. این سرصفحه است، نه پارامتر. درصورت ارائه، نشانهای برگردانده‌شده
به این کلید محدود می‌شوند. برای هر درخواست باید مدرک جدید و منحصربه‌فردی تولید شود و
باید شامل ادعاهای htm (روش HTTP) و htu (نشانی وب HTTP) باشد که
با درخواست مطابقت داشته باشد. |
تکه زیر یک درخواست نمونه را نشان می‌دهد:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
ساختن اثبات DPoP
مراحل زیر نحوه ساختن گواه DPoP بااستفاده از OpenSSL از خط فرمان را نشان می‌دهد:
- تولید جفت کلید EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- ایجاد سرایند DPoP:
سرایند باید شامل ادعاهای
typ،alg، وjwk(کلید عمومی) باشد. مقادیرxوyمختصات کدبندی‌شده Base64Url کلید عمومی EC شما هستند. این JSON را با Base64Url کدبندی کنید:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - ایجاد بار داده DPoP:
بار داده باید شامل
jti(شناسه یکتا برای درخواست)،htm(روش HTTP، مثلاًPOST)،htu(HTTP URI، مثلاًhttps://oauth2.googleapis.com/token)، وiat(زمان صدور) باشد. اگر در پاسخ به درخواست قبلی، یک nonce از سرور در سرصفحهDPoP-Nonceدریافت کردید، باید آن مقدار nonce را در ادعایnonceاضافه کنید. ادعای nonce برای تبادل کد مجوز اختیاری است و فقط زمانی استفاده می‌شود که سرایند DPoP-Nonce قبلاً دریافت شده باشد. این JSON را با Base64Url کدبندی کنید:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }مقدار
jtiبه نوع مبادله بستگی دارد:- برای تبادل کد مجوز،
jtiباید درهم‌سازی SHA256 کد مجوز باشد که با Base64Url کدبندی شده است:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - برای تبادل‌های کد نوسازی،
jtiباید یک شناسه یکتای هر درخواست باشد:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- برای تبادل کد مجوز،
- امضای مدرک:
سرصفحه و بار داده کدگذاری‌شده را با نقطه (
.) به‌هم متصل کنید، سپس نتیجه را با کلید خصوصی‌تان بااستفاده از ES256 امضا کنید. توجه داشته باشید که JWS الزام می‌کند که امضا در قالب خامR | Sبه‌هم‌پیوسته باشد (۶۴ بایت برای P-256). اگر مستقیماً از OpenSSL استفاده می‌کنید، باید امضای پیش‌فرض ASN.1 DER-encoded را به این قالب خام تبدیل کنید.
تبادل موفق با پاسخ 200 OK حاوی کدها نشان داده می‌شود. اگر درطول تبادل از اثبات DPoP معتبری استفاده شود، کد بازآوری که Google برمی‌گرداند به کلید شما محدود به DPoP خواهد بود، اما کدهای دسترسی محدود به DPoP نخواهند بود. رمزهای دسترسی token_type مربوط به
Bearer را به‌جای DPoP حفظ خواهند کرد.
علاوه‌براین، Google سرایند DPoP-Nonce HTTP را در پاسخ برمی‌گرداند.
کارخواه شما باید این عدد یک‌بارمصرف را ذخیره کند و آن را در ادعای nonce اثبات DPoP
در درخواست‌های بعدی (مانند هنگام تبادل یک کد بازآوری برای یک کد دسترسی جدید، یا هنگام
فراخوانی میاناهای برنامه‌سازی کاربردی محافظت‌شده با DPoP) قرار دهد. بااستفاده از این عدد یک‌بارمصرف صادرشده زودهنگام، می‌توانید از خطای رفت‌وبرگشت اضافی (use_dpop_nonce) در درخواست بعدی‌تان جلوگیری کنید.
برای درخواست‌های تبادل ژتون که با ژتون‌های بازآوری محدودشده با DPoP انجام می‌شود، باید اثبات‌های DPoP اضافه شود.
اگر سرایند DPoP در زمان موردانتظار وجود نداشته باشد، نامعتبر باشد، یا اگر مدرک از کلیدی متفاوت با کلید محدودشده به کد استفاده کند، تبادل ناموفق رخ می‌دهد. در این موارد، سرور خطای
400 Bad Request را برمی‌گرداند.
اگر مدرک DPoP ادعاهای htm یا htu ناهماهنگ، iat منقضی، jti مجدداً استفاده‌شده، یا امضای نامعتبر داشته باشد، Google کد خطای invalid_dpop_proof برمی‌گرداند.
اگر یک DPoP nonce لازم باشد، مثلاً درطول تبادل ژتون بازآوری، و اثبات DPoP فاقد ادعای nonce باشد، یا مقدار nonce برای سرور غیرقابل‌قبول باشد (مثلاً منقضی شده باشد، قبلاً استفاده شده باشد، یا نادرست باشد)، Google کد خطای use_dpop_nonce را به‌همراه سرصفحه HTTP DPoP-Nonce حاوی یک nonce جدید برمی‌گرداند که می‌توانید در درخواست بعدی استفاده کنید.
خطاهای دیگر ممکن است invalid_grant را برگردانند.
Google با برگرداندن یک شیء JSON که حاوی یک کد دسترسی کوتاه‌مدت و یک کد نوسازی است به این درخواست پاسخ می‌دهد.
پاسخ حاوی فیلدهای زیر است:
| فیلدها | |
|---|---|
access_token |
نشانهای که برنامه شما برای صدور مجوز درخواست Google API ارسال می‌کند. |
expires_in |
طول عمر باقی‌مانده کد دسترسی برحسب ثانیه. |
id_token |
توجه: این دارایی فقط درصورتی برگردانده می‌شود که درخواست شما شامل محدوده هویت باشد،
مثل openid، profile، یا email. این مقدار یک
«نشان وب JSON» (JWT) است که حاوی اطلاعات هویت امضاشده دیجیتالی درباره
کاربر است. |
refresh_token |
کدی که می‌توانید از آن برای دریافت کد دسترسی جدید استفاده کنید. ژتون‌های بازآوری تا زمانی معتبر هستند که کاربر دسترسی را لغو کند یا ژتون بازآوری منقضی شود. اگر از DPoP استفاده شده باشد، ژتون بازآوری به کلید خصوصی استفاده‌شده برای امضای اثبات DPoP محدود می‌شود. توجه داشته باشید که ژتون‌های بازآوری همیشه برای برنامه‌های نصب‌شده برگردانده می‌شوند. |
refresh_token_expires_in |
طول عمر باقی‌مانده ژتون بازآوری برحسب ثانیه. این مقدار فقط زمانی تنظیم می‌شود که کاربر دسترسی زمان‌دار اعطا کند. |
scope |
دامنه‌های دسترسی اعطاشده توسط access_token به‌صورت فهرستی از
رشته‌های حساس به حروف بزرگ و کوچک که با فاصله از هم جدا شده‌اند بیان می‌شود. |
token_type |
نوع کد برگردانده‌شده. این مقدار همیشه Bearer است، حتی وقتی از DPoP استفاده می‌شود. |
تکه‌کد زیر نمونه‌ای از سرایندها و متن پاسخ موفقیت‌آمیز را هنگام استفاده از DPoP نشان می‌دهد:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"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 Workspace Enterprise با واگذاری اختیارات در سراسر دامنه، یا برنامه‌هایی که به‌عنوان مورد اعتماد علامت‌گذاری شده‌اند، صفحه رضایت اجازه‌های ریزدانه را دور می‌زنند. برای این برنامه‌ها، کاربران صفحه رضایت اجازه دانه‌ای را نخواهند دید. درعوض، برنامه شما یا همه محدوده‌های درخواستی را دریافت خواهد کرد یا هیچ‌کدام را دریافت نخواهد کرد.
برای اطلاعات دقیق‌تر، نحوه مدیریت اجازه‌های ریزدانه را ببینید.
برای بررسی اینکه آیا کاربر به برنامه شما اجازه دسترسی به دامنه خاصی را داده است یا نه،
فیلد 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
پس‌از اینکه برنامه شما کد دسترسی را دریافت کرد، می‌توانید از این کد برای تماس با «میانای برنامه‌سازی کاربردی Google» ازطرف حساب کاربری معینی استفاده کنید، به‌شرطی که محدوده(های) دسترسی موردنیاز میانای برنامه‌سازی کاربردی اعطا شده باشد. برای انجام این کار،
کد دسترسی را با گنجاندن پارامتر پُرسمان access_token یا مقدار سرصفحه HTTP Authorization در درخواست به میانای برنامه‌سازی کاربردی بگنجانید.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
در اینجا فراخوانی به همان API برای کاربر اصیل بااستفاده از پارامتر رشته پُرسمان 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
بازآوری کد دسترسی
رمزهای دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای درخواست API مربوطه اعتبارنامه نامعتبر می‌شوند. اگر دسترسی آفلاین به دامنه‌های مرتبط با کد دسترسی را درخواست کرده باشید، می‌توانید کد دسترسی را بدون درخواست اجازه از کاربر (ازجمله زمانی که کاربر حضور ندارد) بازآوری کنید.
برای بازآوری کردن یک کد دسترسی، برنامه شما یک درخواست HTTPS POST
به سرور مجوز Google (https://oauth2.googleapis.com/token) ارسال می‌کند که
شامل پارامترهای زیر در بدنه درخواست است:
| نام | مقدار |
|---|---|
client_id |
شناسه مشتری به‌دست‌آمده از کنسول API. |
client_secret |
اختیاری
رمز کارخواه دریافت‌شده از کنسول API.
( |
grant_type |
همان‌طور که
در
مشخصات OAuth 2.0 تعریف شده است،
مقدار این فیلد باید روی refresh_token تنظیم شود. |
refresh_token |
نمودار بازآوری برگشتی از تبادل کد مجوز. |
هرچند استفاده از DPoP اختیاری است، اما برای افزایش امنیت توصیه می‌شود. برای استفاده از DPoP با ژتون بازآوری، برنامه شما باید برای هر درخواست به نقطه پایانی ژتون، یک JWT اثبات DPoP جدید و منحصربه‌فرد تولید کند. این مدرک باید با همان کلید خصوصی‌ای امضا شود که درطول تبادل اولیه کد مجوز استفاده شده است. برنامه شما مدرک را به‌عنوان سرصفحه درخواست HTTP اضافه می‌کند.
| سرایند | الزامی | شرح |
|---|---|---|
DPoP |
اختیاری | اثبات DPoP یک JWT است که
مالکیت کلید خصوصی را اثبات می‌کند. این سرصفحه است، نه پارامتر. درصورت ارائه، نشانهای برگردانده‌شده
به این کلید محدود می‌شوند. برای هر درخواست باید مدرک جدید و منحصربه‌فردی تولید شود و باید شامل ادعاهای htm (روش HTTP) و htu (شناسه منبع یکسان HTTP) باشد که با درخواست مطابقت داشته باشد. |
تکه زیر یک درخواست نمونه را نشان می‌دهد:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
برای استفاده از DPoP با کد بازآوری، باید یک مدرک DPoP جدید و منحصربه‌فرد JWT برای درخواست تولید کنید. برای دستورالعمل‌های گام‌به‌گام درباره تولید جفت کلید و ساختن JWT، به ساختن اثبات DPoP مراجعه کنید.
تبادل موفق با پاسخ 200 OK
حاوی کد دسترسی جدید نشان داده می‌شود. وقتی از DPoP استفاده می‌شود،
token_type Bearer است. پاسخ موفقیت‌آمیز تأیید می‌کند که
اثبات DPoP برای ژتون بازآوری پذیرفته شده است. Google همچنین ممکن است سرصفحه HTTP جدید DPoP-Nonce را در پاسخ برگرداند؛ درصورت برگردانده شدن، کارخواه شما باید این nonce را در حافظه نهان ذخیره کند و آن را در ادعای nonce اثبات DPoP در درخواست‌های بعدی لحاظ کند.
اگر سرایند DPoP وجود نداشته باشد، نامعتبر باشد، یا از کلید نادرستی استفاده کند، تبادل ناموفق رخ می‌دهد. برای جزئیات مربوط به کدهای خطای خاص DPoP و مدیریت نانس‌ها، به تبادل ناموفق مراجعه کنید.
تکه‌کد زیر نمونه‌ای از سرایندها و متن پاسخ موفقیت‌آمیز را هنگام استفاده از DPoP نشان می‌دهد:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}توجه داشته باشید که تعداد ژتون‌های بازآوری که صادر می‌شود محدود است؛ یک محدودیت برای هر ترکیب مشتری/کاربر، و محدودیت دیگر برای هر کاربر در همه مشتری‌ها. باید کدهای بازآوری را در فضای ذخیره‌سازی بلندمدت ذخیره کنید و تا زمانی که معتبر هستند از آنها استفاده کنید. اگر برنامه شما توکن‌های بازآوری زیادی درخواست کند، ممکن است با این محدودیت‌ها مواجه شود، در این صورت توکن‌های بازآوری قدیمی‌تر ازکار خواهند افتاد.
ابطال کد
در برخی موارد، ممکن است کاربر بخواهد دسترسی اعطاشده به برنامه‌ای را لغو کند. کاربر می‌تواند با مراجعه به تنظیمات حساب دسترسی را لغو کند. برای اطلاعات بیشتر، بخش برداشتن دسترسی سایت یا برنامه در سند پشتیبانی «برنامه‌ها و سایت‌های طرف سوم با امکان دسترسی به حساب شما» را ببینید.
همچنین این امکان وجود دارد که برنامه به‌صورت برنامه‌نویسی‌شده دسترسی اعطاشده به آن را لغو کند. لغو برنامه‌ای در مواردی که کاربر اشتراک را لغو می‌کند، برنامه‌ای را برمی‌دارد، یا منابع API موردنیاز برنامه به‌طور قابل‌توجهی تغییر کرده است مهم است. به‌عبارت دیگر، بخشی از فرایند برداشتن می‌تواند شامل درخواست API برای اطمینان از برداشته شدن اجازه‌هایی باشد که قبلاً به برنامه اعطا شده است.
برای لغو کردن توکن به‌صورت برنامه‌نویسی‌شده، برنامه شما درخواستی به
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 همراه با کد خطا برگردانده می‌شود.
روش‌های هدایت برنامه
طرح‌واره URI سفارشی
طرح‌های سفارشی URI نوعی پیوند عمیق هستند که از طرح سفارشی برای باز کردن برنامه شما استفاده می‌کنند.
جایگزین استفاده از طرح‌واره‌های URI سفارشی در برنامه‌های Chrome
از Chrome Identity API استفاده کنید که پاسخ OAuth 2.0 را مستقیماً به برنامه‌تان ارسال می‌کند و نیاز به URI تغییرمسیر را ازبین می‌برد.
نشانی IP حلقه برگشتی (macOS، Linux، رایانه Windows)
برای دریافت کد مجوز بااستفاده از این نشانی وب، برنامه‌تان باید در سرور وب محلی درحال گوش دادن باشد. این کار در بسیاری از پلاتفرم‌ها امکان‌پذیر است، اما نه در همه آنها. بااین‌حال، اگر پلاتفرم شما از آن پشتیبانی می‌کند، این سازوکار توصیه‌شده برای دریافت کد مجوز است.
وقتی برنامه‌تان پاسخ مجوز را دریافت می‌کند، برای بهترین قابلیت استفاده، باید با نمایش صفحه HTML که به کاربر دستور می‌دهد مرورگر را ببندد و به برنامه‌تان برگردد پاسخ دهد.
| استفاده توصیه‌شده | برنامه‌های رایانه‌ای macOS، Linux، و Windows (اما نه «پلاتفرم جهانی Windows») |
| مقادیر فرم | نوع برنامه را روی برنامه رایانه‌ای تنظیم کنید. |
کپی/جای‌گذاری دستی (منسوخ‌شده)
از برنامه‌هایتان محافظت کنید
تأیید مالکیت برنامه برای Chrome
می‌توانید مالکیت برنامه‌تان را به‌تأیید برسانید تا خطر جعل برنامه را کاهش دهید.
برای تکمیل فرایند درستی‌سنجی، از حساب «توسعه‌دهنده نت‌بازار Chrome» خود استفاده می‌کنید. برای درستی‌سنجی موفقیت‌آمیز، باید شرایط زیر برآورده شود:
- باید موردی ثبت‌شده در داشبورد توسعه‌دهندگان «نت‌بازار Chrome» با همان شناسه مورد مشتری OAuth «افزونه Chrome» که درستی‌سنجی را برای آن تکمیل می‌کنید داشته باشید.
- باید ناشر مورد «نت‌بازار Chrome» باشید. درباره مدیریت دسترسی در «داشبورد توسعه‌دهندگان نت‌بازار Chrome» بیشتر بدانید.
در بخش درستی‌سنجی مالکیت برنامه در کارخواه «افزونه Chrome»، روی دکمه درستی‌سنجی مالکیت کلیک کنید تا فرایند درستی‌سنجی تکمیل شود.
توجه: پس‌از اعطای دسترسی به حسابتان، چند دقیقه صبر کنید و سپس فرایند درستی‌سنجی را تکمیل کنید.
اگر درستی‌سنجی موفقیت‌آمیز باشد، اعلانی برای تأیید موفقیت‌آمیز بودن فرایند درستی‌سنجی نمایش داده می‌شود. درغیراین‌صورت، پیام‌واره خطا نشان داده خواهد شد.
برای رفع مشکل درستی‌سنجی ناموفق، موارد زیر را امتحان کنید:
- مطمئن شوید موردی ثبت‌شده در «داشبورد توسعه‌دهندگان نت‌بازار Chrome» وجود دارد که شناسه موردی یکسان با کارخواه OAuth افزونه Chrome دارد که درحال تکمیل درستی‌سنجی برای آن هستید.
- مطمئن شوید که ناشر برنامه هستید، یعنی باید ناشر فردی برنامه یا عضو ناشر گروهی برنامه باشید. بیشتر بدانید درباره مدیریت دسترسی در «داشبورد توسعه‌دهندگان نت‌بازار Chrome».
- اگر به‌تازگی فهرست ناشر گروه را به‌روز کرده‌اید، بررسی کنید که فهرست عضویت ناشر گروه در «داشبورد توسعه‌دهندگان نت‌بازار Chrome» همگام‌سازی شده باشد. درباره همگام‌سازی فهرست عضویت ناشر خود بیشتر بدانید.
بررسی برنامه (فقط iOS)
ویژگی بررسی برنامه بااستفاده از سرویس گواهی برنامه Apple به محافظت از برنامه‌های iOS شما دربرابر استفاده غیرمجاز کمک می‌کند تا درستی‌سنجی کند درخواست‌های ارسالی به نقاط پایانی Google OAuth 2.0 از برنامه‌های معتبر شما منشأ می‌گیرند. این کار به کاهش خطر جعل هویت برنامه کمک می‌کند.
فعال کردن «بررسی برنامه» برای مشتری iOS
برای فعال کردن موفقیت‌آمیز «بررسی برنامه» برای مشتری iOS، باید الزامات زیر برآورده شود:- باید شناسه تیمی برای کارخواه iOS خود مشخص کنید.
- نباید از نویسه عام در شناسه دسته نرم‌افزاری‌تان استفاده کنید زیرا می‌تواند به بیش‌از یک برنامه ارجاع دهد. یعنی شناسه دسته نرم‌افزاری نباید شامل نماد ستاره (*) باشد.
پس‌از فعال کردن «بررسی برنامه»، در نمای ویرایش کارخواه OAuth، سنجه‌های مربوط به درخواست‌های OAuth را از کارخواهتان خواهید دید. تا زمانی که «بررسی برنامه» را اعمال نکنید، درخواست‌های منابع درستی‌سنجی‌نشده مسدود نخواهند شد. اطلاعات موجود در صفحه پایش سنجه‌ها می‌تواند به شما کمک کند تا زمان شروع اجرای قانون را تعیین کنید.
هنگام فعال کردن «بررسی برنامه» برای برنامه iOS، ممکن است خطاهای مربوط به ویژگی «بررسی برنامه» را ببینید. برای رفع این خطاها، موارد زیر را امتحان کنید:
- بررسی کنید شناسه دسته نرم‌افزاری و شناسه تیمی که مشخص کرده‌اید معتبر باشد.
- مطمئن شوید که از نویسه عام برای شناسه دسته نرم‌افزاری استفاده نمی‌کنید.
اجرای «بررسی برنامه» برای مشتری iOS
فعال کردن «بررسی برنامه» برای برنامه‌تان به‌طور خودکار درخواست‌های ناشناخته را مسدود نمی‌کند. برای اعمال کردن این محافظت، به نمای ویرایش کلاینت iOS بروید. در آنجا، سنجه‌های «بررسی برنامه» را در سمت چپ صفحه در بخش هویت Google برای iOS خواهید دید. این سنجه‌ها شامل اطلاعات زیر است:- تعداد درخواست‌های درستی‌سنجی‌شده - درخواست‌هایی که دارای یک کد App Check معتبر هستند. پس‌از اینکه اجرای «بررسی برنامه» را فعال کردید، فقط درخواست‌های این دسته موفق خواهند بود.
- تعداد درخواست‌های درستی‌سنجی‌نشده: احتمالاً درخواست‌های کارخواه قدیمی - درخواست‌های فاقد رمز App Check؛ این درخواست‌ها ممکن است از نسخه قدیمی‌تر برنامه‌تان باشد که فاقد پیاده‌سازی App Check است.
- تعداد درخواست‌های تأییدنشده: درخواست‌های با منبع ناشناخته - درخواست‌هایی که فاقد کد App Check هستند و به‌نظر نمی‌رسد از برنامه شما ارسال شده باشند.
- تعداد درخواست‌های درستی‌سنجی‌نشده: درخواست‌های نامعتبر - درخواست‌هایی با یک کد App Check نامعتبر، که ممکن است از یک کارخواه غیرمعتبر باشد که تلاش می‌کند خود را به‌جای برنامه شما جا بزند، یا از محیط‌های شبیه‌سازی‌شده باشد.
برای اعمال «بررسی برنامه»، روی دکمه ENFORCE کلیک کنید و انتخابتان را تأیید کنید. وقتی اجرا فعال باشد، همه درخواست‌های تأییدنشده از مشتری شما رد خواهد شد.
توجه: پس‌از فعال کردن اجرای سیاست، ممکن است تا ۱۵ دقیقه طول بکشد تا تغییرات اعمال شود.
لغو اجرای «بررسی برنامه» برای مشتری iOS شما
لغو اجرای «بررسی برنامه» برای برنامه‌تان، اجرا را متوقف خواهد کرد و به همه درخواست‌های سرویس‌گیرنده شما به نقاط پایانی Google OAuth 2.0، ازجمله درخواست‌های تأییدنشده، اجازه خواهد داد.
برای لغو اجرای «بررسی برنامه» برای کارخواه iOS، به نمای ویرایش کارخواه iOS بروید و روی دکمه لغو اجرا کلیک کنید و انتخابتان را تأیید کنید.
توجه: پس‌از لغو اجرای «بررسی برنامه»، ممکن است تا ۱۵ دقیقه طول بکشد تا تغییرات اعمال شود.
غیرفعال کردن «بررسی برنامه» برای «کارخواه iOS»
درصورت غیرفعال کردن «بررسی برنامه» برای برنامه‌تان، همه پایش و اجرای «بررسی برنامه» متوقف خواهد شد. به‌جای آن، App Check را غیرفعال کنید تا بتوانید به نظارت بر سنجه‌های کارخواهتان ادامه دهید.
برای غیرفعال کردن «بررسی برنامه» برای کارخواه iOS، به نمای ویرایش کارخواه iOS پیمایش کنید و دکمه محافظت از کارخواه OAuth دربرابر سوءاستفاده با «بررسی برنامه Firebase» را خاموش کنید.
توجه: پس‌از غیرفعال کردن App Check، ممکن است تا ۱۵ دقیقه طول بکشد تا تغییرات اعمال شود.
دسترسی زمان‌محور
دسترسی زمان‌محور به کاربر اجازه می‌دهد برای مدت محدودی به برنامه شما اجازه دسترسی به داده‌هایش را بدهد تا کنشی را تکمیل کند. دسترسی زمان‌محور در محصولات منتخب Google درطول جریان رضایت دردسترس است و به کاربران این امکان را می‌دهد که دسترسی را برای مدت محدودی اعطا کنند. یک نمونه از این ابزارها Data Portability API است که امکان انتقال یک‌باره داده‌ها را فراهم می‌کند.
وقتی کاربری به برنامه شما دسترسی زمان‌دار اعطا می‌کند، ژتون بازآوری پس‌از مدت مشخص‌شده منقضی می‌شود. توجه داشته باشید که ممکن است نشانهای بازآوری تحت شرایط خاص زودتر نامعتبر شوند؛ برای جزئیات بیشتر، این موارد را ببینید. فیلد refresh_token_expires_in که در پاسخ
تبادل کد مجوز برگردانده می‌شود، در این موارد نشان‌دهنده زمان باقی‌مانده تا انقضای ژتون بازآوری است.
مطالعه بیشتر
«روال مطلوب فعلی IETF» OAuth 2.0 برای برنامه‌های بومی بسیاری از روال‌های مطلوب مستندشده در اینجا را ایجاد می‌کند.
پیاده‌سازی «محافظت بین‌حسابی»
یکی از اقدامات تکمیلی که باید برای محافظت از حساب‌های کاربران خود انجام دهید، پیاده‌سازی «محافظت بین‌حسابی» بااستفاده از «سرویس محافظت بین‌حسابی» 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
برای اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربر با «محافظت بین‌حسابی»» مراجعه کنید.