این سند توضیح می‌دهد که چگونه برنامه‌های نصب‌شده روی دستگاه‌هایی مانند تلفن، رایانه لوحی، و رایانه از نقاط پایانی Google OAuth 2.0 برای مجاز کردن دسترسی به YouTube Data API استفاده می‌کنند.
OAuth 2.0 به کاربران اجازه می‌دهد داده‌های خاصی را با برنامه‌ای هم‌رسانی کنند و درعین‌حال نام‌های کاربری، گذرواژه‌ها، و اطلاعات دیگرشان را خصوصی نگه دارند. برای مثال، یک برنامه می‌تواند از OAuth 2.0 برای دریافت اجازه بارگذاری ویدیو در کانال YouTube کاربر استفاده کند.
برنامه‌های نصب‌شده در دستگاه‌های جداگانه توزیع می‌شوند و فرض بر این است که این برنامه‌ها نمی‌توانند اسرار را حفظ کنند. این برنامه‌ها می‌توانند وقتی کاربر در برنامه حضور دارد یا وقتی برنامه در پس‌زمینه اجرا می‌شود به Google APIs دسترسی داشته باشند.
این جریان مجوز مشابه جریانی است که برای برنامه‌های سرور وب استفاده می‌شود. تفاوت اصلی این است که برنامه‌های نصب‌شده باید مرورگر سیستم را باز کنند و یک نشانی وب هدایت محلی برای مدیریت پاسخ‌های سرور مجوز Google ارائه دهند.
کتابخانه‌ها و نمونه‌ها
برای برنامه‌های iOS، توصیه می‌کنیم از جدیدترین نسخه کیت توسعه نرم‌افزار iOS «ورود به سیستم با Google» استفاده کنید. کیت توسعه نرم‌افزار مجوز کاربر را مدیریت می‌کند و پیاده‌سازی آن ساده‌تر از پروتکل سطح پایین‌تر شرح‌داده‌شده در این راهنما است.
برای برنامه‌هایی که در دستگاه‌هایی اجرا می‌شوند که از مرورگر سیستم پشتیبانی نمی‌کنند یا قابلیت‌های ورودی محدودی دارند، مانند تلویزیون‌ها، کنسول‌های بازی، دوربین‌ها یا چاپگرها، به OAuth 2.0 برای تلویزیون‌ها و دستگاه‌ها یا ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود مراجعه کنید.
پیش‌نیازها
فعال کردن میاناهای برنامه‌سازی کاربردی برای پروژه
هر برنامه‌ای که میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند باید آن میاناهای برنامه‌سازی کاربردی را در «کنسول میانای برنامه‌سازی کاربردی» فعال کند.
برای فعال کردن میانای برنامه‌سازی کاربردی برای پروژه‌تان:
- در «کنسول Google API»، کتابخانه API را باز کنید.
- اگر درخواست شد، پروژه‌ای را انتخاب کنید یا پروژه جدیدی ایجاد کنید.
- از صفحه کتابخانه برای پیدا کردن و فعال کردن YouTube Data API استفاده کنید. هر API دیگری را که برنامه‌تان استفاده خواهد کرد پیدا کنید و آنها را نیز فعال کنید.
ایجاد اعتبارنامه مجوز
هر برنامه‌ای که از OAuth 2.0 برای دسترسی به Google API استفاده می‌کند باید اعتبارنامه مجوز داشته باشد که برنامه را برای سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اطلاعات اعتباری برای پروژه شما را توضیح می‌دهد. سپس برنامه‌هایتان می‌توانند از این اطلاعات اعتباری برای دسترسی به میاناهای برنامه‌سازی کاربردی‌ای که برای آن پروژه فعال کرده‌اید استفاده کنند.
- به صفحه کارخواهان بروید.
- روی ایجاد کارخواه کلیک کنید.
- بخش‌های زیر انواع کارخواهی را که سرور مجوز Google پشتیبانی می‌کند شرح می‌دهد. نوع کارخواهی را که برای برنامه‌تان توصیه می‌شود انتخاب کنید، نام کارخواه OAuth را وارد کنید، و فیلدهای دیگر را در فرم به‌طور مناسب تنظیم کنید.
iOS
- نوع برنامه iOS را انتخاب کنید.
- نامی برای کارخواه OAuth وارد کنید. این نام در صفحه «کارخواهان» پروژه شما برای شناسایی کارخواه نمایش داده می‌شود.
- شناسه دسته نرم‌افزاری را برای برنامه‌تان وارد کنید. شناسه دسته نرم‌افزاری مقدار کلید
CFBundleIdentifier
در فایل منبع فهرست ویژگی اطلاعات برنامه‌تان (info.plist) است. این مقدار
معمولاً در قاب General یا قاب Signing & Capabilities در
ویرایشگر پروژه Xcode نمایش داده می‌شود. شناسه دسته‌بندی همچنین در بخش «اطلاعات کلی» صفحه «اطلاعات برنامه» برای برنامه در
سایت Apple's 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 (بدون لایه‌گذاری) از تأییدکننده کد است.
|
| plain | چالش کد همان مقدار تأییدکننده کد است که در بالا تولید شده است.
|
مرحله ۲: ارسال درخواست به سرور 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.readonly& 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.readonly& 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 Console صفحه کارخواه‌ها. |
client_secret |
اختیاری
رمز کارخواه به‌دست‌آمده از صفحه کارخواه‌ها در «کنسول Cloud». |
code |
کد مجوز برگشت‌داده‌شده از درخواست اولیه. |
code_verifier |
کد درستی‌سنجی که در مرحله ۱ ایجاد کردید. |
grant_type |
همان‌طور که در مشخصات OAuth 2.0 تعریف شده است، مقدار این فیلد باید روی authorization_code تنظیم شود. |
redirect_uri |
یکی از URIهای هدایت فهرست‌شده برای پروژه‌تان در
صفحه کارخواه‌ها در Cloud Console
برای
client_id داده‌شده. |
هرچند استفاده از DPoP اختیاری است، اما برای افزایش امنیت توصیه می‌شود. امنیت DPoP به محدود بودن کلید خصوصی به یک دستگاه بستگی دارد؛ توصیه می‌کنیم آن را به‌گونه‌ای ذخیره کنید که نتوان آن را از دستگاه کپی کرد، مثلاً بااستفاده از TPM، Secure Enclave، یا دیگر محل‌های ذخیره کلید با پشتیبانی سخت‌افزاری. برای استفاده از 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 را به این قالب خام تبدیل کنید.
تبادل موفق با پاسخ 200 OK
حاوی نشان‌ها مشخص می‌شود. اگر درطول تبادل از اثبات DPoP معتبری استفاده شود، کد بازآوری که Google برمی‌گرداند به کلید شما محدود به DPoP خواهد بود، اما کدهای دسترسی محدود به DPoP نخواهند بود. کدهای دسترسی به‌جای DPoP، token_type مربوط به Bearer را حفظ خواهند کرد.
علاوه‌براین، Google سرصفحه HTTP DPoP-Nonce را در پاسخ برمی‌گرداند.
کارخواه شما باید این عدد یک‌بارمصرف را ذخیره کند و آن را در ادعای 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 Web Token (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",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}مرحله ۶: بررسی کردن گستره‌هایی که کاربران اعطا کرده‌اند
هنگام درخواست چندین اجازه (محدوده)، ممکن است کاربران به برنامه شما اجازه دسترسی به همه آنها را ندهند. برنامه شما باید بررسی کند که کدام محدوده‌ها واقعاً اعطا شده‌اند و در شرایطی که برخی‌از اجازه‌ها رد می‌شوند، به‌طور مناسب عمل کند، معمولاً با غیرفعال کردن ویژگی‌هایی که به آن محدوده‌های ردشده متکی هستند.
بااین‌حال، چند استثنا وجود دارد. برنامه‌های Google Workspace Enterprise با واگذاری اختیارات در سراسر دامنه، یا برنامه‌هایی که به‌عنوان مورد اعتماد علامت‌گذاری شده‌اند، صفحه رضایت اجازه‌های ریزدانه را دور می‌زنند. برای این برنامه‌ها، کاربران صفحه موافقت با اجازه جزئی را نخواهند دید. درعوض، برنامه شما یا همه محدوده‌های درخواستی را دریافت خواهد کرد یا هیچ‌کدام را دریافت نخواهد کرد.
برای اطلاعات دقیق‌تر، نحوه مدیریت اجازه‌های ریزدانه را ببینید.
برای بررسی اینکه آیا کاربر به برنامه شما اجازه دسترسی به دامنه خاصی را داده است یا نه،
فیلد 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 APIs
پس‌از اینکه برنامه شما کد دسترسی را دریافت کرد، می‌توانید از این کد برای تماس با «میانای برنامه‌سازی کاربردی Google» ازطرف حساب کاربری معینی استفاده کنید، به‌شرطی که محدوده(های) دسترسی موردنیاز میانای برنامه‌سازی کاربردی اعطا شده باشد. برای انجام این کار،
کد دسترسی را در درخواست به میانای برنامه‌سازی کاربردی با افزودن پارامتر 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
در اینجا فراخوانی به همان API برای کاربر اصیل بااستفاده از پارامتر رشته پُرسمان 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
بازآوری کد دسترسی
رمزهای دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای درخواست 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 با ژتون بازآوری، باید JWT اثبات DPoP جدید و منحصربه‌فردی برای درخواست تولید کنید. برای دستورالعمل‌های گام‌به‌گام درباره تولید جفت کلید و ساختن JWT، به ساختن اثبات DPoP مراجعه کنید.
تبادل موفق با پاسخ 200 OK
حاوی کد دسترسی جدید نشان داده می‌شود. وقتی از DPoP استفاده می‌شود،
token_type Bearer است. پاسخ موفق تأیید می‌کند
مدرک DPoP برای کد نوسازی پذیرفته شده است. Google ممکن است سرصفحه HTTP جدیدی
DPoP-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",
"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 را مستقیماً به برنامه شما ارائه می‌دهد و نیاز به نشانی وب هدایت را ازبین می‌برد.
نشانی 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 است.
- تعداد درخواست‌های درستی‌سنجی‌نشده: درخواست‌های منشأ ناشناخته - درخواست‌هایی که نشانک «بررسی برنامه» ندارند و به‌نظر نمی‌رسد از برنامه شما آمده باشند.
- تعداد درخواست‌های درستی‌سنجی‌نشده: درخواست‌های نامعتبر - درخواست‌هایی با نشان «بررسی برنامه» نامعتبر، که ممکن است از کارخواه غیرمعتبری باشد که تلاش می‌کند هویت برنامه‌تان را جعل کند، یا از محیط‌های شبیه‌سازی‌شده باشد.
برای اعمال «بررسی برنامه»، روی دکمه 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
برای کسب اطلاعات بیشتر درباره نحوه پیاده‌سازی «محافظت بین‌حسابی» و فهرست کامل رویدادهای دردسترس، به صفحه «محافظت از حساب‌های کاربری با محافظت بین‌حسابی» مراجعه کنید.