استفاده از 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 مناسب برای پلتفرمی که برنامه شما در آن اجرا می شود ایجاد کنید، به عنوان مثال:

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

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

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

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

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

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

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

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

دامنه موجود در درخواست شما ممکن است با محدوده موجود در پاسخ شما مطابقت نداشته باشد، حتی اگر کاربر تمام محدوده های درخواستی را اعطا کرده باشد. برای دامنه های مورد نیاز برای دسترسی، به اسناد مربوط به هر API Google مراجعه کنید. یک API ممکن است چندین مقدار رشته دامنه را به یک محدوده دسترسی نگاشت کند و رشته محدوده یکسانی را برای همه مقادیر مجاز در درخواست بازگرداند. مثال: وقتی برنامه‌ای از کاربر درخواست می‌کند تا محدوده https://www.googleapis.com/auth/contacts را مجوز دهد، Google People API ممکن است دامنه‌ای از https://www.google.com/m8/feeds/ را برگرداند. روش 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 را به عنوان نوع برنامه انتخاب کنید.

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

توالی مجوز زمانی شروع می شود که برنامه شما یک مرورگر را به یک 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 برای برنامه های سمت مشتری مراجعه کنید.

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

نقطه پایانی 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دریافت می‌کنید، شامل یک آدرس ایمیل تولید شده که منحصر به فرد است، یک شناسه مشتری و حداقل یک جفت کلید عمومی/خصوصی است. شما از شناسه مشتری و یک کلید خصوصی برای ایجاد یک JWT امضا شده و ایجاد یک درخواست نشانه دسترسی در قالب مناسب استفاده می کنید. سپس برنامه شما درخواست توکن را به سرور مجوز Google OAuth 2.0 ارسال می کند که یک رمز دسترسی را برمی گرداند. این برنامه از توکن برای دسترسی به API Google استفاده می کند. زمانی که توکن منقضی می شود، برنامه این فرآیند را تکرار می کند.

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

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

اندازه توکن

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

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

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

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

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

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

یک پروژه 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 را ساده تر می کند. ویژگی های بیشتری به مرور زمان به کتابخانه ها اضافه خواهد شد.