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

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

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

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

مراحل اساسی

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

1. اخذ OAuth تأیید 2.0 اعتبار از Google API Console.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

سناریوها

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

برای جزئیات، با استفاده از OAuth 2.0 برای برنامه های کاربردی Client-side را .

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

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

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

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

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

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

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

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

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

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

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

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

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

اندازه توکن

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

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

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

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

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

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

  • کاربر با دسترسی برنامه خود را لغو .
  • توکن رفرش شش ماه است که استفاده نشده است.
  • کاربر گذرواژه‌ها را تغییر داده و رمز تازه‌سازی شامل دامنه‌های Gmail است.
  • حساب کاربری از حداکثر تعداد نشانه‌های تازه‌سازی اعطا شده (زنده) فراتر رفته است.
  • کاربر متعلق به یک سازمان Google Cloud Platform است که دارای خط‌مشی‌های کنترل جلسه است.

برای یک پروژه Google Cloud Platform با صفحه رضایت OAuth که برای نوع کاربر خارجی پیکربندی شده و وضعیت انتشار «آزمایش» است، یک نشانه به‌روزرسانی صادر می‌شود که 7 روز دیگر منقضی می‌شود.

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

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

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

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

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

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

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

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

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