این سند توضیح میدهد که چگونه برنامههای نصبشده در دستگاههایی مانند تلفنها، تبلتها و رایانهها از نقاط پایانی 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 ها را برای پروژه خود فعال کنید
هر برنامهای که Google API را فراخوانی میکند، باید آن 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 اپ استور اپل وجود دارد.
- برنامه Apple App Store را در دستگاه iOS یا iPadOS خود باز کنید.
- اپلیکیشن خود را جستجو کنید.
- دکمه اشتراک گذاری (نماد مربع و فلش رو به بالا) را انتخاب کنید.
- کپی پیوند را انتخاب کنید.
- پیوند را در یک ویرایشگر متن قرار دهید. شناسه فروشگاه 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 تغییر مسیر را از بین می برد.
نحوه مهاجرت به Google Sign-In for Android SDK
اگر در حال حاضر از یک طرح سفارشی برای ادغام OAuth خود در Android استفاده میکنید، برای انتقال کامل به استفاده از Google Sign-In توصیهشده برای Android SDK، باید اقدامات زیر را انجام دهید:
- کد خود را برای استفاده از Google Sign-In SDK به روز کنید.
- پشتیبانی از طرح سفارشی را در Google API Console غیرفعال کنید.
مراحل زیر را برای انتقال به Google Sign-In Android SDK دنبال کنید:
- کد خود را برای استفاده از Google Sign-In Android SDK به روز کنید:
- کد خود را بررسی کنید تا مشخص کنید کجا درخواستی را به سرور 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
مراجعه کنید. - پارامترهای
scope
وclient_id
درخواست را که برای پیکربندی Google Sign-In SDK نیاز دارید، یادداشت کنید. - برای راهاندازی SDK، دستورالعملهای Start Integrating Google Sign-In را در برنامه Android خود دنبال کنید. میتوانید از مرحله دریافت شناسه مشتری OAuth 2.0 سرور باطن خود صرفنظر کنید، همانطور که از
client_id
که از مرحله قبل بازیابی کردهاید دوباره استفاده میکنید. - دستورالعملهای دسترسی به API سمت سرور را دنبال کنید. این شامل مراحل زیر است:
- از روش
getServerAuthCode
برای بازیابی یک کد اعتبار برای محدوده هایی که درخواست مجوز می کنید استفاده کنید. - کد احراز هویت را به پشتیبان برنامه خود ارسال کنید تا آن را با رمز دسترسی و بازخوانی مبادله کنید.
- از نشانه دسترسی بازیابی شده برای برقراری تماس با Google API از طرف کاربر استفاده کنید.
- از روش
- کد خود را بررسی کنید تا مشخص کنید کجا درخواستی را به سرور OAuth 2.0 Google ارسال می کنید . اگر از یک طرح سفارشی استفاده می کنید، درخواست شما به شکل زیر خواهد بود:
- غیرفعال کردن پشتیبانی از طرح سفارشی در Google API Console:
- به لیست اعتبارنامه OAuth 2.0 بروید و کلاینت Android خود را انتخاب کنید.
- به بخش تنظیمات پیشرفته بروید، تیک گزینه Enable Custom URI Scheme را بردارید و برای غیرفعال کردن پشتیبانی از طرح URI سفارشی، روی Save کلیک کنید.
فعال کردن طرح URI سفارشی
اگر جایگزین توصیه شده برای شما کار نمی کند، می توانید با دنبال کردن دستورالعمل های زیر، طرح های URI سفارشی را برای مشتری Android خود فعال کنید:- به لیست اعتبارنامه OAuth 2.0 بروید و کلاینت Android خود را انتخاب کنید.
- به بخش Advanced Settings بروید، چک باکس Enable Custom URI Scheme را علامت بزنید و Save را کلیک کنید تا پشتیبانی از طرح URI سفارشی فعال شود.
از 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). |
مقادیر فرم | نوع برنامه را روی برنامه دسکتاپ تنظیم کنید. |
کپی/پیست دستی
محدوده های دسترسی را شناسایی کنید
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 (بدون بالشتک) تأییدکننده کد است.
|
ساده | چالش کد همان مقدار تأیید کننده کد تولید شده در بالا است.
|
مرحله 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 مجاز مطابقت نداشته باشد، یک خطای جدول زیر مقدار پارامتر
| ||||||
response_type | مورد نیاز تعیین می کند که آیا نقطه پایانی Google OAuth 2.0 یک کد مجوز را برمی گرداند یا خیر. مقدار پارامتر را روی | ||||||
scope | مورد نیاز فهرستی از محدودههای محدود شده با فضا که منابعی را که برنامه شما میتواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی میکند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد. Scopes به برنامه شما امکان میدهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر میسازد تا میزان دسترسی را که به برنامه شما میدهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد. | ||||||
code_challenge | توصیه می شود یک | ||||||
code_challenge_method | توصیه می شود مشخص می کند که از چه روشی برای رمزگذاری یک | ||||||
state | توصیه می شود هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند. سرور مقدار دقیقی را که شما به عنوان یک جفت شما می توانید از این پارامتر برای اهداف مختلفی مانند هدایت کاربر به منبع صحیح در برنامه خود، ارسال nonces و کاهش جعل درخواست بین سایتی استفاده کنید. از آنجایی که | ||||||
login_hint | اختیاری اگر برنامه شما بداند که کدام کاربر در حال تلاش برای احراز هویت است، میتواند از این پارامتر برای ارائه راهنمایی به سرور احراز هویت Google استفاده کند. سرور از راهنمایی برای ساده سازی جریان ورود استفاده می کند یا با پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چند ورود مناسب. مقدار پارامتر را به آدرس ایمیل یا شناسه |
نمونه URL های مجوز
برگه های زیر نمونه URL های مجوز را برای گزینه های مختلف URI تغییر مسیر نشان می دهد.
URL ها به جز مقدار پارامتر redirect_uri
یکسان هستند. URL ها همچنین حاوی پارامترهای response_type
و client_id
مورد نیاز و همچنین پارامتر state
اختیاری هستند. هر URL حاوی خطوط شکسته و فاصله برای خوانایی است.
طرح URI سفارشی
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2F1.800.gay%3A443%2Fhttps%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=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2F1.800.gay%3A443%2Fhttps%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 تنظیم می شود. |
قطعه زیر یک نمونه پاسخ را نشان می دهد:
{ "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 ترجیح داده می شود، زیرا رشته های پرس و جو در گزارش های سرور قابل مشاهده هستند. در بیشتر موارد میتوانید از کتابخانه سرویس گیرنده برای تنظیم تماسهای خود با APIهای Google استفاده کنید (مثلاً هنگام تماس با 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 بهترین تمرین فعلی 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 با صفحه حفاظت از حساب متقابل مراجعه کنید.