OAuth 2.0 برای برنامه های موبایل و دسکتاپ

توجه: اگر با OAuth 2.0 تازه کار هستید، توصیه می کنیم قبل از شروع به کار نمای کلی OAuth 2.0 را مطالعه کنید. مرور کلی جریان‌های OAuth 2.0 را که Google پشتیبانی می‌کند، خلاصه می‌کند، که می‌تواند به شما کمک کند تا مطمئن شوید که جریان مناسب را برای برنامه خود انتخاب کرده‌اید.

این سند توضیح می‌دهد که چگونه برنامه‌های نصب شده در دستگاه‌هایی مانند تلفن، تبلت و رایانه از نقاط پایانی OAuth 2.0 Google برای اجازه دسترسی به YouTube Analytics API یا YouTube Reporting API استفاده می‌کنند.

OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. به عنوان مثال، یک برنامه می تواند از OAuth 2.0 برای دریافت مجوز برای بازیابی داده های YouTube Analytics یک کانال استفاده کند.

برنامه‌های نصب‌شده در دستگاه‌های جداگانه توزیع می‌شوند و فرض بر این است که این برنامه‌ها نمی‌توانند اسرار را حفظ کنند. وقتی کاربر در برنامه حضور دارد یا زمانی که برنامه در پس‌زمینه اجرا می‌شود، می‌توانند به Google API دسترسی داشته باشند.

این جریان مجوز مشابه جریان مورد استفاده برای برنامه های کاربردی وب سرور است. تفاوت اصلی این است که برنامه های نصب شده باید مرورگر سیستم را باز کنند و یک URI تغییر مسیر محلی برای رسیدگی به پاسخ ها از سرور مجوز Google ارائه دهند.

جایگزین ها

برای برنامه‌های تلفن همراه، ممکن است ترجیح دهید از Google Sign-in برای Android یا iOS استفاده کنید. کتابخانه‌های سرویس گیرنده Google Sign-in، احراز هویت و مجوز کاربر را کنترل می‌کنند، و ممکن است اجرای آنها ساده‌تر از پروتکل سطح پایین‌تر توضیح داده شده در اینجا باشد.

برای برنامه‌هایی که روی دستگاه‌هایی اجرا می‌شوند که از مرورگر سیستم پشتیبانی نمی‌کنند یا دارای قابلیت‌های ورودی محدودی هستند، مانند تلویزیون‌ها، کنسول‌های بازی، دوربین‌ها یا چاپگرها، به OAuth 2.0 برای تلویزیون‌ها و دستگاه‌ها یا ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود مراجعه کنید.

کتابخانه ها و نمونه ها

ما کتابخانه ها و نمونه های زیر را برای کمک به پیاده سازی جریان OAuth 2.0 که در این سند توضیح داده شده است، توصیه می کنیم:

• AppAuth برای کتابخانه اندروید
• AppAuth برای کتابخانه iOS
• OAuth برای برنامه ها: نمونه های ویندوز

پیش نیازها

API ها را برای پروژه خود فعال کنید

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن APIها را در آن فعال کند API Console.

برای فعال کردن یک API برای پروژه خود:

1. Open the API Library در Google API Console.
2. If prompted, select a project, or create a new one.
3. از صفحه کتابخانه برای یافتن و فعال کردن API YouTube Analytics و YouTube Reporting API استفاده کنید. بسیاری از برنامه‌هایی که داده‌های YouTube Analytics را بازیابی می‌کنند، با YouTube Data API نیز ارتباط دارند. هر API دیگری را که برنامه شما از آن استفاده می کند پیدا کنید و آن ها را نیز فعال کنید.

اعتبارنامه مجوز ایجاد کنید

هر برنامه‌ای که از OAuth 2.0 برای دسترسی به APIهای Google استفاده می‌کند، باید دارای اعتبارنامه مجوز باشد که برنامه را در سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه ها برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.

1. Go to the Credentials page.
2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
3. بخش‌های زیر انواع سرویس گیرنده‌هایی را که سرور مجوز Google پشتیبانی می‌کند، توضیح می‌دهد. نوع سرویس گیرنده ای را که برای برنامه شما توصیه می شود انتخاب کنید، کلاینت OAuth خود را نام ببرید و فیلدهای دیگر را در فرم مناسب تنظیم کنید.

اندروید

1. نوع برنامه اندروید را انتخاب کنید.
2. یک نام برای مشتری OAuth وارد کنید. این نام در پروژه شما نمایش داده می شود Credentials page برای شناسایی مشتری
3. نام بسته برنامه اندروید خود را وارد کنید. این مقدار در ویژگی package عنصر <manifest> در فایل مانیفست برنامه شما تعریف شده است.
4. اثر انگشت گواهی امضای SHA-1 توزیع برنامه را وارد کنید.
   • اگر برنامه شما از امضای برنامه توسط Google Play استفاده می‌کند، اثر انگشت SHA-1 را از صفحه امضای برنامه کنسول Play کپی کنید.
   • اگر ذخیره کلید و کلیدهای امضای خود را مدیریت می‌کنید، از ابزار ابزار کلید موجود در جاوا برای چاپ اطلاعات گواهی در قالبی قابل خواندن برای انسان استفاده کنید. مقدار SHA1 را در بخش Certificate fingerprints در خروجی ابزار کلید کپی کنید. برای اطلاعات بیشتر به تأیید اعتبار مشتری خود در اسناد Google APIs for Android مراجعه کنید.
5. (اختیاری) مالکیت برنامه Android خود را تأیید کنید .
6. روی ایجاد کلیک کنید.

iOS

1. نوع برنامه iOS را انتخاب کنید.
2. یک نام برای مشتری OAuth وارد کنید. این نام در پروژه شما نمایش داده می شود Credentials page برای شناسایی مشتری
3. شناسه بسته نرم افزاری خود را وارد کنید. شناسه بسته مقدار کلید CFBundleIdentifier در فایل منبع فهرست دارایی اطلاعات برنامه شما ( info.plist ) است. این مقدار معمولاً در قسمت General یا پانل Signing & Capabilities در ویرایشگر پروژه Xcode نمایش داده می شود. شناسه بسته نرم افزاری همچنین در بخش اطلاعات عمومی صفحه اطلاعات برنامه برای برنامه در سایت App Store Connect Apple نمایش داده می شود.

   تأیید کنید که از شناسه بسته نرم افزاری درستی برای برنامه خود استفاده می کنید، زیرا اگر از ویژگی بررسی برنامه استفاده می کنید، نمی توانید آن را تغییر دهید.

4. (اختیاری)

   اگر برنامه در اپ استور اپل منتشر شده است، شناسه App Store برنامه خود را وارد کنید. شناسه فروشگاه یک رشته عددی است که در هر URL اپ استور اپل وجود دارد.

   1. برنامه Apple App Store را در دستگاه iOS یا iPadOS خود باز کنید.
   2. برنامه خود را جستجو کنید.
   3. دکمه اشتراک گذاری (نماد مربع و فلش رو به بالا) را انتخاب کنید.
   4. کپی پیوند را انتخاب کنید.
   5. پیوند را در یک ویرایشگر متن قرار دهید. شناسه فروشگاه App آخرین قسمت URL است.

      مثال: https://apps.apple.com/app/google/id 284815942

5. (اختیاری)

   شناسه تیم خود را وارد کنید. برای اطلاعات بیشتر به شناسه تیم خود در مستندات حساب توسعه دهنده اپل مراجعه کنید.

   توجه: اگر برنامه بررسی را برای مشتری خود فعال می کنید، فیلد Team ID ضروری است.
6. (اختیاری)

   بررسی برنامه را برای برنامه iOS خود فعال کنید. وقتی App Check را فعال می‌کنید، از سرویس App Attest Apple برای تأیید اینکه درخواست‌های OAuth 2.0 از مشتری OAuth شما واقعی هستند و از برنامه شما می‌آیند استفاده می‌شود. این به کاهش خطر جعل هویت اپلیکیشن کمک می کند. درباره فعال کردن App Check برای برنامه iOS خود بیشتر بیاموزید .

7. روی ایجاد کلیک کنید.

UWP

1. نوع برنامه Universal Windows Platform را انتخاب کنید.
2. یک نام برای مشتری OAuth وارد کنید. این نام در پروژه شما نمایش داده می شود Credentials page برای شناسایی مشتری
3. شناسه فروشگاه مایکروسافت 12 کاراکتری برنامه خود را وارد کنید. می توانید این مقدار را در Microsoft Partner Center در صفحه هویت برنامه در بخش مدیریت برنامه پیدا کنید.
4. روی ایجاد کلیک کنید.

برای برنامه‌های UWP، طرح URI سفارشی نمی‌تواند بیشتر از 39 کاراکتر باشد.

محدوده های دسترسی را شناسایی کنید

Scopes به برنامه شما امکان می‌دهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر می‌سازد تا میزان دسترسی را که به برنامه شما می‌دهند کنترل کنند. بنابراین، ممکن است بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود داشته باشد.

قبل از شروع اجرای مجوز OAuth 2.0، توصیه می‌کنیم محدوده‌هایی را که برنامه شما برای دسترسی به آنها نیاز به مجوز دارد، شناسایی کنید.

توجه: مجوز افزایشی برای برنامه‌ها یا دستگاه‌های نصب‌شده پشتیبانی نمی‌شود.

YouTube Analytics API از حوزه های زیر استفاده می کند:

محدوده ها
https://www.googleapis.com/auth/youtube	حساب YouTube خود را مدیریت کنید
https://www.googleapis.com/auth/youtube.readonly	حساب YouTube خود را مشاهده کنید
https://www.googleapis.com/auth/youtubepartner	دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/youtube	حساب YouTube خود را مدیریت کنید
https://www.googleapis.com/auth/youtube.readonly	حساب YouTube خود را مشاهده کنید
https://www.googleapis.com/auth/youtubepartner	دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/youtube	حساب YouTube خود را مدیریت کنید
https://www.googleapis.com/auth/youtube.readonly	حساب YouTube خود را مشاهده کنید
https://www.googleapis.com/auth/youtubepartner	دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/youtube	حساب YouTube خود را مدیریت کنید
https://www.googleapis.com/auth/youtube.readonly	حساب YouTube خود را مشاهده کنید
https://www.googleapis.com/auth/youtubepartner	دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

YouTube Reporting API از حوزه های زیر استفاده می کند:

محدوده ها
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

،

محدوده ها
https://www.googleapis.com/auth/yt-analytics-monetary.readonly	گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید
https://www.googleapis.com/auth/yt-analytics.readonly	گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید

سند OAuth 2.0 API Scopes حاوی فهرست کاملی از حوزه‌هایی است که ممکن است برای دسترسی به Google API از آنها استفاده کنید.

اگر برنامه عمومی شما از دامنه‌هایی استفاده می‌کند که اجازه دسترسی به داده‌های کاربر خاص را می‌دهد، باید یک فرآیند تأیید را تکمیل کند. اگر هنگام آزمایش برنامه خود، برنامه تأیید نشده را روی صفحه مشاهده کردید، باید برای حذف آن درخواست تأیید ارسال کنید. درباره برنامه‌های تأیید نشده بیشتر بیاموزید و پاسخ سؤالات متداول درباره تأیید برنامه را در مرکز راهنمایی دریافت کنید.

دریافت توکن های دسترسی OAuth 2.0

مراحل زیر نشان می دهد که چگونه برنامه شما با سرور OAuth 2.0 Google برای کسب رضایت کاربر برای انجام یک درخواست API از طرف کاربر تعامل دارد. برنامه شما قبل از اینکه بتواند یک درخواست Google API را که نیاز به مجوز کاربر دارد، اجرا کند، باید این رضایت را داشته باشد.

مرحله 1: یک تأیید کننده کد و چالش ایجاد کنید

Google از پروتکل Proof Key for Code Exchange (PKCE) پشتیبانی می کند تا جریان برنامه نصب شده را ایمن تر کند. برای هر درخواست مجوز یک تأیید کننده کد منحصر به فرد ایجاد می شود و مقدار تبدیل شده آن به نام "code_challenge" برای دریافت کد مجوز به سرور مجوز ارسال می شود.

تایید کننده کد را ایجاد کنید

یک code_verifier یک رشته رمزنگاری تصادفی با آنتروپی بالا با استفاده از کاراکترهای رزرو نشده [AZ] / [az] / [0-9] / "-" / " است. / "_" / "~"، با حداقل طول 43 کاراکتر و حداکثر طول 128 کاراکتر.

تأیید کننده کد باید آنتروپی کافی داشته باشد تا حدس زدن مقدار را غیرعملی کند.

چالش کد را ایجاد کنید

دو روش ایجاد چالش کد پشتیبانی می شود.

روش‌های ایجاد چالش کد
S256 (توصیه می شود)	چالش کد، هش SHA256 کدگذاری شده Base64URL (بدون بالشتک) تأییدکننده کد است. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
ساده	چالش کد همان مقدار تأیید کننده کد تولید شده در بالا است. code_challenge = code_verifier

مرحله 2: درخواستی را به سرور OAuth 2.0 Google ارسال کنید

برای دریافت مجوز کاربر، درخواستی را به سرور مجوز Google در https://accounts.google.com/o/oauth2/v2/auth ارسال کنید. این نقطه پایانی جستجوی جلسه فعال را کنترل می کند، کاربر را احراز هویت می کند و رضایت کاربر را دریافت می کند. نقطه پایانی فقط از طریق SSL قابل دسترسی است و از اتصالات HTTP (غیر SSL) خودداری می کند.

سرور مجوز از پارامترهای رشته کوئری زیر برای برنامه های نصب شده پشتیبانی می کند:

پارامترها
client_id	مورد نیاز شناسه مشتری برای برنامه شما. شما می توانید این مقدار را در API ConsoleCredentials page.
redirect_uri	مورد نیاز نحوه ارسال پاسخ سرور مجوز Google به برنامه شما را تعیین می کند. چندین گزینه تغییر مسیر برای برنامه های نصب شده وجود دارد، و شما اعتبار مجوز خود را با روش تغییر مسیر خاصی در ذهن تنظیم خواهید کرد. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در مشتری خود پیکربندی کرده اید. API ConsoleCredentials page. اگر این مقدار با یک URI مجاز مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد. جدول زیر مقدار پارامتر redirect_uri مناسب را برای هر روش نشان می دهد: مقادیر redirect_uri طرح URI سفارشی com.example.app : redirect_uri_path یا com.googleusercontent.apps.123 : redirect_uri_path com.example.app نماد DNS معکوس دامنه تحت کنترل شما است. طرح سفارشی باید دارای یک دوره باشد تا معتبر باشد. com.googleusercontent.apps.123 نماد DNS معکوس شناسه مشتری است. redirect_uri_path یک جزء مسیر اختیاری است، مانند /oauth2redirect . توجه داشته باشید که مسیر باید با یک اسلش شروع شود که با URL های HTTP معمولی متفاوت است. توجه : طرح‌های URI سفارشی دیگر در برنامه‌های Chrome پشتیبانی نمی‌شوند و به‌طور پیش‌فرض در Android غیرفعال هستند. درباره جایگزین‌های طرح سفارشی برای برنامه‌های Android و Chrome بیشتر بدانید . آدرس IP Loopback http://127.0.0.1: port یا http://[::1]: port از پلتفرم خود برای آدرس IP مربوطه پرس و جو کنید و یک شنونده HTTP را در یک پورت تصادفی در دسترس راه اندازی کنید. port با شماره پورتی که برنامه شما به آن گوش می دهد جایگزین کنید. توجه داشته باشید که پشتیبانی از گزینه تغییر مسیر آدرس IP Loopback در برنامه های تلفن همراه منسوخ شده است.
response_type	مورد نیاز تعیین می کند که آیا نقطه پایانی Google OAuth 2.0 یک کد مجوز را برمی گرداند یا خیر. مقدار پارامتر را روی code برنامه های نصب شده تنظیم کنید.
scope	مورد نیاز فهرستی از محدوده‌های محدود شده با فضا که منابعی را که برنامه شما می‌تواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی می‌کند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد. Scopes به برنامه شما امکان می‌دهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر می‌سازد تا میزان دسترسی را که به برنامه شما می‌دهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد. YouTube Analytics API از حوزه های زیر استفاده می کند: محدوده ها https://www.googleapis.com/auth/youtube حساب YouTube خود را مدیریت کنید https://www.googleapis.com/auth/youtube.readonly حساب YouTube خود را مشاهده کنید https://www.googleapis.com/auth/youtubepartner دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/youtube حساب YouTube خود را مدیریت کنید https://www.googleapis.com/auth/youtube.readonly حساب YouTube خود را مشاهده کنید https://www.googleapis.com/auth/youtubepartner دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/youtube حساب YouTube خود را مدیریت کنید https://www.googleapis.com/auth/youtube.readonly حساب YouTube خود را مشاهده کنید https://www.googleapis.com/auth/youtubepartner دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/youtube حساب YouTube خود را مدیریت کنید https://www.googleapis.com/auth/youtube.readonly حساب YouTube خود را مشاهده کنید https://www.googleapis.com/auth/youtubepartner دارایی ها و محتوای مرتبط خود را در YouTube مشاهده و مدیریت کنید https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید YouTube Reporting API از حوزه های زیر استفاده می کند: محدوده ها https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید ، محدوده ها https://www.googleapis.com/auth/yt-analytics-monetary.readonly گزارش های پولی و غیر پولی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید https://www.googleapis.com/auth/yt-analytics.readonly گزارش‌های YouTube Analytics را برای محتوای YouTube خود مشاهده کنید سند OAuth 2.0 API Scopes فهرست کاملی از حوزه هایی را ارائه می دهد که ممکن است برای دسترسی به Google API از آنها استفاده کنید.
code_challenge	توصیه می شود یک code_verifier کدگذاری شده را مشخص می کند که به عنوان یک چالش سمت سرور در طول تبادل کد مجوز استفاده می شود. برای اطلاعات بیشتر به بخش ایجاد چالش کد در بالا مراجعه کنید.
code_challenge_method	توصیه می شود مشخص می کند که از چه روشی برای رمزگذاری یک code_verifier استفاده شده است که در هنگام تبادل کد مجوز استفاده می شود. این پارامتر باید با پارامتر code_challenge که در بالا توضیح داده شد استفاده شود. مقدار code_challenge_method اگر در درخواستی که شامل یک code_challenge است وجود نداشته باشد، به طور پیش‌فرض به plain است. تنها مقادیر پشتیبانی شده برای این پارامتر S256 یا plain هستند.
state	توصیه می شود هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند. سرور مقدار دقیقی را که شما به عنوان یک جفت name=value در شناسه قطعه URL ( # ) از redirect_uri ارسال می کنید، پس از رضایت کاربر یا رد درخواست دسترسی برنامه شما، برمی گرداند. شما می توانید از این پارامتر برای اهداف مختلفی مانند هدایت کاربر به منبع صحیح در برنامه خود، ارسال nonces و کاهش جعل درخواست بین سایتی استفاده کنید. از آنجایی که redirect_uri شما قابل حدس زدن است، استفاده از یک مقدار state می تواند اطمینان شما را از اینکه اتصال ورودی نتیجه درخواست احراز هویت است افزایش دهد. اگر یک رشته تصادفی ایجاد کنید یا هش یک کوکی یا مقدار دیگری را رمزگذاری کنید که وضعیت مشتری را نشان می‌دهد، می‌توانید پاسخ را تأیید اعتبار کنید تا علاوه بر این اطمینان حاصل کنید که درخواست و پاسخ از یک مرورگر منشأ گرفته‌اند و محافظت در برابر حملاتی مانند cross-site را فراهم می‌کنند. درخواست جعل . برای مثالی از نحوه ایجاد و تأیید یک نشانه state ، به اسناد OpenID Connect مراجعه کنید. مهم: مشتری OAuth باید از CSRF همانطور که در مشخصات OAuth2 نامیده شده است جلوگیری کند. یکی از راه‌های رسیدن به این هدف، استفاده از پارامتر state برای حفظ حالت بین درخواست مجوز شما و پاسخ سرور مجوز است.
login_hint	اختیاری اگر برنامه شما بداند که کدام کاربر در حال تلاش برای احراز هویت است، می‌تواند از این پارامتر برای ارائه راهنمایی به سرور احراز هویت Google استفاده کند. سرور از راهنمایی برای ساده سازی جریان ورود استفاده می کند یا با پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چند ورود مناسب. مقدار پارامتر را به آدرس ایمیل یا شناسه sub که معادل شناسه گوگل کاربر است تنظیم کنید.

توجه: مجوز افزایشی با برنامه های نصب شده پشتیبانی نمی شود، زیرا مشتری نمی تواند client_secret را محرمانه نگه دارد.

نمونه URL های مجوز

برگه های زیر نمونه URL های مجوز را برای گزینه های مختلف URI تغییر مسیر نشان می دهد.

هر URL درخواست دسترسی به محدوده‌ای را می‌دهد که اجازه دسترسی به بازیابی گزارش‌های YouTube Analytics کاربر را می‌دهد.

URL ها به جز مقدار پارامتر redirect_uri یکسان هستند. URL ها همچنین حاوی پارامترهای response_type و client_id مورد نیاز و همچنین پارامتر state اختیاری هستند. هر URL حاوی خطوط شکسته و فاصله برای خوانایی است.

طرح URI سفارشی

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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 Loopback

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.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

مرحله 3: گوگل رضایت کاربر را درخواست می کند

در این مرحله، کاربر تصمیم می گیرد که آیا به اپلیکیشن شما دسترسی درخواستی را بدهد یا خیر. در این مرحله، گوگل یک پنجره رضایت را نمایش می دهد که نام برنامه شما و سرویس های Google API را نشان می دهد که درخواست اجازه دسترسی به آن ها را با اعتبار مجوز کاربر و خلاصه ای از محدوده های دسترسی که باید اعطا شود را نشان می دهد. سپس کاربر می تواند با اعطای دسترسی به یک یا چند حوزه درخواست شده توسط برنامه شما موافقت کند یا درخواست را رد کند.

برنامه شما در این مرحله نیازی به انجام هیچ کاری ندارد زیرا منتظر پاسخ سرور OAuth 2.0 Google است که نشان می دهد آیا دسترسی اعطا شده است یا خیر. این پاسخ در مرحله زیر توضیح داده شده است.

خطاها

درخواست‌ها به نقطه پایانی مجوز OAuth 2.0 Google ممکن است پیام‌های خطای کاربر را به‌جای جریان‌های احراز هویت و مجوز مورد انتظار نمایش دهند. کدهای خطای رایج و راهکارهای پیشنهادی در زیر فهرست شده‌اند.

admin_policy_enforced

حساب Google به دلیل خط‌مشی‌های سرپرست Google Workspace نمی‌تواند یک یا چند محدوده درخواستی را تأیید کند. برای اطلاعات بیشتر در مورد اینکه چگونه یک سرپرست می‌تواند دسترسی به همه حوزه‌ها یا محدوده‌های حساس و محدود را تا زمانی که صراحتاً به شناسه مشتری OAuth شما اعطا نشود، به مقاله راهنمای Google Workspace Admin مراجعه کنید.

disallowed_useragent

نقطه پایانی مجوز در داخل یک عامل کاربر تعبیه‌شده نمایش داده می‌شود که توسط خط‌مشی‌های OAuth 2.0 Google مجاز نیست.

اندروید

برنامه‌نویسان Android ممکن است هنگام باز کردن درخواست‌های مجوز درandroid.webkit.WebView با این پیام خطا مواجه شوند. توسعه‌دهندگان باید در عوض از کتابخانه‌های Android مانند Google Sign-In برای Android یا OpenID Foundation's AppAuth for Android استفاده کنند.

توسعه دهندگان وب ممکن است زمانی با این خطا مواجه شوند که یک برنامه Android یک پیوند وب کلی را در یک عامل کاربر تعبیه شده باز کند و کاربر به نقطه پایانی مجوز OAuth 2.0 Google از سایت شما هدایت شود. توسعه‌دهندگان باید اجازه دهند پیوندهای عمومی در کنترل‌کننده پیوند پیش‌فرض سیستم‌عامل، که شامل کنترل‌کننده‌های پیوندهای برنامه Android یا برنامه مرورگر پیش‌فرض است، باز شوند. کتابخانه Android Custom Tabs نیز یک گزینه پشتیبانی شده است.

iOS

توسعه دهندگان iOS و macOS ممکن است هنگام باز کردن درخواست های مجوز درWKWebView با این خطا مواجه شوند. توسعه‌دهندگان باید در عوض از کتابخانه‌های iOS مانند Google Sign-In برای iOS یا OpenID Foundations AppAuth برای iOS استفاده کنند.

زمانی که یک برنامه iOS یا macOS یک پیوند وب عمومی را در یک عامل کاربر تعبیه شده باز می کند و کاربر به نقطه پایانی مجوز OAuth 2.0 Google از سایت شما می رود، ممکن است توسعه دهندگان وب با این خطا مواجه شوند. توسعه‌دهندگان باید اجازه دهند پیوندهای عمومی در کنترل‌کننده پیوند پیش‌فرض سیستم‌عامل، که شامل کنترل‌کننده‌های پیوندهای جهانی یا برنامه مرورگر پیش‌فرض است، باز شوند. کتابخانهSFSafariViewController نیز یک گزینه پشتیبانی شده است.

org_internal

شناسه مشتری OAuth در درخواست بخشی از پروژه ای است که دسترسی به حساب های Google را در یک سازمان Google Cloud خاص محدود می کند. برای اطلاعات بیشتر در مورد این گزینه پیکربندی، بخش نوع کاربر را در مقاله راهنمای تنظیم صفحه رضایت OAuth خود ببینید.

invalid_grant

اگر از تأیید کننده کد و چالش استفاده می کنید، پارامتر code_callenge نامعتبر است یا وجود ندارد. مطمئن شوید که پارامتر code_challenge به درستی تنظیم شده است.

هنگام بازخوانی نشانه دسترسی ، نشانه ممکن است منقضی شده باشد یا باطل شده باشد. مجدداً کاربر را احراز هویت کنید و برای دریافت توکن های جدید رضایت کاربر را بخواهید. اگر همچنان این خطا را مشاهده می کنید، مطمئن شوید که برنامه شما به درستی پیکربندی شده است و از نشانه ها و پارامترهای صحیح در درخواست خود استفاده می کنید. در غیر این صورت، حساب کاربری ممکن است حذف یا غیرفعال شده باشد.

redirect_uri_mismatch

redirect_uri ارسال شده در درخواست مجوز با URI تغییر مسیر مجاز برای شناسه مشتری OAuth مطابقت ندارد. URIهای مجاز تغییر مسیر را در Google API Console Credentials page.

redirect_uri ارسال شده ممکن است برای نوع مشتری نامعتبر باشد.

پارامتر redirect_uri ممکن است به جریان OAuth خارج از باند (OOB) اشاره داشته باشد که منسوخ شده است و دیگر پشتیبانی نمی شود. برای به روز رسانی ادغام خود به راهنمای مهاجرت مراجعه کنید.

invalid_request

مشکلی در درخواستی که دادید وجود داشت. این می تواند به دلایل مختلفی باشد:

• درخواست به درستی قالب بندی نشده بود
• درخواست فاقد پارامترهای لازم بود
• این درخواست از روش مجوزی استفاده می‌کند که Google از آن پشتیبانی نمی‌کند. بررسی کنید که ادغام OAuth شما از یک روش ادغام توصیه شده استفاده می کند
• یک طرح سفارشی برای تغییر مسیر uri استفاده می‌شود: اگر پیام خطا را مشاهده کردید که طرح URI سفارشی در برنامه‌های Chrome پشتیبانی نمی‌شود یا طرح URI سفارشی برای کلاینت Android شما فعال نیست ، به این معنی است که از یک طرح URI سفارشی استفاده می‌کنید که چنین نیست. در برنامه های Chrome پشتیبانی می شود و به طور پیش فرض در Android غیرفعال است. درباره جایگزین های طرح URI سفارشی بیشتر بیاموزید

مرحله 4: پاسخ سرور OAuth 2.0 را مدیریت کنید

روشی که برنامه شما پاسخ مجوز را دریافت می کند به طرح URI تغییر مسیری که استفاده می کند بستگی دارد. صرف نظر از طرح، پاسخ شامل یک کد مجوز ( code ) یا یک خطا ( error ) خواهد بود. برای مثال error=access_denied نشان می دهد که کاربر درخواست را رد کرده است.

اگر کاربر اجازه دسترسی به برنامه شما را بدهد، می‌توانید کد مجوز را با یک نشانه دسترسی و یک نشانه تازه‌سازی، همانطور که در مرحله بعد توضیح داده شد، مبادله کنید.

مرحله 5: کد مجوز را برای به‌روزرسانی و دسترسی به توکن‌ها مبادله کنید

برای تبادل کد مجوز برای یک نشانه دسترسی، با https://oauth2.googleapis.com/token endpoint تماس بگیرید و پارامترهای زیر را تنظیم کنید:

فیلدها
client_id	شناسه مشتری به دست آمده از API ConsoleCredentials page.
client_secret	راز مشتری به دست آمده از API ConsoleCredentials page.
code	کد مجوز از درخواست اولیه بازگردانده شد.
code_verifier	تأیید کننده کدی که در مرحله 1 ایجاد کردید.
grant_type	همانطور که در مشخصات OAuth 2.0 تعریف شده است ، مقدار این فیلد باید روی authorization_code تنظیم شود.
redirect_uri	یکی از URI های تغییر مسیر که برای پروژه شما در فهرست فهرست شده است API ConsoleCredentials page برای client_id داده شده.

قطعه زیر یک نمونه درخواست را نشان می دهد:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google به این درخواست با برگرداندن یک شی JSON که حاوی یک نشانه دسترسی کوتاه مدت و یک نشانه تازه‌سازی است، پاسخ می‌دهد.

پاسخ شامل فیلدهای زیر است:

فیلدها
access_token	رمزی که برنامه شما برای تأیید درخواست Google API ارسال می کند.
expires_in	طول عمر باقیمانده رمز دسترسی در ثانیه.
id_token	توجه: این ویژگی تنها در صورتی بازگردانده می‌شود که درخواست شما شامل محدوده هویتی مانند openid ، profile یا email باشد. مقدار یک رمز وب JSON (JWT) است که حاوی اطلاعات هویتی با امضای دیجیتالی درباره کاربر است.
refresh_token	توکنی که می توانید از آن برای به دست آوردن یک نشانه دسترسی جدید استفاده کنید. نشانه‌های Refresh تا زمانی که کاربر دسترسی را لغو نکند معتبر هستند. توجه داشته باشید که نشانه های تازه سازی همیشه برای برنامه های نصب شده برگردانده می شوند.
scope	دامنه دسترسی اعطا شده توسط access_token به صورت لیستی از رشته های حساس به حروف کوچک و کوچک با فاصله بیان می شود.
token_type	نوع رمز برگشتی. در این زمان، مقدار این فیلد همیشه روی Bearer تنظیم می شود.

مهم: برنامه شما باید هر دو توکن را در مکانی امن و با عمر طولانی ذخیره کند که بین فراخوان های مختلف برنامه شما قابل دسترسی باشد. توکن refresh به برنامه شما امکان می‌دهد تا در صورتی که رمز دسترسی شما منقضی شود، یک رمز دسترسی جدید به دست آورد. به این ترتیب، اگر برنامه شما رمز بازخوانی را از دست بدهد، کاربر باید جریان رضایت OAuth 2.0 را تکرار کند تا برنامه شما بتواند یک نشانه به‌روزرسانی جدید دریافت کند.

قطعه زیر یک نمونه پاسخ را نشان می دهد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

توجه: برنامه شما باید فیلدهای ناشناخته موجود در پاسخ را نادیده بگیرد.

مرحله 6: بررسی کنید که کاربران چه محدوده هایی را اعطا کرده اند

هنگامی که چندین دامنه را به طور همزمان درخواست می کنید، کاربران ممکن است همه دامنه درخواست های برنامه شما را اعطا نکنند. برنامه شما باید همیشه بررسی کند که کاربر کدام حوزه را اعطا کرده است و با غیرفعال کردن ویژگی‌های مربوطه، هرگونه انکار دامنه را بررسی کند. برای اطلاعات بیشتر نحوه رسیدگی به مجوزهای گرانول را مرور کنید.

برای بررسی اینکه آیا کاربر به برنامه شما اجازه دسترسی به یک محدوده خاص را داده است یا خیر، فیلد scope در پاسخ نشانه دسترسی بررسی کنید. دامنه دسترسی اعطا شده توسط access_token به صورت لیستی از رشته های حساس به حروف کوچک و کوچک با فاصله بیان می شود.

به عنوان مثال، نمونه پاسخ نشانه دسترسی زیر نشان می دهد که کاربر به برنامه شما اجازه دسترسی به فعالیت Drive فقط خواندنی و رویدادهای تقویم را داده است:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

فراخوانی Google API

پس از اینکه برنامه شما یک نشانه دسترسی به دست آورد، در صورتی که دامنه دسترسی مورد نیاز توسط API اعطا شده باشد، می توانید از این رمز برای برقراری تماس با Google API از طرف یک حساب کاربری خاص استفاده کنید. برای انجام این کار، توکن دسترسی را با درج یک پارامتر query access_token یا یک مقدار Authorization HTTP header Bearer در درخواست API قرار دهید. در صورت امکان، هدر HTTP ترجیح داده می شود، زیرا رشته های پرس و جو در گزارش های سرور قابل مشاهده هستند. در بیشتر موارد می‌توانید از کتابخانه سرویس گیرنده برای تنظیم تماس‌های خود با Google API استفاده کنید (به عنوان مثال، هنگام تماس با YouTube Analytics API ).

توجه داشته باشید که YouTube Analytics API از جریان حساب سرویس پشتیبانی نمی‌کند. YouTube Reporting API از حساب‌های خدماتی فقط برای دارندگان محتوای YouTube پشتیبانی می‌کند که چندین کانال YouTube مانند برچسب‌های ضبط و استودیوهای فیلم را مالک و مدیریت می‌کنند.

می‌توانید همه APIهای Google را امتحان کنید و دامنه آنها را در OAuth 2.0 Playground مشاهده کنید.

نمونه های HTTP GET

تماس با نقطه پایانی reports.query (API YouTube Analytics) با استفاده از هدر HTTP Authorization: Bearer ممکن است به شکل زیر باشد. توجه داشته باشید که باید رمز دسترسی خود را مشخص کنید:

GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query access_token وجود دارد:

GET https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

نمونه های curl

می توانید این دستورات را با برنامه خط فرمان curl آزمایش کنید. در اینجا یک مثال است که از گزینه هدر HTTP (ترجیح) استفاده می کند:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

یا، گزینه پارامتر query string:

curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views

در حال بازخوانی نشانه دسترسی

توکن‌های دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای یک درخواست API مرتبط به اعتبارنامه‌های نامعتبر تبدیل می‌شوند. اگر درخواست دسترسی آفلاین به محدوده‌های مرتبط با رمز را داشته باشید، می‌توانید یک نشانه دسترسی را بدون درخواست اجازه از کاربر (از جمله زمانی که کاربر حضور ندارد) بازخوانی کنید.

برای تازه کردن یک نشانه دسترسی، برنامه شما یک درخواست HTTPS POST به سرور مجوز Google ( https://oauth2.googleapis.com/token ) ارسال می کند که شامل پارامترهای زیر است:

فیلدها
client_id	شناسه مشتری به دست آمده از API Console.
client_secret	راز مشتری به دست آمده از API Console. ( client_secret برای درخواست‌های مشتریانی که به عنوان برنامه‌های Android، iOS یا Chrome ثبت شده‌اند، قابل اجرا نیست.)
grant_type	همانطور که در مشخصات OAuth 2.0 تعریف شده است ، مقدار این فیلد باید روی refresh_token تنظیم شود.
refresh_token	رمز به‌روزرسانی از تبادل کد مجوز بازگشت.

قطعه زیر یک نمونه درخواست را نشان می دهد:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

تا زمانی که کاربر دسترسی اعطا شده به برنامه را لغو نکرده باشد، سرور توکن یک شی JSON را که حاوی یک نشانه دسترسی جدید است برمی گرداند. قطعه زیر یک نمونه پاسخ را نشان می دهد:

{
  "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 سفارشی (اندروید، iOS، UWP)

طرح‌های URI سفارشی نوعی پیوند عمیق هستند که از یک طرح سفارشی تعریف شده برای باز کردن برنامه شما استفاده می‌کنند.

مهم: طرح‌های URI سفارشی دیگر در برنامه‌های جدید Chrome پشتیبانی نمی‌شوند و به‌دلیل خطر جعل هویت برنامه، به‌طور پیش‌فرض در کلاینت‌های Android جدید غیرفعال می‌شوند.

جایگزینی برای استفاده از طرح های URI سفارشی در اندروید

از Google Sign-In برای Android SDK استفاده کنید که پاسخ OAuth 2.0 را مستقیماً به برنامه شما ارائه می دهد و نیاز به URI تغییر مسیر را از بین می برد.

نحوه مهاجرت به Google Sign-In for Android SDK

اگر از یک طرح سفارشی برای ادغام OAuth خود در Android استفاده می کنید، باید اقدامات زیر را انجام دهید تا به طور کامل به استفاده از Google Sign-In توصیه شده برای Android SDK مهاجرت کنید:

1. کد خود را برای استفاده از Google Sign-In SDK به روز کنید.
2. پشتیبانی از طرح سفارشی را در Google API Console غیرفعال کنید.

توجه: باید قبل از غیرفعال کردن پشتیبانی از طرح‌های سفارشی در Google API Console، به‌روزرسانی‌های کد خود را تکمیل و اجرا کنید (محاسبه زمان پذیرش در پایگاه کاربر یا دستگاه‌های قدیمی‌تر) تا کاربران هنگام تلاش برای استفاده از برنامه شما، پیام خطای invalid_request دریافت نکنند.

مراحل زیر را برای انتقال به Google Sign-In Android SDK دنبال کنید:

1. کد خود را برای استفاده از Google Sign-In Android SDK به روز کنید:
   1. کد خود را بررسی کنید تا مشخص کنید کجا درخواستی را به سرور OAuth 2.0 Google ارسال می کنید . اگر از یک طرح سفارشی استفاده می کنید، درخواست شما به شکل زیر خواهد بود:

        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        

      com.example.app:/oauth2redirect URI تغییر مسیر طرح سفارشی در مثال بالا است. برای جزئیات بیشتر در مورد قالب مقدار طرح URI سفارشی، به تعریف پارامتر redirect_uri مراجعه کنید.
   2. پارامترهای scope و client_id درخواست را که برای پیکربندی Google Sign-In SDK نیاز دارید، یادداشت کنید.
      توجه: اگر از کتابخانه شخص ثالث استفاده می کنید، فایل پیکربندی کتابخانه را برای یافتن این اطلاعات مرور کنید.
   3. برای راه‌اندازی SDK، دستورالعمل‌های Start Integrating Google Sign-In را در برنامه Android خود دنبال کنید. می‌توانید از مرحله دریافت شناسه مشتری OAuth 2.0 سرور باطن خود صرفنظر کنید، همانطور که از client_id که از مرحله قبل بازیابی کرده‌اید دوباره استفاده می‌کنید.
   4. دستورالعمل‌های دسترسی به API سمت سرور را دنبال کنید. این شامل مراحل زیر است:
      1. از روش getServerAuthCode برای بازیابی یک کد اعتبار برای محدوده هایی که درخواست مجوز می کنید استفاده کنید.
      2. کد احراز هویت را به پشتیبان برنامه خود ارسال کنید تا آن را با رمز دسترسی و بازخوانی مبادله کنید.
      3. از نشانه دسترسی بازیابی شده برای برقراری تماس با Google API از طرف کاربر استفاده کنید.
      توجه: اگر برنامه شما به دسترسی آفلاین نیاز ندارد، به جای درخواست دسترسی API سمت سرویس گیرنده، این دستورالعمل ها را دنبال کنید.
2. غیرفعال کردن پشتیبانی از طرح سفارشی در Google API Console:
   1. به لیست اعتبارنامه OAuth 2.0 بروید و کلاینت Android خود را انتخاب کنید.
   2. به بخش تنظیمات پیشرفته بروید، تیک گزینه Enable Custom URI Scheme را بردارید و برای غیرفعال کردن پشتیبانی از طرح URI سفارشی، روی Save کلیک کنید.

طرح URI سفارشی را فعال کنید

اگر جایگزین توصیه شده برای شما کار نمی کند، می توانید با دنبال کردن دستورالعمل های زیر، طرح های URI سفارشی را برای مشتری Android خود فعال کنید:

1. به لیست اعتبارنامه OAuth 2.0 بروید و کلاینت Android خود را انتخاب کنید.
2. به بخش Advanced Settings بروید، چک باکس Enable Custom URI Scheme را علامت بزنید و Save را کلیک کنید تا پشتیبانی از طرح URI سفارشی فعال شود.

جایگزینی برای استفاده از طرح‌های URI سفارشی در برنامه‌های Chrome

از Chrome Identity API استفاده کنید که پاسخ OAuth 2.0 را مستقیماً به برنامه شما ارائه می دهد و نیاز به URI تغییر مسیر را از بین می برد.

آدرس IP Loopback (macOS، Linux، Windows desktop)

مهم: گزینه تغییر مسیر آدرس IP حلقه بک برای انواع سرویس گیرنده Android ، برنامه Chrome و iOS OAuth منسوخ شده است. راهنمای انتقال آدرس IP Loopback را برای دستورالعمل‌هایی در مورد نحوه انتقال به یک جایگزین پشتیبانی شده مرور کنید.

برای دریافت کد مجوز با استفاده از این URL، برنامه شما باید در وب سرور محلی در حال گوش دادن باشد. این در بسیاری از پلتفرم ها، اما نه همه، امکان پذیر است. با این حال، اگر پلت فرم شما از آن پشتیبانی می کند، این مکانیسم توصیه شده برای دریافت کد مجوز است.

هنگامی که برنامه شما پاسخ مجوز را دریافت می کند، برای بهترین قابلیت استفاده باید با نمایش یک صفحه HTML پاسخ دهد که به کاربر دستور می دهد مرورگر را ببندد و به برنامه شما بازگردد.

استفاده توصیه شده	برنامه‌های دسکتاپ macOS، Linux و Windows (اما نه Universal Windows Platform).
مقادیر فرم	نوع برنامه را روی برنامه دسکتاپ تنظیم کنید.

توجه: برای اطلاعات بیشتر در مورد آدرس IP loopback به تعریف پارامتر redirect_uri مراجعه کنید. همچنین می توان از localhost به جای IP Loopback استفاده کرد، اما این پیکربندی ممکن است باعث ایجاد مشکلاتی در فایروال های مشتری شود. اکثر فایروال ها، اما نه همه آنها، امکان ارتباط Loopback را فراهم می کنند.

کپی/پیست دستی (منسوخ شده)

مهم: گزینه کپی/پیست دستی، که به عنوان روش تغییر مسیر خارج از باند (OOB) نیز نامیده می شود، دیگر پشتیبانی نمی شود . راهنمای مهاجرت OOB را برای دستورالعمل‌هایی درباره نحوه مهاجرت به یک جایگزین امن مرور کنید.

از برنامه های خود محافظت کنید

تأیید مالکیت برنامه (اندروید، کروم)

برای کاهش خطر جعل هویت برنامه، می توانید مالکیت برنامه خود را تأیید کنید.

اندروید

توجه: تأیید مالکیت برنامه Android فقط برای برنامه‌های Google Play در دسترس است.

برای تکمیل فرآیند تأیید، اگر حساب برنامه‌نویس Google Play خود دارید و برنامه شما در کنسول Google Play ثبت شده است، می‌توانید از آن استفاده کنید. برای تأیید موفقیت آمیز باید شرایط زیر رعایت شود:

• باید برنامه‌ای ثبت‌شده در کنسول Google Play با همان نام بسته و اثر انگشت گواهی امضای SHA-1 به‌عنوان سرویس‌گیرنده Android OAuth که در حال تکمیل تأیید آن هستید، داشته باشید.
• شما باید مجوز Admin برای برنامه در کنسول Google Play داشته باشید. درباره مدیریت دسترسی در کنسول Google Play بیشتر بیاموزید .

در بخش Verify App Ownership در کلاینت Android، روی دکمه Verify Ownership کلیک کنید تا فرآیند تأیید تکمیل شود.

در صورت موفقیت آمیز بودن تأیید، یک اعلان برای تأیید موفقیت آمیز بودن فرآیند تأیید نمایش داده می شود. در غیر این صورت، یک اعلان خطا نشان داده خواهد شد.

برای رفع یک تأیید ناموفق، موارد زیر را امتحان کنید:

• مطمئن شوید برنامه ای که تأیید می کنید یک برنامه ثبت شده در کنسول Google Play است.
• مطمئن شوید که مجوز Admin برای برنامه در کنسول Google Play دارید.

کروم

برای تکمیل فرآیند تأیید، باید از حساب برنامه‌نویس فروشگاه وب Chrome خود استفاده کنید. برای تأیید موفقیت آمیز باید شرایط زیر رعایت شود:

• شما باید یک مورد ثبت‌شده در داشبورد برنامه‌نویس فروشگاه وب Chrome با همان شناسه موردی داشته باشید که مشتری OAuth برنامه افزودنی Chrome که تأیید را برای آن تکمیل می‌کنید.
• شما باید ناشر مورد فروشگاه وب Chrome باشید. درباره مدیریت دسترسی در داشبورد برنامه‌نویس فروشگاه وب Chrome بیشتر بدانید .

در بخش تأیید مالکیت برنامه مشتری برنامه افزودنی Chrome، روی دکمه تأیید مالکیت کلیک کنید تا فرآیند تأیید تکمیل شود.

توجه: پس از اعطای دسترسی به حساب خود، قبل از تکمیل فرآیند تأیید، چند دقیقه صبر کنید.

در صورت موفقیت آمیز بودن تأیید، یک اعلان برای تأیید موفقیت آمیز بودن فرآیند تأیید نمایش داده می شود. در غیر این صورت، یک اعلان خطا نشان داده خواهد شد.

برای رفع یک تأیید ناموفق، موارد زیر را امتحان کنید:

• مطمئن شوید که یک مورد ثبت‌شده در داشبورد برنامه‌نویس فروشگاه وب Chrome با همان شناسه موردی وجود دارد که مشتری OAuth برنامه افزودنی Chrome که تأیید را برای آن تکمیل می‌کنید.
• مطمئن شوید که ناشر برنامه هستید، یعنی باید ناشر انفرادی برنامه یا عضو گروه ناشر برنامه باشید. در مورد مدیریت دسترسی در داشبورد توسعه دهنده فروشگاه وب Chrome بیشتر بدانید .
• اگر به تازگی لیست ناشر گروه خود را به روز کرده اید ، تأیید کنید که لیست عضویت گروه ناشر در داشبورد توسعه دهنده فروشگاه وب Chrome همگام سازی شده است. در مورد همگام سازی لیست عضویت ناشر خود بیشتر بدانید .

بررسی برنامه (فقط iOS)

ویژگی چک برنامه به محافظت از برنامه های iOS شما از استفاده غیرمجاز با استفاده از برنامه تأیید شده اپل کمک می کند تا تأیید کند که درخواست های ساخته شده به نقاط پایانی Google OAUTH 2.0 از برنامه های معتبر شما سرچشمه می گیرد. این به کاهش خطر جعل هویت برنامه کمک می کند.

فعال کردن برنامه برای مشتری iOS خود را فعال کنید

برای فعال کردن موفقیت آمیز برنامه برای مشتری iOS باید موارد زیر را برآورده کنید:

• شما باید شناسه تیم را برای مشتری iOS خود مشخص کنید.
• شما نباید از کارت وحشی در شناسه بسته نرم افزاری خود استفاده کنید زیرا می تواند بیش از یک برنامه حل شود. این بدان معنی است که شناسه بسته نرم افزاری نباید شامل نماد ستاره (*) باشد.

هشدار: هنگامی که برنامه بررسی برنامه فعال است ، شما قادر نخواهید بود شناسه بسته نرم افزاری OAUTH خود را بدون ایجاد مشتری جدید ویرایش کنید. قبل از ایجاد مشتری iOS یا فعال کردن برنامه ، تأیید کنید که از شناسه بسته نرم افزاری استفاده می کنید. به روزرسانی شناسه بسته نرم افزاری خود برای یک پروژه موجود می تواند در صورت استفاده از شناسه Bundle به عنوان URI تغییر مسیر ، باعث تجربه شکسته برای کاربران برنامه های شما شود.

برای فعال کردن بررسی برنامه ، مشتری OAUTH خود را از سوءاستفاده از دکمه ضامن برنامه Firebase در نمای ویرایش مشتری iOS خود محافظت کنید.

پس از فعال کردن بررسی برنامه ، شروع به دیدن معیارهای مربوط به درخواست های OAUTH از مشتری خود در نمای ویرایش مشتری OAUTH خواهید کرد. درخواست های منابع تأیید نشده تا زمانی که شما بررسی برنامه را اجرا کنید مسدود نمی شوند. اطلاعات موجود در صفحه نظارت بر معیارها می تواند به شما در تعیین زمان شروع اجرای کمک کند.

ممکن است هنگام فعال کردن برنامه برنامه iOS خود ، خطاهای مربوط به ویژگی بررسی برنامه را مشاهده کنید. برای رفع این خطاها ، موارد زیر را امتحان کنید:

• تأیید کنید که شناسه بسته نرم افزاری و شناسه تیمی که مشخص کرده اید معتبر است.
• تأیید کنید که از کارت وحشی برای شناسه بسته نرم افزاری استفاده نمی کنید.

اجرای برنامه برای مشتری iOS خود را بررسی کنید

فعال کردن برنامه برای برنامه شما به طور خودکار درخواست های ناشناخته را مسدود نمی کند. برای اجرای این محافظت ، به نمای ویرایش مشتری iOS خود بروید. در آنجا ، معیارهای بررسی برنامه را در سمت راست صفحه تحت بخش Google برای بخش iOS مشاهده خواهید کرد. معیارها شامل اطلاعات زیر است:

• تعداد درخواست های تأیید شده - درخواستهایی که دارای یک برنامه بررسی معتبر هستند. پس از فعال کردن اجرای برنامه ، فقط درخواست ها در این گروه موفق می شوند.
• تعداد درخواست های تأیید نشده: درخواست های مشتری منسوخ احتمالاً - درخواست های از دست دادن یک برنامه چک برنامه. این درخواست ممکن است از نسخه قدیمی برنامه شما باشد که شامل اجرای برنامه چک برنامه نمی شود.
• تعداد درخواست های تأیید نشده: درخواست های مبدأ ناشناخته - درخواست های از دست رفته یک برنامه چک برنامه که به نظر نمی رسد مانند برنامه شما باشد.
• تعداد درخواست های تأیید نشده: درخواست های نامعتبر - درخواست هایی با نشانه چک برنامه نامعتبر ، که ممکن است از یک مشتری غیرمجاز باشد که سعی در جعل هویت برنامه شما یا از محیط های شبیه سازی شده دارد.

این معیارها را مرور کنید تا درک کنید که چگونه اجرای برنامه اجرای برنامه بر کاربران شما تأثیر می گذارد.

برای اجرای بررسی برنامه ، روی دکمه اجرای کلیک کنید و انتخاب خود را تأیید کنید. پس از فعال شدن اجرای ، تمام درخواست های تأیید نشده از مشتری شما رد می شوند.

توجه : پس از فعال کردن اجرای ، می تواند تا 15 دقیقه طول بکشد تا تغییرات عملی شود.

برنامه Unenforce برای مشتری iOS خود را بررسی کنید

بررسی برنامه های غیرقابل اجرا برای برنامه شما متوقف خواهد شد و تمام درخواست های مشتری شما را به نقاط پایانی Google OAuth 2.0 ، از جمله درخواست های تأیید نشده اجازه می دهد.

برای بررسی برنامه UneNforce برای مشتری iOS خود ، به نمای ویرایش مشتری iOS بروید و روی دکمه UnenForce کلیک کرده و انتخاب خود را تأیید کنید.

توجه : پس از بررسی برنامه های غیرقابل اجرا ، می تواند تا 15 دقیقه طول بکشد تا تغییرات عملی شود.

برنامه را برای مشتری iOS خود غیرفعال کنید

غیرفعال کردن برنامه برای برنامه شما ، تمام نظارت و اجرای برنامه را متوقف می کند. به جای آن ، بررسی برنامه های غیرقابل اجرا را در نظر بگیرید تا بتوانید معیارهای مشتری خود را ادامه دهید.

برای غیرفعال کردن برنامه برای مشتری iOS خود ، به نمای ویرایش مشتری iOS بروید و مشتری OAUTH خود را از سوءاستفاده با دکمه ضامن برنامه Firebase استفاده کنید.

توجه : پس از غیرفعال کردن بررسی برنامه ، می تواند تا 15 دقیقه طول بکشد تا تغییرات عملی شود.

ادامه مطلب

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

برای اطلاعات بیشتر در مورد نحوه اجرای حفاظت از حساب متقابل و لیست کامل رویدادهای موجود ، به حساب های کاربری Protect با صفحه حفاظت از حساب متقابل مراجعه کنید.