این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

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

جایگزین، گزینه ها

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

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

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

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

پیش نیازها

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

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

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

Open the API Library در Google API Console.
If prompted, select a project, or create a new one.
API Library همه API های موجود را فهرست می کند که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند. اگر API که می‌خواهید فعال کنید در لیست قابل مشاهده نیست، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
API را که می خواهید فعال کنید انتخاب کنید، سپس روی دکمه Enable کلیک کنید.
If prompted, enable billing.
If prompted, read and accept the API's Terms of Service.

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

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

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

اندروید

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

iOS

نوع برنامه iOS را انتخاب کنید.
یک نام برای مشتری OAuth وارد کنید. این نام در Credentials page پروژه شما نمایش داده می شود تا مشتری را شناسایی کند.
شناسه بسته نرم افزاری خود را وارد کنید. شناسه بسته مقدار کلید CFBundleIdentifier در فایل منبع فهرست دارایی اطلاعات برنامه شما ( info.plist ) است. این مقدار معمولاً در قسمت General یا پانل Signing & Capabilities در ویرایشگر پروژه Xcode نمایش داده می شود. شناسه بسته نرم افزاری همچنین در بخش اطلاعات عمومی صفحه اطلاعات برنامه برای برنامه در سایت App Store Connect Apple نمایش داده می شود.
(اختیاری)
اگر برنامه در اپ استور اپل منتشر شده است، شناسه App Store برنامه خود را وارد کنید. شناسه فروشگاه یک رشته عددی است که در هر URL اپ استور اپل وجود دارد.
1. برنامه Apple App Store را در دستگاه iOS یا iPadOS خود باز کنید.
2. برنامه خود را جستجو کنید.
3. دکمه اشتراک گذاری (نماد مربع و فلش رو به بالا) را انتخاب کنید.
4. کپی پیوند را انتخاب کنید.
5. پیوند را در یک ویرایشگر متن قرار دهید. شناسه فروشگاه App آخرین قسمت URL است.
  مثال: https://apps.apple.com/app/google/id 284815942
(اختیاری)
شناسه تیم خود را وارد کنید. برای اطلاعات بیشتر به شناسه تیم خود در مستندات حساب توسعه دهنده اپل مراجعه کنید.
روی ایجاد کلیک کنید.

UWP

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

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

طرح URI سفارشی (اندروید، iOS، UWP)

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

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

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

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

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

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

کد خود را برای استفاده از 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 سمت سرویس گیرنده ، این دستورالعمل ها را دنبال کنید.
غیرفعال کردن پشتیبانی از طرح سفارشی در Google API Console:
1. به لیست اعتبارنامه OAuth 2.0 بروید و کلاینت Android خود را انتخاب کنید.
2. به بخش تنظیمات پیشرفته بروید، تیک گزینه Enable Custom URI Scheme را بردارید و برای غیرفعال کردن پشتیبانی از طرح URI سفارشی، روی Save کلیک کنید.

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

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

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

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

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

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

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

اندروید

برای تکمیل فرآیند تأیید، اگر حساب برنامه‌نویس 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 همگام‌سازی شده باشد. درباره همگام‌سازی فهرست عضویت ناشر خود بیشتر بیاموزید .

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

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

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

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

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

کپی/پیست دستی

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

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

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

سند 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 معمولی متفاوت است.

آدرس 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 به برنامه شما امکان می‌دهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر می‌سازد تا میزان دسترسی را که به برنامه شما می‌دهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد.

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 مراجعه کنید.

login_hint

اختیاری

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

مقدار پارامتر را به آدرس ایمیل یا شناسه sub که معادل شناسه گوگل کاربر است تنظیم کنید.

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

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

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

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

مرحله 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` تنظیم می شود.

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

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

فراخوانی Google API

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

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

نمونه های HTTP GET

تماس با نقطه پایانی drive.files (API فایل‌های Drive) با استفاده از هدر HTTP Authorization: Bearer ممکن است به شکل زیر باشد. توجه داشته باشید که باید رمز دسترسی خود را مشخص کنید:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

نمونه های `curl`

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

توکن‌های دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای یک درخواست 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",
  "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 به همراه یک کد خطا برگردانده می شود.

بیشتر خواندن

IETF Best Current Practice OAuth 2.0 for Native Apps بسیاری از بهترین شیوه های مستند شده در اینجا را ایجاد می کند.

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

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

پیش نیازها

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

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

اندروید

iOS

UWP

طرح URI سفارشی (اندروید، iOS، UWP)

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

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

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

اندروید

کروم

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

کپی/پیست دستی

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

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

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

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

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

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

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

طرح URI سفارشی

آدرس IP Loopback

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

خطاها

admin_policy_enforced

disallowed_useragent

اندروید

iOS

org_internal

invalid_grant

redirect_uri_mismatch

invalid_request

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

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

فراخوانی Google API

نمونه های HTTP GET

نمونه های curl

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

باطل کردن یک نشانه

بیشتر خواندن

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

نمونه های `curl`