میاناهای برنامه‌سازی کاربردی 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 Authorization به 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 می‌توانند بدون دسترسی به اطلاعات کاربر، ازطرف برنامه شما عمل کنند. در این شرایط، برنامه شما باید هویت خود را برای میانای برنامه‌سازی کاربردی اثبات کند، اما رضایت کاربر لازم نیست. به‌طور مشابه، در سناریوهای سازمانی، برنامه شما می‌تواند درخواست دسترسی تفویض‌شده به برخی منابع را داشته باشد.
برای این نوع تعامل‌های سرور به سرور، به حساب خدمات نیاز دارید که حسابی متعلق به برنامه شما است و به کاربر نهایی خاصی تعلق ندارد. برنامه شما ازطرف حساب سرویس، میاناهای برنامه‌سازی کاربردی Google را فراخوانی می‌کند، و رضایت کاربر لازم نیست. (در سناریوهای حساب غیرخدماتی، برنامه شما میاناهای برنامه‌سازی کاربردی Google را ازطرف کاربران نهایی فراخوانی می‌کند و گاهی اوقات رضایت کاربر لازم است.)
اعتبارنامه حساب سرویس، که از «کنسول Google API» دریافت می‌کنید، شامل نشانی ایمیل تولیدشده‌ای است که منحصربه‌فرد است، شناسه کارخواه، و حداقل یک جفت کلید عمومی/خصوصی. از شناسه کارخواه و یک کلید خصوصی برای ایجاد یک 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 ممکن است بااستفاده از
ویژگی کنترل جلسه Google Cloud،
از کاربران بخواهند هنگام دسترسی به منابع GCP، به‌طور مکرر مجدداً اصالت‌سنجی کنند.
این خط‌مشی بر دسترسی به Google Cloud Console،
Google Cloud SDK (که با نام
gcloud CLI نیز شناخته می‌شود)، و هر برنامه OAuth شخص ثالثی که به دامنه Cloud
Platform نیاز دارد تأثیر می‌گذارد. اگر کاربر خط‌مشی کنترل جلسه داشته باشد، پس‌از انقضای مدت جلسه، فراخوانی‌های API شما با خطا مواجه می‌شوند، مشابه آنچه درصورت لغو ژتون بازآوری اتفاق می‌افتد - فراخوانی با نوع خطای invalid_grant ناموفق خواهد بود؛ فیلد error_subtype می‌تواند برای تشخیص بین ژتون لغوشده و خرابی ناشی از خط‌مشی کنترل جلسه (برای مثال، "error_subtype": "invalid_rapt") استفاده شود. ازآنجایی‌که مدت‌زمان جلسه می‌تواند بسیار محدود باشد (بین ۱ ساعت تا ۲۴ ساعت)، این سناریو باید با راه‌اندازی مجدد جلسه احراز هویت به‌درستی مدیریت شود.
به‌همین ترتیب، نباید از اطلاعات کاربری کاربر برای استقرار سروربه‌سرور استفاده کنید یا دیگران را به استفاده از آن تشویق کنید. اگر اطلاعات کاربری کاربر برای عملیات یا کارهای طولانی‌مدت در سرور مستقر شده باشد و مشتری خط‌مشی‌های کنترل جلسه را برای چنین کاربرانی اعمال کند، برنامه سرور ناموفق خواهد بود زیرا راهی برای اصالت‌سنجی مجدد کاربر پس‌از منقضی شدن مدت جلسه وجود نخواهد داشت.
برای کسب اطلاعات بیشتر درباره نحوه کمک به مشتریانتان برای استقرار این ویژگی، به این مقاله راهنمای متمرکز بر سرپرست مراجعه کنید.
کتابخانه‌های مشتری
کتابخانه‌های مشتری زیر با چارچوب‌های محبوب ادغام می‌شوند که پیاده‌سازی OAuth 2.0 را ساده‌تر می‌کند. به‌مرور زمان، ویژگی‌های بیشتری به کتابخانه‌ها اضافه خواهد شد.
- کتابخانه Google Auth برای Java
- کتابخانه کارخواه Google API برای Python
- کتابخانه کارخواه Google API برای Dart
- Google API Client Library for Go
- کتابخانه کارخواه Google API برای NET.
- کتابخانه کارخواه Google API برای Ruby
- کتابخانه کارخواه Google API برای PHP
- کتابخانه کارخواه Google API برای جاوا اسکریپت
- GTMAppAuth - OAuth Client Library for Mac and iOS