میاناهای برنامه‌سازی کاربردی Google از پروتکل OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کنند. Google از سناریوهای رایج OAuth 2.0 مانند سناریوهای مربوط به سرور وب، سمت کارخواه، نصب‌شده، و برنامه‌های دستگاه با ورودی محدود پشتیبانی می‌کند.
برای شروع، اطلاعات کاربری مشتری OAuth 2.0 را از کنسول Google API دریافت کنید. سپس برنامه کارخواه شما یک کد دسترسی از «سرور مجوز Google» درخواست می‌کند، کدی را از پاسخ استخراج می‌کند، و کد را به Google API که می‌خواهید به آن دسترسی داشته باشید ارسال می‌کند. برای نمایش تعاملی استفاده از OAuth 2.0 با Google (ازجمله گزینه استفاده از اطلاعات کاربری مشتری خودتان)، با OAuth 2.0 Playground آزمایش کنید.
این صفحه نمای کلی از سناریوهای مجوز OAuth 2.0 را که Google پشتیبانی می‌کند ارائه می‌دهد، و پیوندهایی به محتوای دقیق‌تر ارائه می‌دهد. برای جزئیات بیشتر درباره استفاده از OAuth 2.0 برای اصالت‌سنجی، به OpenID Connect مراجعه کنید.
مراحل اولیه
همه برنامه‌ها هنگام دسترسی به Google API بااستفاده از OAuth 2.0 از الگوی پایه‌ای پیروی می‌کنند. در سطح بالا، پنج مرحله را دنبال می‌کنید:
۱. اعتبارنامه OAuth 2.0 را از «کنسول Google API» دریافت کنید.
برای دریافت اطلاعات کاربری OAuth 2.0، مانند شناسه کارخواه و رمز کارخواه که هم برای Google و هم برای برنامه شما شناخته‌شده هستند، به کنسول Google API مراجعه کنید. مجموعه مقادیر بسته به نوع برنامه‌ای که می‌سازید متفاوت است. برای مثال، برنامه جاوا اسکریپت به رمز نیاز ندارد، اما برنامه کارساز وب به رمز نیاز دارد.
باید کارخواه OAuth مناسبی برای پلاتفرمی که برنامه‌تان در آن اجرا خواهد شد ایجاد کنید، برای مثال:
- برای برنامه‌های Android، از نوع برنامه Android استفاده کنید.
-
برای برنامه‌های iOS، از
نوع برنامه iOS استفاده کنید.
- desktop_windows برای برنامه‌های رایانه‌ای (مانند برنامه‌های Windows، macOS، یا Linux یا ابزارهای CLI)، از نوع برنامه برنامه رایانه‌ای استفاده کنید.
- کد برای سمت سرور یا برنامه‌های وب جاوا اسکریپت از نوع برنامه برنامه وب استفاده کنید. از این نوع برنامه برای هیچ برنامه دیگری، مثل برنامه‌های بومی یا تلفن همراه، استفاده نکنید.
- chrome_extension برای افزونه‌های Chrome، از نوع برنامه افزونه Chrome استفاده کنید.
- tv برای دستگاه‌های ورودی محدود، مثل تلویزیون یا دستگاه‌های جاسازی‌شده، از نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود استفاده کنید.
- میزبان برای تعاملات سرور به سرور، از حساب‌های سرویس استفاده کنید. به «شناسه کارخواه» OAuth نیازی نیست.
۲. یک کد دسترسی از سرور مجوز Google دریافت کنید.
قبل‌از اینکه برنامه شما بتواند بااستفاده از Google API به داده‌های خصوصی دسترسی پیدا کند، باید
یک کد دسترسی دریافت کند که دسترسی به آن API را اعطا می‌کند. یک کد دسترسی واحد می‌تواند سطوح مختلفی از دسترسی به چندین میانای برنامه‌سازی کاربردی را اعطا کند. پارامتر متغیری به‌نام scope مجموعه منابع و عملیاتی را که کد دسترسی مجاز می‌کند کنترل می‌کند. درطول درخواست کد دسترسی،
برنامه شما یک یا چند مقدار در پارامتر scope ارسال می‌کند.
چندین روش برای ایجاد این درخواست وجود دارد و این روش‌ها براساس نوع برنامه‌ای که می‌سازید متفاوت است. برای مثال، یک برنامه جاوا اسکریپت ممکن است بااستفاده از تغییر مسیر مرورگر به Google، کد دسترسی درخواست کند، درحالی‌که برنامه‌ای که در دستگاهی بدون مرورگر نصب شده است از درخواست‌های سرویس وب استفاده می‌کند. برای کسب اطلاعات بیشتر درباره نحوه درخواست، Scenarios و راهنماهای دقیق پیاده‌سازی برای هر نوع برنامه را ببینید.
برخی‌از درخواست‌ها به مرحله اصالت‌سنجی نیاز دارند که در آن کاربر با حساب Google خود به سیستم وارد می‌شود. پس‌از ورود به سیستم، از کاربر پرسیده می‌شود که آیا مایل است یک یا چند اجازه‌ای را که برنامه شما درخواست می‌کند اعطا کند یا نه. این فرایند موافقت کاربر نامیده می‌شود.
اگر کاربر حداقل یک اجازه را اعطا کند، «سرور مجوز Google» یک کد دسترسی (یا کد مجوزی که برنامه‌تان می‌تواند برای دریافت کد دسترسی استفاده کند) و فهرستی از دامنه‌های دسترسی اعطاشده توسط آن کد را به برنامه‌تان ارسال می‌کند. اگر کاربر اجازه را اعطا نکند، سرور خطایی برمی‌گرداند.
به‌طور کلی، بهترین روش این است که دامنه‌ها را به‌صورت افزایشی و در زمان نیاز به دسترسی درخواست کنید، نه از ابتدا. برای مثال، برنامه‌ای که می‌خواهد از ذخیره کردن رویداد در تقویم پشتیبانی کند نباید تا زمانی که کاربر دکمه «افزودن به تقویم» را فشار نداده است، درخواست دسترسی به «تقویم Google» کند؛ مجوزدهی افزایشی را ببینید.
۳. حوزه‌های دسترسی اعطاشده توسط کاربر را بررسی کنید.
گستره‌های موجود در پاسخ کد دسترسی را با گستره‌های موردنیاز برای دسترسی به ویژگی‌ها و عملکردهای برنامه‌تان که به دسترسی به Google API مربوطه وابسته است مقایسه کنید. هر ویژگی‌ای از برنامه‌تان را که بدون دسترسی به API مربوطه نمی‌تواند کار کند غیرفعال کنید.
ممکن است دامنه موجود در درخواست شما با دامنه موجود در پاسخ شما مطابقت نداشته باشد، حتی
اگر کاربر همه دامنه‌های درخواستی را اعطا کرده باشد. برای دامنه‌های موردنیاز برای دسترسی، به مستندات هر Google API مراجعه کنید. یک API ممکن است چندین مقدار رشته دامنه را به یک دامنه دسترسی نگاشت کند و همان رشته دامنه را برای همه مقادیر مجاز در درخواست برگرداند.
مثال: Google People API ممکن است وقتی برنامه‌ای از کاربر درخواست می‌کند
گستره https://www.google.com/m8/feeds/ را مجاز کند، گستره
https://www.googleapis.com/auth/contacts را برگرداند؛ روش Google People API
people.updateContact
به گستره اعطاشده https://www.googleapis.com/auth/contacts نیاز دارد.
۴. کد دسترسی را به میانای برنامه‌سازی کاربردی ارسال کنید.
پس‌از اینکه برنامه کد دسترسی را دریافت کرد، آن کد را در سرصفحه درخواست «مجوز HTTP» به Google API ارسال می‌کند. می‌توانید توکن‌ها را به‌عنوان پارامترهای رشته پُرسمان URI ارسال کنید، اما این کار را توصیه نمی‌کنیم، زیرا پارامترهای URI ممکن است در فایل‌های گزارشی قرار بگیرند که کاملاً امن نیستند. همچنین، اجتناب از ایجاد نام‌های پارامتر URI غیرضروری، از روش‌های خوب REST است.
کدهای دسترسی فقط برای مجموعه عملیات و منابع شرح‌داده‌شده در
scope درخواست کد معتبر هستند. برای مثال، اگر کد دسترسی برای Google Calendar API صادر شود، دسترسی به Google Contacts API را اعطا نمی‌کند. بااین‌حال، می‌توانید
آن کد دسترسی را چندین بار برای عملیات مشابه به Google Calendar API ارسال کنید.
۵. درصورت لزوم، کد دسترسی را بازآوری کنید.
کدهای دسترسی طول عمر محدودی دارند. اگر برنامه شما نیاز به دسترسی به Google API فراتر از طول عمر یک کد دسترسی دارد، می‌تواند کد بازآوری دریافت کند. ژتون بازآوری به برنامه شما اجازه می‌دهد کدهای دسترسی جدید دریافت کند.
وضعیت‌ها
این سناریوها نحوه استفاده از OAuth 2.0 را برای درخواست کدهای صدور مجوز و دریافت ژتون‌های دسترسی و بازآوری برای انواع مختلف برنامه‌ها شرح می‌دهند.
برنامه‌های سرور وب
نقطه پایانی Google OAuth 2.0 از برنامه‌های سرور وب که از زبان‌ها و چارچوب‌هایی مانند PHP، Java، Go، Python، Ruby، و ASP.NET استفاده می‌کنند پشتیبانی می‌کند.
توالی مجوز زمانی آغاز می‌شود که برنامه شما مرورگری را به نشانی وب Google هدایت می‌کند؛ نشانی وب شامل پارامترهای پرسمانی است که نوع دسترسی درخواستی را نشان می‌دهد. Google اصالت‌سنجی کاربر، انتخاب جلسه، و رضایت کاربر را مدیریت می‌کند. نتیجه یک کد مجوز است که برنامه می‌تواند آن را با کد دسترسی و ژتون بازآوری معاوضه کند.
برنامه باید ژتون بازآوری را برای استفاده در آینده ذخیره کند و از کد دسترسی برای دسترسی به Google API استفاده کند. وقتی کد دسترسی منقضی می‌شود، برنامه از ژتون بازآوری برای دریافت کد جدید استفاده می‌کند.
برای جزئیات، به استفاده از OAuth 2.0 برای برنامه‌های وب سرور مراجعه کنید.
برنامه‌های کاربردی نصب شده
نقطه پایانی Google OAuth 2.0 از برنامه‌هایی که در دستگاه‌هایی مانند رایانه، دستگاه همراه، و رایانه لوحی نصب شده‌اند پشتیبانی می‌کند. وقتی شناسه مشتری را ازطریق کنسول Google API ایجاد می‌کنید، مشخص کنید که این برنامه نصب‌شده است، سپس Android، افزونه Chrome، iOS، یا برنامه رایانه‌ای را به‌عنوان نوع برنامه انتخاب کنید.
این فرایند به شناسه کارخواه و در برخی موارد به رمز کارخواه منجر می‌شود که آن را در کد منبع برنامه‌تان جاسازی می‌کنید. (در این زمینه، رمز کارخواه آشکارا به‌عنوان رمز درنظر گرفته نمی‌شود.)
توالی مجوز زمانی آغاز می‌شود که برنامه شما مرورگری را به نشانی وب Google هدایت می‌کند؛ نشانی وب شامل پارامترهای پرسمانی است که نوع دسترسی درخواستی را نشان می‌دهد. Google اصالت‌سنجی کاربر، انتخاب جلسه، و رضایت کاربر را مدیریت می‌کند. نتیجه یک کد مجوز است که برنامه می‌تواند آن را با کد دسترسی معاوضه کند. برنامه باید کد دسترسی را قبل‌از گنجاندن آن در درخواست Google API اعتبارسنجی کند. وقتی توکن منقضی می‌شود، برنامه فرایند را تکرار می‌کند.
به‌صورت اختیاری، سرور زیرینه می‌تواند کد مجوز را با ژتون بازآوری معاوضه کند، و آن را در مکانی امن ذخیره کند. وقتی کد دسترسی منقضی می‌شود، سرور زیرینه از ژتون بازآوری برای دریافت کد جدید برای برنامه استفاده می‌کند.
برای جزئیات، به مجاز کردن دسترسی به داده‌های کاربر Google برای Android، دسترسی به Google APIs در برنامه iOS، و OAuth 2.0 برای برنامه‌های رایانه‌ای مراجعه کنید.
برنامه‌های سمت کارخواه (جاوا اسکریپت)
نقطه پایانی Google OAuth 2.0 از برنامه‌های جاوا اسکریپت که در مرورگر اجرا می‌شوند پشتیبانی می‌کند.
توالی مجوز زمانی آغاز می‌شود که برنامه شما مرورگری را به نشانی وب Google هدایت می‌کند؛ نشانی وب شامل پارامترهای پرسمانی است که نوع دسترسی درخواستی را نشان می‌دهد. Google اصالت‌سنجی کاربر، انتخاب جلسه، و رضایت کاربر را مدیریت می‌کند.
نتیجه یک کد دسترسی است که کارخواه باید قبل‌از گنجاندن آن در درخواست Google API، آن را اعتبارسنجی کند. وقتی توکن منقضی می‌شود، برنامه فرایند را تکرار می‌کند.
برای جزئیات، به استفاده از OAuth 2.0 برای برنامه‌های سمت کارخواه مراجعه کنید.
برنامه‌های کاربردی در دستگاه‌های ورودی محدود
نقطه پایانی Google OAuth 2.0 از برنامه‌هایی که در دستگاه‌های با ورودی محدود اجرا می‌شوند، مانند کنسول‌های بازی، دوربین‌های ویدیو، و چاپگرها پشتیبانی می‌کند.
توالی مجوز با درخواست سرویس وب برنامه به نشانی وب Google برای کد مجوز شروع می‌شود. پاسخ حاوی چندین پارامتر است، ازجمله نشانی وب و کدی که برنامه به کاربر نشان می‌دهد.
کاربر نشانی وب و کد را از دستگاه دریافت می‌کند، سپس به دستگاه یا رایانه دیگری با قابلیت‌های ورودی غنی‌تر می‌رود. کاربر مرورگر را راه‌اندازی می‌کند، به نشانی وب مشخص‌شده می‌رود، به سیستم وارد می‌شود، و کد را وارد می‌کند.
در همین‌حال، برنامه در فواصل زمانی مشخصی یک نشانی وب Google را نظرسنجی می‌کند. پس‌از اینکه کاربر دسترسی را تأیید کرد، پاسخ سرور Google حاوی کد دسترسی و کد بازآوری است. برنامه باید ژتون بازآوری را برای استفاده در آینده ذخیره کند و از کد دسترسی برای دسترسی به Google API استفاده کند. وقتی کد دسترسی منقضی می‌شود، برنامه از ژتون بازآوری برای دریافت کد جدید استفاده می‌کند.
برای جزئیات، به استفاده از OAuth 2.0 برای دستگاه‌ها مراجعه کنید.
حساب‌های سرویس
میاناهای برنامه‌سازی کاربردی Google مانند Prediction API و Google Cloud Storage می‌توانند از طرف برنامه شما بدون دسترسی به اطلاعات کاربر عمل کنند. در این شرایط، برنامه شما باید هویت خود را برای API اثبات کند، اما نیازی به رضایت کاربر نیست. به‌طور مشابه، در سناریوهای سازمانی، برنامه شما می‌تواند دسترسی واگذارشده به برخی منابع را درخواست کند.
برای این نوع تعاملات سرور به سرور، به حساب خدمات نیاز دارید که حسابی است که به‌جای کاربر نهایی به برنامه شما تعلق دارد. برنامه شما ازطرف حساب سرویس، میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند و رضایت کاربر لازم نیست. (در سناریوهای غیرحساب خدمات، برنامه شما میاناهای برنامه‌سازی کاربردی Google را ازطرف کاربران نهایی فراخوانی می‌کند و گاهی رضایت کاربر لازم است.)
اعتبارنامه حساب سرویس، که از Google API Console دریافت می‌کنید، شامل یک نشانی ایمیل تولیدشده منحصربه‌فرد، یک شناسه مشتری، و حداقل یک جفت کلید عمومی/خصوصی است. از شناسه کارخواه و یک کلید خصوصی برای ایجاد JWT امضاشده و ساختن درخواست کد دسترسی در قالب مناسب استفاده می‌کنید. سپس برنامه شما درخواست کد را به «سرور مجوز Google OAuth 2.0» ارسال می‌کند، که کد دسترسی را برمی‌گرداند. برنامه از این کد برای دسترسی به Google API استفاده می‌کند. وقتی توکن منقضی می‌شود، برنامه فرایند را تکرار می‌کند.
برای جزئیات، به مستندات حساب سرویس مراجعه کنید.
اندازه کد
اندازه نشانه‌ها می‌تواند متفاوت باشد و حداکثر به حدود زیر می‌رسد:
کدهای دسترسی برگردانده‌شده توسط Security Token Service API Google Cloud ساختاری مشابه کدهای دسترسی Google API OAuth 2.0 دارند اما محدودیت‌های اندازه کد متفاوتی دارند. برای جزئیات، مستندات میانای برنامه‌سازی کاربردی را ببینید.
Google این حق را برای خود محفوظ می‌دارد که اندازه کد را در این حدود تغییر دهد و برنامه شما باید از اندازه‌های متغیر کد پشتیبانی کند.
انقضای ژتون بازآوری
باید کدتان را طوری بنویسید که احتمال اینکه ژتون بازآوری اعطاشده دیگر کار نکند را پیش‌بینی کند. ممکن است ژتون بازآوری به یکی از دلایل زیر از کار بیفتد:
برای پروژه Google Cloud Platform با صفحه رضایت OAuth پیکربندی‌شده برای نوع کاربر خارجی و وضعیت انتشار «درحال آزمایش»، یک ژتون بازآوری با تاریخ انقضای ۷ روز صادر می‌شود، مگراینکه تنها دامنه‌های OAuth درخواست‌شده زیرمجموعه‌ای از نام، نشانی ایمیل، و نمایه کاربر (ازطریق دامنه‌های
userinfo.email, userinfo.profile, openid یا معادل‌های OpenID Connect آن‌ها) باشد.
درحال‌حاضر، محدودیت ۱۰۰ ژتون بازآوری برای هر «حساب Google» به‌ازای هر شناسه کارخواه OAuth 2.0 وجود دارد. اگر به حد مجاز برسید، ایجاد کردن ژتون بازآوری جدید به‌طور خودکار قدیمی‌ترین ژتون بازآوری را بدون هشدار نامعتبر می‌کند. این محدودیت برای حساب‌های سرویس اعمال نمی‌شود.
همچنین حد بزرگتری برای تعداد کل ژتون‌های بازآوری که حساب کاربری یا حساب سرویس می‌تواند در همه کارخواه‌ها داشته باشد وجود دارد. اکثر کاربران عادی از این حد فراتر نمی‌روند اما حساب توسعه‌دهنده‌ای که برای آزمایش پیاده‌سازی استفاده می‌شود ممکن است فراتر برود.
اگر لازم است چند برنامه، دستگاه، یا ماشین را مجاز کنید، یک راه حل این است که تعداد کارخواه‌هایی را که برای هر «حساب Google» مجاز می‌کنید به ۱۵ یا ۲۰ محدود کنید. اگر سرپرست Google Workspace هستید، می‌توانید کاربران دیگری با امتیازهای سرپرست ایجاد کنید و از آن‌ها برای صدور مجوز برای برخی‌از کارخواه‌ها استفاده کنید.
رسیدگی به خط‌مشی‌های کنترل جلسه برای سازمان‌های Google Cloud Platform (GCP)
سرپرستان سازمان‌های GCP ممکن است هنگام دسترسی کاربران به منابع GCP، بااستفاده از ویژگی کنترل جلسه Google Cloud، از آن‌ها بخواهند که به‌طور مکرر مجدداً اصالت‌سنجی کنند. این خط‌مشی بر دسترسی به Google Cloud Console،
کیت توسعه نرم‌افزار Google Cloud (که با نام gcloud
CLI نیز شناخته می‌شود)، و هر برنامه OAuth شخص ثالثی که به دامنه Cloud Platform نیاز دارد تأثیر می‌گذارد. اگر
کاربر خط‌مشی کنترل جلسه داشته باشد، پس‌از انقضای مدت جلسه،
فراخوانی‌های میانای برنامه‌سازی کاربردی شما با خطا مواجه می‌شود، مشابه آنچه درصورت لغو ژتون بازآوری اتفاق می‌افتد -
فراخوانی با نوع خطای invalid_grant ناموفق خواهد بود؛ از فیلد error_subtype
می‌توان برای تشخیص بین ژتون لغوشده و ناموفق بودن به‌دلیل خط‌مشی کنترل جلسه (برای مثال، "error_subtype": "invalid_rapt") استفاده کرد. ازآنجایی‌که
مدت جلسه می‌تواند بسیار محدود باشد (بین ۱ ساعت تا ۲۴ ساعت)، این سناریو باید
با راه‌اندازی مجدد جلسه اصالت‌سنجی به‌درستی مدیریت شود.
به‌همین ترتیب، نباید از اطلاعات کاربری کاربر برای استقرار سروربه‌سرور استفاده کنید یا استفاده از آن را تشویق کنید. اگر اطلاعات کاربری کاربر برای عملیات یا کارهای طولانی‌مدت در سرور مستقر شده باشد و مشتری خط‌مشی‌های کنترل جلسه را برای چنین کاربرانی اعمال کند، برنامه سرور ناموفق خواهد بود زیرا راهی برای اصالت‌سنجی مجدد کاربر پس‌از منقضی شدن مدت جلسه وجود نخواهد داشت.
برای کسب اطلاعات بیشتر درباره نحوه کمک به مشتریانتان برای پیاده‌سازی این ویژگی، به این مقاله راهنمای متمرکز بر سرپرست مراجعه کنید.
کتابخانه‌های مشتری
کتابخانه‌های مشتری زیر با چارچوب‌های محبوب ادغام می‌شوند که پیاده‌سازی OAuth 2.0 را ساده‌تر می‌کند. به‌مرور زمان، ویژگی‌های بیشتری به کتابخانه‌ها اضافه خواهد شد.
- کتابخانه Google Auth برای Java
- کتابخانه کارخواه Google API برای Python
- کتابخانه کارخواه Google API برای Dart
- کتابخانه کارخواه Google API برای Go
- Google API Client Library for .NET
- کتابخانه کارخواه Google API برای Ruby
- کتابخانه کارخواه Google API برای PHP
- کتابخانه کارخواه Google API برای جاوا اسکریپت
- GTMAppAuth - OAuth Client Library for Mac and iOS