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

استفاده از OAuth 2.0 برای دسترسی به APIهای Google

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

برای شروع، اعتبار مشتری OAuth 2.0 را از Google API Console . سپس برنامه مشتری شما یک نشانه دسترسی از سرور مجوز Google درخواست می‌کند، یک نشانه را از پاسخ استخراج می‌کند و توکن را به API Google که می‌خواهید به آن دسترسی داشته باشید ارسال می‌کند. برای نمایش تعاملی استفاده از OAuth 2.0 با Google (از جمله گزینه استفاده از اعتبار مشتری خود)، با OAuth 2.0 Playground آزمایش کنید.

این صفحه یک نمای کلی از سناریوهای مجوز OAuth 2.0 که Google پشتیبانی می کند ارائه می دهد و پیوندهایی به محتوای دقیق تر ارائه می دهد. برای جزئیات در مورد استفاده از OAuth 2.0 برای احراز هویت، به OpenID Connect مراجعه کنید.

مراحل اساسی

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

1. اعتبار OAuth 2.0 را از Google API Console.

بازدید کنید Google API Console برای به دست آوردن اعتبارنامه های OAuth 2.0 مانند شناسه مشتری و راز مشتری که هم برای Google و هم برای برنامه شما شناخته شده است. مجموعه مقادیر بر اساس نوع برنامه ای که می سازید متفاوت است. به عنوان مثال، یک برنامه جاوا اسکریپت به یک راز نیاز ندارد، اما یک برنامه وب سرور نیاز دارد.

شما باید یک سرویس گیرنده OAuth مناسب برای پلتفرمی که برنامه شما در آن اجرا می شود ایجاد کنید، به عنوان مثال:

برای برنامه های وب سمت سرور یا جاوا اسکریپت از نوع کلاینت «وب» استفاده کنید. از این نوع کلاینت برای هیچ برنامه دیگری مانند برنامه های بومی یا تلفن همراه استفاده نکنید.
برای برنامه‌های Android ، از نوع کلاینت «Android» استفاده کنید.
برای برنامه‌های iOS و macOS ، از نوع کلاینت «iOS» استفاده کنید.
برای برنامه‌های Universal Windows Platform ، از نوع کلاینت «Universal Windows Platform» استفاده کنید.
برای دستگاه‌های ورودی محدود ، مانند تلویزیون یا دستگاه‌های جاسازی شده، از نوع کلاینت «تلویزیون‌ها و دستگاه‌های ورودی محدود» استفاده کنید.
برای تعاملات سرور به سرور ، از حساب‌های سرویس استفاده کنید.

2. یک رمز دسترسی از سرور مجوز Google دریافت کنید.

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

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

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

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

به طور کلی بهترین روش این است که دامنه ها را به صورت تدریجی، در زمانی که دسترسی لازم است، درخواست کنید، نه از قبل. برای مثال، برنامه‌ای که می‌خواهد از ذخیره یک رویداد در تقویم پشتیبانی کند، نباید تا زمانی که کاربر دکمه «افزودن به تقویم» را فشار دهد، درخواست دسترسی به تقویم Google را بدهد. مجوز افزایشی را ببینید.

3. دامنه دسترسی اعطا شده توسط کاربر را بررسی کنید.

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

دامنه موجود در درخواست شما ممکن است با محدوده موجود در پاسخ شما مطابقت نداشته باشد، حتی اگر کاربر تمام محدوده های درخواستی را اعطا کرده باشد. برای دامنه های مورد نیاز برای دسترسی، به اسناد مربوط به هر API Google مراجعه کنید. یک API ممکن است چندین مقدار رشته دامنه را به یک محدوده دسترسی نگاشت کند و رشته محدوده یکسانی را برای همه مقادیر مجاز در درخواست بازگرداند. مثال: وقتی برنامه‌ای از کاربر درخواست می‌کند تا محدوده https://www.google.com/m8/feeds/ را مجوز دهد، Google People API ممکن است دامنه‌ای از https://www.googleapis.com/auth/contacts را برگرداند. روش Google People API people.updateContact به یک محدوده اختصاصی https://www.googleapis.com/auth/contacts نیاز دارد.

4. رمز دسترسی را به یک API ارسال کنید.

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

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

5. در صورت لزوم رمز دسترسی را بازخوانی کنید.

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

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

سناریوها

برنامه های کاربردی وب سرور

نقطه پایانی Google OAuth 2.0 از برنامه های سرور وب که از زبان ها و چارچوب هایی مانند PHP، Java، Go، Python، Ruby و ASP.NET استفاده می کنند، پشتیبانی می کند.

توالی مجوز زمانی شروع می شود که برنامه شما یک مرورگر را به یک URL Google هدایت می کند. URL شامل پارامترهای پرس و جو است که نوع دسترسی مورد درخواست را نشان می دهد. Google احراز هویت کاربر، انتخاب جلسه و رضایت کاربر را کنترل می کند. نتیجه یک کد مجوز است که برنامه می‌تواند آن را با یک نشانه دسترسی و یک نشانه تازه‌سازی مبادله کند.

برنامه باید رمز به‌روزرسانی را برای استفاده در آینده ذخیره کند و از نشانه دسترسی برای دسترسی به Google API استفاده کند. پس از انقضای نشانه دسترسی، برنامه از توکن رفرش برای به دست آوردن یک نشانه جدید استفاده می کند.

برنامه شما یک درخواست رمز به سرور مجوز Google ارسال می‌کند، یک کد مجوز دریافت می‌کند، کد را با یک نشانه مبادله می‌کند و از آن برای فراخوانی یک نقطه پایانی Google API استفاده می‌کند.

برای جزئیات، به استفاده از OAuth 2.0 برای برنامه های وب سرور مراجعه کنید.

برنامه های نصب شده

نقطه پایانی Google OAuth 2.0 از برنامه‌هایی پشتیبانی می‌کند که روی دستگاه‌هایی مانند رایانه، دستگاه‌های تلفن همراه و تبلت‌ها نصب می‌شوند. هنگامی که یک شناسه مشتری از طریق ایجاد می کنید Google API Console ، مشخص کنید که این یک برنامه نصب شده است، سپس Android، برنامه Chrome، iOS، Universal Windows Platform (UWP) یا برنامه Desktop را به عنوان نوع برنامه انتخاب کنید.

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

برای جزئیات، به استفاده از OAuth 2.0 برای برنامه های نصب شده مراجعه کنید.

برنامه های کاربردی سمت کلاینت (جاوا اسکریپت).

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

نتیجه یک نشانه دسترسی است که مشتری باید قبل از گنجاندن آن در درخواست Google API آن را تأیید کند. زمانی که توکن منقضی می شود، برنامه این فرآیند را تکرار می کند.

برنامه JS شما یک درخواست توکن به سرور مجوز Google ارسال می کند، یک نشانه دریافت می کند، رمز را تأیید می کند و از آن برای فراخوانی یک نقطه پایانی Google API استفاده می کند.

برای جزئیات، به استفاده از OAuth 2.0 برای برنامه های سمت مشتری مراجعه کنید.

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

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

توالی مجوز با درخواست سرویس وب توسط برنامه برای یک کد مجوز به یک URL Google آغاز می شود. پاسخ شامل چندین پارامتر از جمله URL و کدی است که برنامه به کاربر نشان می دهد.

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

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

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

برای جزئیات، به استفاده از OAuth 2.0 برای دستگاه ها مراجعه کنید.

حساب های خدماتی

API های Google مانند Prediction API و Google Cloud Storage می توانند از طرف برنامه شما بدون دسترسی به اطلاعات کاربر عمل کنند. در این مواقع برنامه شما باید هویت خود را به API ثابت کند، اما رضایت کاربر لازم نیست. به طور مشابه، در سناریوهای سازمانی، برنامه شما می تواند درخواست دسترسی تفویض شده به برخی منابع را داشته باشد.

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

توجه: این سناریوهای حساب سرویس به برنامه‌ها برای ایجاد و امضای رمزنگاری شده JSON Web Tokens (JWT) نیاز دارند. ما قویاً شما را به استفاده از کتابخانه برای انجام این وظایف تشویق می کنیم. اگر این کد را بدون استفاده از کتابخانه ای که ایجاد و امضای توکن را انتزاعی می کند، بنویسید، ممکن است خطاهایی را مرتکب شوید که تأثیر شدیدی بر امنیت برنامه شما داشته باشد. برای فهرستی از کتابخانه‌هایی که از این سناریو پشتیبانی می‌کنند، به مستندات حساب سرویس مراجعه کنید.

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

برنامه سرور شما از JWT برای درخواست توکن از سرور مجوز Google استفاده می‌کند، سپس از این رمز برای فراخوانی یک نقطه پایانی Google API استفاده می‌کند. هیچ کاربر نهایی درگیر نیست.

برای جزئیات، به مستندات حساب سرویس مراجعه کنید.

اندازه توکن

توکن‌ها می‌توانند از نظر اندازه متفاوت باشند، تا محدودیت‌های زیر:

کدهای مجوز: 256 بایت
توکن های دسترسی: 2048 بایت
نشانه های تازه سازی: 512 بایت

توکن‌های دسترسی که توسط API سرویس توکن امنیتی Google Cloud بازگردانده می‌شوند، مشابه ساختارهای دسترسی Google API OAuth 2.0 هستند، اما محدودیت‌های اندازه توکن متفاوتی دارند. برای جزئیات، به مستندات API مراجعه کنید.

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

بازخوانی انقضای رمز

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

کاربر دسترسی برنامه شما را لغو کرده است.
توکن رفرش شش ماه است که استفاده نشده است.
کاربر گذرواژه‌ها را تغییر داده و رمز تازه‌سازی شامل دامنه‌های Gmail است.
حساب کاربری از حداکثر تعداد نشانه‌های تازه‌سازی اعطا شده (زنده) فراتر رفته است.
اگر سرپرست هر یک از سرویس‌های درخواست شده در محدوده برنامه شما را روی «محدود» تنظیم کند (خطا admin_policy_enforced است).
برای APIهای Google Cloud Platform - ممکن است از طول جلسه تعیین شده توسط سرپرست بیشتر شده باشد.

یک پروژه Google Cloud Platform با صفحه رضایت OAuth پیکربندی شده برای یک نوع کاربر خارجی و وضعیت انتشار "آزمایش" یک نشانه به‌روزرسانی صادر می‌کند که طی 7 روز منقضی می‌شود، مگر اینکه تنها دامنه‌های OAuth درخواستی زیرمجموعه‌ای از نام، آدرس ایمیل و نمایه کاربر (از طریق userinfo.email, userinfo.profile, openid scopes یا معادل های OpenID Connect آنها).

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

همچنین محدودیت بیشتری برای تعداد کل نشانه‌های تازه‌سازی وجود دارد که یک حساب کاربری یا حساب سرویس می‌تواند در همه مشتریان داشته باشد. اکثر کاربران عادی از این حد تجاوز نمی‌کنند، اما حساب توسعه‌دهنده که برای آزمایش پیاده‌سازی استفاده می‌شود ممکن است.

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

برخورد با خط‌مشی‌های کنترل جلسه برای سازمان‌های Google Cloud Platform (GCP).

مدیران سازمان‌های GCP ممکن است نیاز به احراز هویت مجدد مکرر کاربران در حین دسترسی به منابع GCP با استفاده از ویژگی کنترل جلسه Google Cloud داشته باشند. این خط‌مشی بر دسترسی به Google Cloud Console، Google Cloud SDK (همچنین به عنوان gcloud CLI شناخته می‌شود) و هر برنامه OAuth شخص ثالثی که به محدوده پلتفرم Cloud نیاز دارد، تأثیر می‌گذارد. اگر کاربر یک خط‌مشی کنترل جلسه برقرار کرده باشد، پس از انقضای مدت جلسه، فراخوانی‌های API شما با خطای مشابهی مواجه می‌شوند که در صورت ابطال نشانه تازه‌سازی اتفاق می‌افتد - تماس با نوع خطای invalid_grant ناموفق خواهد بود. از فیلد error_subtype می توان برای تمایز بین یک نشانه ابطال شده و یک شکست ناشی از خط مشی کنترل جلسه استفاده کرد (به عنوان مثال، "error_subtype": "invalid_rapt" ). از آنجایی که مدت‌زمان جلسه می‌تواند بسیار محدود باشد (بین 1 ساعت تا 24 ساعت)، این سناریو باید با راه‌اندازی مجدد جلسه احراز هویت، به خوبی مدیریت شود.

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

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

کتابخانه های مشتری

کتابخانه های مشتری زیر با فریم ورک های محبوب ادغام می شوند که اجرای OAuth 2.0 را ساده تر می کند. ویژگی های بیشتری به مرور زمان به کتابخانه ها اضافه خواهد شد.