احراز هویت و مجوز در پروتکل داده گوگل

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

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

سرویس‌های احراز هویت به کاربران اجازه می‌دهند با استفاده از یک حساب گوگل به برنامه شما وارد شوند.

سرویس‌های مجوزدهی به کاربران اجازه می‌دهند تا به برنامه‌های شما دسترسی به داده‌هایی که در برنامه‌های گوگل ذخیره کرده‌اند را بدهند. گوگل به حریم خصوصی اهمیت زیادی می‌دهد و هر برنامه‌ای که نیاز به دسترسی به داده‌های کاربر دارد، باید توسط کاربر مجاز شود.

سرویس‌های احراز هویت و مجوز اغلب به صورت جمعی به عنوان auth شناخته می‌شوند.

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

  • ورود به سیستم با گوگل (Google Sign-In) روشی ساده برای استفاده افراد از اعتبارنامه‌های گوگل خود جهت ورود به سایت شما فراهم می‌کند. این سرویس شامل مجموعه‌ای از ابزارها است که به راحتی در دستگاه‌های مختلف قابل ادغام هستند.
  • OAuth 2.0 یک پروتکل احراز هویت برای همه APIهای گوگل است. OAuth 2.0 برای امنیت به SSL متکی است، به جای اینکه از برنامه شما بخواهد مستقیماً امضای رمزنگاری انجام دهد. این پروتکل به برنامه شما اجازه می‌دهد تا درخواست دسترسی به داده‌های مرتبط با حساب گوگل کاربر را داشته باشد.
  • ورود با OAuth 2.0 ( OpenID Connect ) کاربران را با وارد کردن حساب‌های گوگلشان احراز هویت می‌کند. این جایگزینی برای OpenID است و کاربران OpenID باید قصد داشته باشند به ورود با OAuth 2.0 مهاجرت کنند.

اگر برنامه شما یک گجت است (برای استفاده در iGoogle یا سایر کانتینرهای OpenSocial)، به بخش احراز هویت برای گجت‌ها مراجعه کنید.

توجه : این سند قصد دارد مروری بر هر روش احراز هویت داشته باشد. برای اطلاعات دقیق در مورد هر روش، به مستندات کامل APIهای احراز هویت حساب گوگل مراجعه کنید.

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

OAuth - مجوز برای برنامه‌های وب و نصب شده

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

گوگل از دو نسخه OAuth برای دسترسی مجاز به داده‌های گوگل کاربر پشتیبانی می‌کند: OAuth 1.0 و OAuth 2.0 که هر دو دسترسی به برنامه‌های وب و برنامه‌های نصب شده را ارائه می‌دهند.

OAuth 2.0 برای وب و برنامه‌های نصب‌شده

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

OAuth 1.0 برای برنامه‌های وب

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

OAuth 1.0 برای برنامه‌های نصب‌شده

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

استفاده از OAuth با برنامه‌های وب

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

کتابخانه‌های کلاینت APIهای Google Data، روش‌هایی را برای کمک به شما در استفاده از OAuth در برنامه وب خود ارائه می‌دهند. به طور خاص، روش‌هایی برای ساخت توکن درخواست، تأیید توکن درخواست و تبادل توکن درخواست مجاز با توکن دسترسی وجود دارد. این کتابخانه‌ها همچنین الگوریتم‌های امضای لازم را هنگام ارسال درخواست به یک سرویس Google Data مدیریت می‌کنند. برای مثال‌های گسترده‌تر در مورد نحوه استفاده از OAuth با کتابخانه‌های کلاینت APIهای Google Data، به بخش «استفاده از OAuth با کتابخانه‌های کلاینت APIهای Google Data» مراجعه کنید.

فرآیند احراز هویت OAuth

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

در سطح پایه، فرآیند به شرح زیر است:

  1. برنامه شما درخواست دسترسی می‌دهد و یک توکن درخواست غیرمجاز از سرور احراز هویت گوگل دریافت می‌کند.
  2. گوگل از کاربر می‌خواهد که به شما اجازه دسترسی به داده‌های مورد نیاز را بدهد.
  3. برنامه شما یک توکن درخواست مجاز از سرور احراز هویت دریافت می‌کند.
  4. شما توکن درخواست مجاز را با یک توکن دسترسی تعویض می‌کنید.
  5. شما از توکن دسترسی برای درخواست داده از سرورهای دسترسی به خدمات گوگل استفاده می‌کنید.

وقتی برنامه شما در ابتدا درخواست دسترسی به داده‌های کاربر را می‌دهد، گوگل یک توکن درخواست غیرمجاز به برنامه شما ارسال می‌کند.

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

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

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

آماده شدن برای OAuth

قبل از اینکه بتوانید برنامه خود را برای استفاده از سرویس احراز هویت گوگل با OAuth تنظیم کنید، باید مراحل زیر را انجام دهید.

تصمیم گیری در مورد ثبت برنامه وب خود

برای اطمینان بیشتر کاربران از امنیت داده‌هایشان، می‌توانید برنامه وب خود را در گوگل ثبت کنید و درخواست‌های خود را با گواهی امنیتی ثبت‌شده امضا کنید. برخی از فیدهای Google Data API فقط برای برنامه‌های ثبت‌شده در دسترس هستند. برای تعیین اینکه آیا آن API فقط با برنامه‌های ثبت‌شده کار می‌کند یا خیر، به مستندات مربوط به Google Data API مورد نظر خود مراجعه کنید.

برنامه شما باید هر درخواست OAuth که ارسال می‌کند را امضا کند. اگر تصمیم دارید از امضای RSA-SHA1 برای امضای درخواست‌های خود استفاده کنید، باید یک گواهی امنیتی را به عنوان بخشی از فرآیند ثبت نام آپلود کنید.

به عنوان یک روش جایگزین، می‌توانید از امضای HMAC-SHA1 برای امضای درخواست‌های خود استفاده کنید. برای امضاهای HMAC-SHA1 نیازی به گواهی نیست. در عوض، گوگل یک مقدار consumer secret OAuth ایجاد می‌کند که پس از ثبت دامنه، در صفحه ثبت دامنه شما نمایش داده می‌شود.

برای اطلاعات بیشتر در مورد مراحل ثبت نام، به ثبت نام برای برنامه های وب مراجعه کنید.

تعیین محدوده داده‌هایی که برنامه شما به آنها دسترسی خواهد داشت

هر سرویس گوگل محدودیت‌هایی را برای دسترسی‌هایی که از طریق APIهای داده‌های گوگل (Google Data APIs) مجاز می‌داند، تعیین می‌کند. این دسترسی به صورت یک مقدار دامنه (scope value) بیان می‌شود. برخی سرویس‌ها مقادیر دامنه متنوعی را ارائه می‌دهند تا به کاربر اجازه دهند انتخاب کند کدام برنامه‌ها باید به کدام داده‌ها دسترسی داشته باشند. برای کسب اطلاعات در مورد مقادیر دامنه موجود برای سرویس گوگلی که می‌خواهید به آن دسترسی داشته باشید، به مستندات آن سرویس مراجعه کنید.

به طور کلی، شما باید برای محدودترین محدوده‌ای که شامل داده‌های مورد نیاز شماست، یک توکن درخواست کنید. برای مثال، اگر برنامه شما نیاز به دسترسی به فید "همه تقویم‌ها"ی کاربر دارد، باید یک توکن برای محدوده http://www.google.com/calendar/feeds/default/allcalendars/full درخواست کنید.

راه‌اندازی مکانیزمی برای مدیریت توکن‌های OAuth

وقتی یک توکن دسترسی OAuth برای داده‌های یک کاربر دریافت می‌کنید، باید از آن توکن دسترسی برای همه تعاملات آینده با سرویس گوگل مشخص شده از طرف کاربر استفاده کنید.

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

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

راه‌اندازی مکانیزمی برای درخواست دسترسی به یک سرویس گوگل

هر درخواست به یک سرویس گوگل باید امضا شده باشد و باید شامل یک توکن دسترسی OAuth معتبر باشد. به طور کلی، هر درخواست به شکل یک درخواست HTTP GET انجام می‌شود که توکن دسترسی و امضا در هدر آن گنجانده شده است. درخواست‌هایی که داده‌های جدید را می‌نویسند باید از HTTP POST استفاده کنند.

برای اطلاعات بیشتر در مورد قالب درخواست مناسب برای هر API داده گوگل ، به مستندات آن API مراجعه کنید.

پیاده‌سازی OpenID (اختیاری)

اگر OpenID را برای احراز هویت کاربر پیاده‌سازی می‌کنید، استفاده از پروتکل ترکیبی را برای ترکیب این دو فرآیند در نظر بگیرید. با OpenID+OAuth ، وظایف دریافت توکن درخواست و تأیید آن به عنوان بخشی از درخواست OpenID با افزونه‌های OAuth انجام می‌شود. همانند OAuthGetRequestToken ، این افزونه‌ها برای شناسایی سرویس‌های گوگل مورد دسترسی استفاده می‌شوند. یک پاسخ موفقیت‌آمیز به درخواست OpenID حاوی یک توکن درخواست مجاز است. پس از دریافت این توکن، OAuthGetAccessToken برای تبادل آن با یک توکن دسترسی استفاده کنید.

کار با توکن‌های OAuth

برای استفاده از OAuth، برنامه شما باید فراخوانی‌های درخواست توکن امضا شده و خوش‌فرمی را برای دنباله زیر تولید کند و پاسخ‌ها را مدیریت کند:

  1. دریافت توکن درخواست غیرمجاز ( OAuthGetRequestToken )
  2. توکن درخواست ( OAuthAuthorizeToken ) را مجاز کنید.
  3. توکن درخواست مجاز را با یک توکن دسترسی ( OAuthGetAccessToken ) مبادله کنید.

تمام درخواست‌های OAuth باید امضا شوند، چه درخواست شما ثبت شده باشد و چه ثبت نشده باشد. برای اطلاعات بیشتر، به بخش امضای درخواست‌های OAuth مراجعه کنید.

شما می‌توانید درخواست و دریافت توکن‌های مجوز را در OAuth Playground آزمایش کنید.

برای مستندات دقیق، به مرجع API OAuth مراجعه کنید.

تنظیم URL پاسخ به تماس

شما می‌توانید در یک درخواست OAuthGetRequestToken مقداری برای oauth_callback تعیین کنید تا مشخص شود گوگل پس از تأیید درخواست دسترسی شما، کاربر را به کجا هدایت می‌کند. URL فراخوانی می‌تواند شامل پارامترهای پرس‌وجو باشد. این هدایت شامل همان پارامترهای پرس‌وجو و همچنین توکن درخواست مجاز خواهد بود که برنامه شما باید بتواند آن را تجزیه کند.

برای مثال، هنگام پشتیبانی از چندین زبان، می‌توانید یک پارامتر پرس‌وجو اضافه کنید که نسخه برنامه‌ای را که کاربر مشاهده می‌کند مشخص کند. مقدار oauth_callback برابر با "http://www.yoursite.com/Retrievetoken?Lang=de" منجر به تغییر مسیر "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE" می‌شود. تجزیه توکن و پارامتر زبان تضمین می‌کند که کاربر به نسخه صحیح سایت هدایت می‌شود.

اگر پارامتر oauth_callback لحاظ نشده باشد، گوگل پس از تأیید درخواست دسترسی شما، کاربر را به صفحه وبی هدایت می‌کند که شماره تأیید ( به مثال مراجعه کنید ) را نمایش می‌دهد. کاربر باید قبل از اینکه بتوانید توکن درخواست مجاز را دریافت کنید، به صورت دستی به برنامه شما برگردد و شماره تأیید را وارد کند.

معرفی اپلیکیشن شما به کاربران

گوگل معمولاً هنگام درخواست رضایت دسترسی از کاربر، نام برنامه را نمایش می‌دهد ( به مثال مراجعه کنید ).

اگر برنامه شما ثبت نشده است، از پارامتر xoauth_displayname در درخواست OAuthGetRequestToken خود برای مشخص کردن نام برنامه خود استفاده کنید. اگر این پارامتر مشخص نشده باشد، گوگل نام دامنه URL ارائه شده توسط پارامتر oauth_callback را نمایش می‌دهد. اگر هیچ URL فراخوانی ارائه نشده باشد، گوگل رشته "anonymous" را نمایش می‌دهد.

اگر برنامه شما ثبت شده است، این پارامتر را تنظیم نکنید. به طور پیش‌فرض، گوگل نام نمایشی مشخص شده در هنگام ثبت را نشان می‌دهد. اگر در درخواست OAuthGetRequestToken خود نام نمایشی تنظیم کنید، گوگل از این نام به جای نام نمایشی ثبت شده شما استفاده می‌کند و پیامی مبنی بر عدم تأیید هویت برنامه شما ارسال خواهد کرد.

توجه: برای تنظیم پارامتر xoauth_displayname در OAuth Playground ، قبل از دریافت توکن درخواست، کادر «پیشرفته» را علامت بزنید.

کار با دامنه‌های Google Apps

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

اطلاعات بیشتر در مورد OAuth

برای اطلاعات دقیق در مورد پیاده‌سازی OAuth توسط گوگل، از جمله نحوه ثبت برنامه و ساخت پارامترهای لازم OAuth، به این منابع اضافی مراجعه کنید:

بازگشت به بالا

استفاده از OAuth با برنامه‌های نصب شده

تمام APIهای داده گوگل از OAuth ، یک استاندارد باز برای مجوز استفاده از داده‌ها در برنامه‌ها، پشتیبانی می‌کنند. برنامه‌های نصب شده برای استفاده از OAuth نیازی به ثبت در گوگل ندارند.

فرآیند احراز هویت OAuth

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

در سطح پایه، فرآیند به شرح زیر است:

  1. برنامه شما درخواست دسترسی می‌دهد و یک توکن درخواست غیرمجاز از سرور احراز هویت گوگل دریافت می‌کند.
  2. گوگل از کاربر می‌خواهد که به شما اجازه دسترسی به داده‌های مورد نیاز را بدهد.
  3. برنامه شما یک توکن درخواست مجاز از سرور احراز هویت دریافت می‌کند.
  4. شما توکن درخواست مجاز را با یک توکن دسترسی تعویض می‌کنید.
  5. شما از توکن دسترسی برای درخواست داده از سرورهای دسترسی به خدمات گوگل استفاده می‌کنید.

وقتی برنامه شما در ابتدا درخواست دسترسی به داده‌های کاربر را می‌دهد، گوگل یک توکن درخواست غیرمجاز به برنامه شما ارسال می‌کند.

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

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

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

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

آماده شدن برای OAuth

قبل از اینکه بتوانید برنامه خود را برای استفاده از سرویس احراز هویت گوگل با OAuth تنظیم کنید، باید مراحل زیر را انجام دهید.

تعیین محدوده داده‌هایی که برنامه شما به آنها دسترسی خواهد داشت

هر سرویس گوگل محدودیت‌هایی را برای دسترسی‌هایی که از طریق APIهای داده‌های گوگل (Google Data APIs) مجاز می‌داند، تعیین می‌کند. این دسترسی به صورت یک مقدار دامنه (scope value) بیان می‌شود. برخی سرویس‌ها مقادیر دامنه متنوعی را ارائه می‌دهند تا به کاربر اجازه دهند انتخاب کند کدام برنامه‌ها باید به کدام داده‌ها دسترسی داشته باشند. برای کسب اطلاعات در مورد مقادیر دامنه موجود برای سرویس گوگلی که می‌خواهید به آن دسترسی داشته باشید، به مستندات آن سرویس مراجعه کنید.

به طور کلی، شما باید برای محدودترین محدوده‌ای که شامل داده‌های مورد نیاز شماست، یک توکن درخواست کنید. برای مثال، اگر برنامه شما نیاز به دسترسی به فید "همه تقویم‌ها"ی کاربر دارد، باید یک توکن برای محدوده http://www.google.com/calendar/feeds/default/allcalendars/full درخواست کنید.

راه‌اندازی مکانیزمی برای مدیریت توکن‌های OAuth

وقتی یک توکن دسترسی OAuth برای داده‌های یک کاربر دریافت می‌کنید، باید از آن توکن دسترسی برای همه تعاملات آینده با سرویس گوگل مشخص شده از طرف کاربر استفاده کنید.

برنامه شما باید ذخیره‌سازی توکن‌ها را به صورت ایمن مدیریت کند، از جمله ردیابی سرویس گوگل که هر توکن برای آن معتبر است.

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

راه‌اندازی مکانیزمی برای درخواست دسترسی به یک سرویس گوگل

هر درخواست به یک سرویس گوگل باید امضا شده باشد و باید شامل یک توکن دسترسی OAuth معتبر باشد. به طور کلی، هر درخواست به شکل یک درخواست HTTP GET انجام می‌شود که توکن دسترسی و امضا در هدر آن گنجانده شده است. درخواست‌هایی که داده‌های جدید را می‌نویسند باید از HTTP POST استفاده کنند.

برای اطلاعات بیشتر در مورد قالب درخواست مناسب برای هر API داده گوگل ، به مستندات آن API مراجعه کنید.

کار با توکن‌های OAuth

برای استفاده از OAuth، برنامه شما باید فراخوانی‌های درخواست توکن امضا شده و خوش‌فرمی را برای دنباله زیر تولید کند و پاسخ‌ها را مدیریت کند:

  1. دریافت توکن درخواست غیرمجاز ( OAuthGetRequestToken )
  2. توکن درخواست ( OAuthAuthorizeToken ) را مجاز کنید.
  3. توکن درخواست مجاز را با یک توکن دسترسی ( OAuthGetAccessToken ) مبادله کنید.

تمام درخواست‌های OAuth باید امضا شوند، چه برنامه شما ثبت شده باشد و چه نباشد. برای اطلاعات بیشتر، به بخش امضای درخواست‌های OAuth مراجعه کنید. برنامه‌های نصب شده باید دستورالعمل‌های مربوط به یک برنامه ثبت نشده را دنبال کنند.

شما می‌توانید درخواست و دریافت توکن‌های مجوز را در OAuth Playground آزمایش کنید.

برای مستندات دقیق، به مرجع API OAuth مراجعه کنید.

معرفی اپلیکیشن شما به کاربران

گوگل معمولاً هنگام درخواست رضایت دسترسی از کاربر، نام برنامه را نمایش می‌دهد ( به مثال مراجعه کنید ).

از پارامتر xoauth_displayname در درخواست OAuthGetRequestToken خود برای مشخص کردن نام برنامه خود استفاده کنید. اگر این پارامتر مشخص نشده باشد، گوگل نام دامنه URL ارائه شده توسط پارامتر oauth_callback را نمایش می‌دهد. اگر هیچ URL فراخوانی ارائه نشده باشد، گوگل رشته "anonymous" را نمایش می‌دهد.

توجه: برای تنظیم پارامتر xoauth_displayname در OAuth Playground ، قبل از دریافت توکن درخواست، کادر «پیشرفته» را علامت بزنید.

راه اندازی مرورگر وب

به عنوان بخشی از فرآیند مجوز OAuth، برنامه شما باید یک درخواست OAuthAuthorizeToken ارسال کند. سپس کاربر باید به یک صفحه وب گوگل وارد شود و درخواست دسترسی برنامه شما را تأیید کند.

  • حالت تشخیص خودکار باید برای اکثر برنامه‌ها استفاده شود
  • حالت دستگاه باید برای برنامه‌هایی استفاده شود که نمی‌توانند یک مرورگر وب کامل را اجرا کنند.
  • حالت توسعه فقط باید در مراحل اولیه توسعه استفاده شود.

حالت تشخیص خودکار

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

این حالت مستلزم آن است که شما یک URL فراخوانی ارائه دهید که کاربر پس از تأیید درخواست دسترسی شما به آن هدایت شود. این URL باید به عنوان پارامتر oauth_callback درخواست OAuthGetRequestToken و به عنوان پارامتر verifier درخواست OAuthGetAccessToken ارائه شود.

برای بهبود تجربه کاربری، برنامه شما باید سعی کند به طور خودکار تشخیص دهد که چه زمانی کاربر به این URL هدایت می‌شود و بلافاصله خود را به پیش‌زمینه آورده و یک درخواست OAuthGetAccessToken برای تکمیل فرآیند OAuth ارسال کند.

برای اطلاعات بیشتر و بهترین شیوه‌ها، به تأیید تشخیص خودکار مراجعه کنید.

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

حالت دستگاه

اگر برنامه شما نمی‌تواند یک مرورگر وب کامل را اجرا کند، دستگاه‌های دارای کلاینت غنی نیز می‌توانند بدون مرورگر وب مجوز بگیرند .

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

حالت توسعه

این حالت فقط برای استفاده در مراحل اولیه توسعه یک برنامه توصیه می‌شود.

همانند حالت AutoDetect، برنامه شما باید یک مرورگر را اجرا کند و کاربر باید درخواست شما را تأیید کند. با این حال، به جای ایجاد یک صفحه وب برای URL فراخوانی، می‌توانید مقدار پارامتر oauth_callback را روی "oob" (خارج از باند) تنظیم کنید.

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

کاربر باید به برنامه شما برگردد و شماره تأیید را وارد کند، قبل از اینکه بتوانید درخواست OAuthGetAccessToken را ارسال کنید.

اطلاعات بیشتر در مورد OAuth

برای اطلاعات دقیق در مورد پیاده‌سازی OAuth توسط گوگل، از جمله نحوه ثبت برنامه و ساخت پارامترهای لازم OAuth، به این منابع اضافی مراجعه کنید:

بازگشت به بالا

استفاده از AuthSub برای احراز هویت

AuthSub یک API مجوز اختصاصی گوگل است که به عنوان جایگزینی برای OAuth برای اکثر API های گوگل در دسترس است. در صورت امکان باید از استفاده از AuthSub خودداری کنید. اگر از قبل برنامه‌هایی دارید که از AuthSub استفاده می‌کنند، باید به OAuth یا پروتکل ترکیبی مهاجرت کنید.

فرآیند احراز هویت AuthSub

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

فرآیند مجوزدهی

  1. وقتی برنامه‌ی وب نیاز به دسترسی به سرویس گوگل کاربر دارد، یک فراخوانی AuthSub به سرویس Authorization Proxy گوگل انجام می‌دهد.
  2. سرویس احراز هویت با نمایش صفحه درخواست دسترسی پاسخ می‌دهد. این صفحه که توسط گوگل مدیریت می‌شود، کاربر را وادار به اعطای/عدم اعطای دسترسی به سرویس گوگل خود می‌کند. ابتدا ممکن است از کاربر خواسته شود وارد حساب کاربری خود شود.
  3. کاربر تصمیم می‌گیرد که آیا به برنامه وب دسترسی بدهد یا ندهد. اگر کاربر دسترسی را رد کند، به جای بازگشت به برنامه وب، به یک صفحه گوگل هدایت می‌شود.
  4. اگر کاربر اجازه دسترسی بدهد، سرویس احراز هویت، کاربر را به برنامه وب هدایت می‌کند. این هدایت مجدد شامل یک توکن احراز هویت است که برای یک بار استفاده مناسب است؛ می‌توان آن را با یک توکن با طول عمر بالا تعویض کرد.
  5. برنامه وب با درخواستی با سرویس گوگل تماس می‌گیرد و با استفاده از توکن مجوز، به عنوان نماینده کاربر عمل می‌کند.
  6. اگر سرویس گوگل توکن را تشخیص دهد، داده‌های درخواستی را ارائه می‌دهد.

کار با AuthSub

گنجاندن AuthSub در برنامه وب شما مستلزم انجام این وظایف است:

  1. تصمیم بگیرید که آیا برنامه وب خود را ثبت کنید یا خیر.

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

    اگر ثبت نام کنید، می‌توانید یک گواهی امنیتی و کلید نیز ارائه دهید. برنامه‌های وب ثبت شده با گواهی ثبت شده می‌توانند هنگام درخواست داده از یک سرویس گوگل، توکن‌های امن را برای استفاده دریافت کنند. (همچنین می‌توانند در صورت لزوم از توکن‌های غیر امن استفاده کنند.)

  2. تصمیم بگیرید که از چه نوع توکن‌هایی استفاده کنید و چگونه آنها را مدیریت کنید.

    یک توکن مجوز دریافت شده از گوگل برای استفاده در تمام تعاملات آینده با سرویس مشخص شده گوگل برای آن کاربر در نظر گرفته شده است. نوع توکنی که شما برای استفاده انتخاب می‌کنید - یکبار مصرف یا جلسه‌ای - به نوع تعاملاتی که برنامه وب شما با یک سرویس گوگل خواهد داشت بستگی دارد. به عنوان مثال، اگر تعامل یک رویداد یک‌باره یا نادر باشد، یک توکن یکبار مصرف ممکن است کافی باشد.

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

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

  3. محدوده مورد نیاز سرویس گوگل برای دسترسی را تعیین کنید.

    هر سرویس گوگل میزان و نوع دسترسی مجاز را تعیین می‌کند. این دسترسی به صورت یک مقدار دامنه بیان می‌شود. دامنه یک سرویس ممکن است یک URL ساده باشد که کل سرویس را مشخص می‌کند، یا ممکن است دسترسی محدودتری را مشخص کند. برخی سرویس‌ها دسترسی را به شدت محدود می‌کنند، مانند اجازه دسترسی فقط خواندنی به اطلاعات محدود. برای دریافت دامنه‌های مجاز برای سرویس گوگلی که می‌خواهید به آن دسترسی داشته باشید، به مستندات آن سرویس مراجعه کنید. شما باید توکن با دامنه محدودترین حد ممکن را درخواست کنید. به عنوان مثال، اگر می‌خواهید به ویژگی فید Atom جیمیل دسترسی پیدا کنید، از دامنه "http://www.google.com/calendar/feeds/" استفاده کنید، نه "http://www.google.com/calendar/". سرویس‌های گوگل در مورد درخواست‌های با دامنه بزرگ بسیار محدودتر هستند.

  4. سازوکاری برای درخواست و دریافت توکن مجوز راه‌اندازی کنید.

    این مکانیزم باید یک فراخوانی AuthSubRequest خوش‌فرم ایجاد کند، از جمله مشخص کردن مقادیر مناسب URL بعدی و دامنه (که در مرحله 3 تعیین شده‌اند). اگر از توکن‌های امن استفاده می‌کنید و/یا توکن‌های جلسه را مدیریت می‌کنید، درخواست باید شامل مقادیری برای این متغیرها نیز باشد.

    آدرس اینترنتی بعدی می‌تواند شامل پارامترهای جستجو باشد. برای مثال، هنگام پشتیبانی از چندین زبان، یک پارامتر جستجو اضافه کنید که نسخه برنامه وب مورد نظر کاربر را مشخص کند. مقدار بعدی http://www.yoursite.com/Retrievetoken?Lang=de منجر به تغییر مسیر http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE می‌شود. تجزیه توکن و پارامتر Lang تضمین می‌کند که کاربر به نسخه صحیح سایت هدایت می‌شود.

    در شرایط خاص، استفاده از پارامتر hd می‌تواند به ساده‌سازی تجربه کاربران شما هنگام درخواست اعطای دسترسی در سایت حساب‌های گوگل کمک کند. در بیشتر موارد، این فرآیند به سادگی ورود به حساب کاربری و انتخاب اعطای دسترسی یا عدم اعطای آن است. با این حال، کاربرانی که بیش از یک حساب گوگل دارند (یک حساب جیمیل معمولی و/یا یک یا چند حساب میزبانی‌شده Google Apps)، ممکن است نیاز به دنبال کردن فرآیند اضافی "ورود عمومی" داشته باشند تا مشخص کنند که می‌خواهند به کدام حساب دسترسی داشته باشند. اگر برنامه شما برای یک دامنه مدیریت‌شده خاص طراحی شده است، می‌توانید با استفاده از این پارامتر برای شناسایی آن دامنه، این مراحل اضافی را حذف کنید. همچنین می‌توانید از پارامتر hd در صورتی که برنامه شما به سرویس‌هایی دسترسی دارد که در حساب‌های میزبانی‌شده در دسترس نیستند، استفاده کنید - تنظیم مقدار روی "پیش‌فرض" مجوز را فقط به حساب‌های معمولی محدود می‌کند. وقتی مقدار hd تنظیم شود، گوگل به طور خودکار حساب صحیح را برای مجوز انتخاب می‌کند.

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

  5. سازوکارهایی را برای درخواست توکن‌های جلسه و ذخیره یا لغو آنها، در صورت لزوم، تنظیم کنید.

    بسته به تصمیماتی که در مرحله ۲ در مورد مدیریت توکن‌ها گرفته‌اید، ممکن است نیاز به ایجاد مکانیسم‌هایی برای دریافت و لغو توکن‌های جلسه ( AuthSubSessionToken و AuthSubRevokeToken ) داشته باشید. برای آزمایش مکانیسم‌های جلسه و لغو، از AuthSubTokenInfo استفاده کنید که نشان می‌دهد آیا یک توکن داده شده معتبر است یا خیر. در صورت ذخیره توکن‌ها، برنامه باید هم شناسه کاربر و هم سرویس (محدوده) تحت پوشش توکن را ردیابی کند.

  6. سازوکاری برای درخواست دسترسی به یک سرویس گوگل راه‌اندازی کنید.

    برای اطلاعات در مورد قالب مناسب درخواست، به مستندات سرویس گوگل مراجعه کنید. همه درخواست‌ها به یک سرویس گوگل باید شامل یک توکن مجوز معتبر باشند. به طور کلی، درخواست به یک سرویس گوگل به شکل HTTP GET (یا POST در صورت نوشتن داده‌های جدید) است که توکن در هدر درخواست به آن ارجاع داده می‌شود.

    هدر درخواست باید به شکل زیر باشد:

    Authorization: AuthSub token="token"

    که در آن token ، توکن مجوز، یکبار مصرف یا جلسه‌ای است که از گوگل در پاسخ به درخواست AuthSub دریافت شده است. اگر توکن امن باشد، باید با یک امضای دیجیتال همراه باشد. برای دستورالعمل‌ها و مثال‌ها به « درخواست‌های امضا » مراجعه کنید.

    The example below illustrates a request header for a call to the Google Calendar feed service. This request contains a non-secure token:

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

More information about AuthSub

For information on AuthSub, including registering your application with Google and a detailed explanation of exchanging a one-time token for a session token, see these additional resources:

بازگشت به بالا

Using ClientLogin for authorization

ClientLogin is a Google proprietary authorization API, available as an alternative to OAuth for most Google APIs. You should avoid using ClientLogin if possible. If you already have applications that use ClientLogin, you should migrate to OAuth or the hybrid protocol.

Authentication for Installed Applications: ClientLogin

ClientLogin allows your users to log into their Google account from inside your application. The application then contacts Google with the login data and requests access to a specified Google Data API. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account, such as to get or post data. The token remains valid for a set length of time, defined by whichever Google service you're working with.

Note : The Google Data APIs Client Libraries provide methods to help you use ClientLogin in your installed applications. Specifically, there are methods for acquiring an authentication token, handling CAPTCHA challenges, recalling the auth token for later use, and sending the correct Authorization header with every request. If you are working with one of the libraries, see Using ClientLogin with the Google Data APIs Client Libraries .

The ClientLogin authorization process

Authorization with ClientLogin involves a sequence of interactions between three entities: the installed application, Google services, and the user. This diagram illustrates the sequence:

Authorization process

  1. When the third-party application needs to access a user's Google service, it retrieves the user's login name and password.
  2. The third-party application then makes a ClientLogin call to Google's Authorization service.
  3. If the Google Authorization service decides additional vetting is necessary, it returns failure response with a CAPTCHA token and challenge, in the form of a URL for a CAPTCHA image.
  4. If a CAPTCHA challenge is received, the third-party application displays the CAPTCHA image for the user and solicits an answer from the user.
  5. If requested, the user submits an answer to the CAPTCHA challenge.
  6. The third-party application makes a new ClientLogin call, this time including the CAPTCHA answer and token (received with the failure response).
  7. On a successful login attempt (with or without CAPTCHA challenge), the Google Authorization service returns a token to the application.
  8. The application contacts the Google service with a request for data access, referencing the token received from the Google Authorization service.
  9. If the Google service recognizes the token, it supplies the requested data access.

Using ClientLogin

Use this interface in your installed application to programmatically access a user's Google account. After collecting login information from the user, call ClientLogin to request access to the user's account. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account. The token remains valid for a set length of time, which is defined by whichever Google service you're working with.

Incorporating ClientLogin into your application requires these tasks:

  1. Create a UI element to capture login data from the user.

    The UI needs to solicit a user name (email address including domain) and password. The UI should also be capable of displaying a CAPTCHA image using the URL received from Google, if one is required, and soliciting a correct answer from the user. Ideally, your UI will include a link to Google Accounts login page ("https://www.google.com/accounts/Login") in the event that the user needs to sign up for a new account or do other account maintenance.

  2. Write code to generate a well-formed HTTPS POST ClientLogin request and transmit it.

    This code needs to contain logic to handle a CAPTCHA challenge and include both the logintoken and logincaptcha parameters. The application should also be able to detect when the user omits required information--or repeats incorrect data after a login failure--and display an error without sending a superfluous request.

  3. Handle responses from Google.

    There are four possible responses to a login request:

    • success (an HTTP 200)
    • failure (an HTTP 403) with an explanatory error code
    • invalid request, generally resulting from a malformed request
    • failure with a CAPTCHA challenge

    A success response contains an authorization token labeled "Auth". This token must be included in all subsequent requests to the Google service for this account. Authorization tokens should be closely guarded and should not be given to any other application, as they represent access to the user's account. The time limit on the token varies depending on which service issued it.

    A failure response includes one or more error codes and a URL with the error message that can be displayed for the user. Please note that ClientLogin does not differentiate between a failure due to an incorrect password or one due to an unrecognized user name (for example, if the user has not yet signed up for an account). Your application needs to handle all possible error messages as appropriate.

    A failure response with a CAPTCHA challenge means that Google has decided, for whatever reason, that additional security measures should be taken. This response is accompanied by a CAPTCHA image URL and a token representing the specific CAPTCHA challenge.

  4. Handle a CAPTCHA challenge from Google.

    To handle the challenge, the application must display the CAPTCHA image and solicit an answer from the user. To display the CAPTCHA image, use the value of CaptchaUrl returned with the failure response, prefixing it with the Google Accounts URL: "http://www.google.com/accounts/". Once the user provides an answer, the application should resend the login request, this time including the CAPTCHA token ( logintoken ) and the user's answer ( logincaptcha ). Google validates the user's answer before authorizing access to the account.

    There is an alternative for developers who do not want to manage the process's of getting and transmitting a user CAPTCHA response. In response to a CAPTCHA challenge, the application can direct the user to the Google hosted page: "https://www.google.com/accounts/DisplayUnlockCaptcha". Once the user has successfully responded to the challenge, the Google server trusts the computer in use. The application can then resend the original login request to obtain the authorization token.

    5. Note: Google does not validate the login attempt prior to issuing a CAPTCHA challenge. This means a login attempt could fail even after a CAPTCHA challenge.

* CAPTCHA is a trademark of Carnegie Mellon University

بازگشت به بالا

Authentication for Gadgets

OAuth Proxy

If you're building a gadget using the standard Gadgets API , you can leverage a feature of the gadget platform called the OAuth Proxy to access the Google Data APIs. OAuth ( described above ) is an authentication standard that allows users to access their private data in a gadget hosting service such as iGoogle, MySpace, or Orkut, or share their data with another website or gadget. The OAuth Proxy is designed to make development easier for gadget developers by hiding many of OAuth's authentication details. The Proxy is based on an open-source project called Shindig , which is an implementation of the gadget specification.

Note : The OAuth Proxy is only supported for gadgets that use the gadgets.* API and run in OpenSocial containers. It is not supported for the legacy gadgets API .

جریان احراز هویت

Your gadget must obtain an OAuth token before it can access a user's data. The OAuth Proxy manages the authentication flow for you. The first time a user installs your gadget, the following process takes place:

  1. Your gadget loads for the first time and attempts to access the user's data using one of the Google Data APIs.
  2. The request fails because the user hasn't granted access. The response object contains a URL (in response.oauthApprovalUrl ) for the OAuth approval page. Your gadget should provide a method to launch a new window with that URL.
  3. On the approval page, the user chooses to grant or deny access to your gadget. If successful, the user is taken to the oauth_callback page you specify. For the best user experience, use http://oauth.gmodules.com/gadgets/oauthcallback .
  4. Next, the user closes the popup window. To notify your gadget that the user has approved, you can use a popup handler to detect the approval window closing. Alternatively, your gadget can display a link (eg " I've approved access ") for the user to click after this window closes.
  5. Your gadget attempts to access the Google Data API a second time by re-requesting the user's data. This attempt is successful.
  6. Your gadget is authenticated and can begin operating normally.

Gadget setup

To access one or more of the Google Data APIs, you first need to tell your gadget to use OAuth as the authentication method. Add an <OAuth> element in the <ModulePrefs> section of your gadget's XML:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

In this section, only change the following query parameters:

scope
A required parameter in the Request URL. Your gadget can access data from the scope (s) used in this parameter. In this example, the gadget can access Blogger and Calendar data. A gadget can request data for a single scope or multiple scopes, as this example does.
oauth_callback
An optional parameter in the Authorization URL. The OAuth approval page redirects to this URL after the user has approved access to data. You should set this parameter to http://oauth.gmodules.com/gadgets/oauthcallback to provide the best user experience when users install your gadget. That page provides a snippet of JavaScript that automatically closes the popup window. Alternatively, you can set this parameter to point to your own "approved" page, or you can simply leave the parameter blank.

Accessing an authenticated Google Data API feed

Once your gadget has authenticated the user, accessing a Google Data API is straightforward with the Google Data APIs JavaScript client library. For information on how to use the library in the OAuth Proxy, see Using the JavaScript Client Library .

More information about Gadgets

For complete information on creating Google Data API Gadgets, including details on the OAuth Proxy, an article on how to get started, and the gadgets.* spec, see these additional resources:

بازگشت به بالا