این سند نحوه استفاده از سیستم احراز هویت Google AuthSub را از یک برنامه Flash یا Silverlight توضیح می دهد.
توجه : اگر قبلاً با AuthSub، سرویس احراز هویت حساب Google برای برنامه های کاربردی مبتنی بر وب آشنا هستید، خواهید دید که AuthSub برای ActionScript از نظر مفهومی بسیار شبیه است. پیاده سازی اساسی متفاوت است، اما تفاوت ها برای شما به عنوان یک توسعه دهنده برنامه مشتری مهم نیست. در برخی از اسناد، در زمینه‌هایی که تمایز نامربوط است، به AuthSub برای ActionScript به‌طور خلاصه به عنوان «AuthSub» اشاره می‌کنیم.
رابط AuthSub برای ActionScript به برنامه‌های Flash یا Silverlight اجازه می‌دهد تا از طرف یک کاربر به فیدهای محافظت‌شده Google Data API احراز هویت کنند. برای حفظ سطح بالایی از امنیت، این رابط برنامه را قادر می‌سازد تا رمز احراز هویت را بدون استفاده از اطلاعات ورود به حساب کاربر دریافت کند.
AuthSub برای ActionScript یک گونه از AuthSub برای جاوا اسکریپت است. مانند AuthSub برای جاوا اسکریپت، یک روش متقابل دامنه برای برنامه های مشتری برای احراز هویت از یک صفحه وب میزبانی شده در دامنه غیر Google ارائه می دهد. تفاوت آن با AuthSub استاندارد در این است که سرویس احراز هویت در دامنه دیگری قرار دارد (accounts.googleapis.com به جای www.google.com) و یک فایل crossdomain.xml فراهم می کند که امکان دسترسی به آن دامنه را از سایت های خارجی فراهم می کند.
همچنین برای بحث در مورد استفاده از همه APIهای سرویس احراز هویت، به گروه API حساب‌های Google مراجعه کنید.
حضار
این سند برای برنامه نویسانی است که در حال توسعه برنامه های وب Flash یا Silverlight هستند که به خدمات Google دسترسی دارند.
این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs و رابط AuthSub را درک می‌کنید. همچنین فرض می‌کند که می‌دانید چگونه در ActionScript برنامه‌نویسی کنید.
محیط های پشتیبانی شده
AuthSub for ActionScript در حال حاضر در فایرفاکس 1.5 و بالاتر و اینترنت اکسپلورر 6.0 و بالاتر، با Flash 9.0 یا بالاتر یا Silverlight 2.0 یا بالاتر پشتیبانی می شود.
نحوه عملکرد AuthSub برای ActionScript
در اینجا خلاصه ای سریع از نحوه کار ارتباط بین یک برنامه وب، سرویس Google Authentication و سرویس Google Data آورده شده است:
- برای دسترسی به یک سرویس Google Data از طرف یک کاربر، برنامه وب باید دارای یک کد احراز هویت معتبر باشد. به طور معمول، برنامه ها این رمز را در یک کوکی ذخیره می کنند. اگر چنین کوکی وجود نداشته باشد، برنامه وب باید رمز را از طریق AuthSub دریافت کند. برای به دست آوردن یک نشانه، برنامه وب یک تماس ورود به سیستم AuthSub برای ActionScript با سرویس Authentication برقرار می کند و سرویس مورد نظر را مشخص می کند.
- با دریافت درخواست از برنامه وب، سرویس احراز هویت کاربر را به صفحه "درخواست دسترسی" هدایت می کند. این صفحه از کاربر می خواهد که به حساب Google خود وارد شود و از آنها می خواهد که دسترسی به سرویس Google خود را اعطا یا رد کنند.
- کاربر تصمیم می گیرد که آیا دسترسی به برنامه وب را اعطا کند یا رد کند. اگر کاربر دسترسی را رد کند، به جای بازگشت به برنامه وب، به صفحه Google هدایت می شود.
- اگر کاربر با موفقیت وارد سیستم شود و اجازه دسترسی بدهد، سرویس Authentication کاربر را به URL برنامه وب که تماس اصلی را انجام داده است هدایت می کند. ریدایرکت یک نشانه احراز هویت را برای سرویس مشخص شده از طریق یک پارامتر پرس و جو ارائه می کند. برنامه باید رمز را به عنوان یک کوکی در مرورگر کاربر، تحت دامنه برنامه وب ذخیره کند. ژتون تا زمانی که باطل نشود معتبر است. (برای راهنمایی در مورد زمان لغو توکن ها به بخش About tokens مراجعه کنید.)
- برنامه وب با سرویس Google Data تماس می گیرد و رمز احراز هویت را همراه با هر درخواست ارسال شده به سرویس ارسال می کند.
- اگر سرویس Google Data رمز را بشناسد، داده های درخواستی را ارائه می دهد.
با استفاده از رابط AuthSub برای ActionScript
AuthSub for ActionScript یا AuthSubAS یک نقطه پایانی بین دامنه ای AuthSub برای برنامه های Flash (یا Silverlight) که از Google Data API استفاده می کنند، ارائه می دهد.
AuthSubAS آینه‌ای از نقاط پایانی AuthSub موجود در google.com را با یک فایل crossdomain.xml اضافی ارائه می‌کند که به Flash (یا Silverlight) اجازه دسترسی به آن نقاط پایانی را می‌دهد. به عنوان مثال، نقطه پایانی AuthSubSessionToken را می توان با دسترسی به https://accounts.googleapis.com/accounts/AuthSubSessionToken استفاده کرد.
مراحل زیر مراحل دریافت رمز احراز هویت و استفاده از آن برای دسترسی به سرویس Google از یک برنامه فلش را طی می کند.
- خط مشی های بین دامنه ای را تنظیم کنید.
برای استفاده از Flash به صورت متقابل دامنه، باید با یک خط مشی برای هر دامنه خارجی که قرار است به آن دسترسی داشته باشید مقداردهی اولیه شود. برای انجام این کار، روش ActionScript
Security.loadPolicyFile( policy )را برای هر دامنه فراخوانی کنید، مانند:<?xml version="1.0" encoding="utf-8"?> <Application xmlns="http://www.adobe.com/2006/mxml" initialize="onInitialized()" applicationComplete="onLoaded()"> <Script> import flash.external.ExternalInterface; import flash.net.navigateToURL; import mx.controls.Alert; private function onInitialized() : void { // Load the cross domain policy file for each of the googleapis.com // domains used. At the very least, we need the ones for the API (photos, // in this case) and the one for AuthSub for ActionScript (accounts). Security.loadPolicyFile('http://photos.googleapis.com/data/crossdomain.xml'); Security.loadPolicyFile('https://accounts.googleapis.com/crossdomain.xml'); }توجه داشته باشید که در اینجا ما خط‌مشی را برای
accounts.googleapis.com(AuthSubAS) و برایphotos.googleapis.com/data(PicasaWeb که نمونه بعداً به آن دسترسی پیدا می‌کند) بارگیری می‌کنیم. - درخواست یک توکن یکبار مصرف.
اولین مرحله در فرآیند AuthSub درخواست یک توکن یکبار مصرف از نقطه پایانی AuthSub است. برنامه شما باید این کار را با فراخوانی به نقطه پایانی
AuthSubRequestانجام دهد، مانند:var getTokenPage : URLRequest = new URLRequest('https://www.google.com/accounts/AuthSubRequest'); // Construct the parameters of the AuthSub request. These are the same parameters // as normal AuthSub, which can be found here: /accounts/docs/AuthSub.html#AuthSubRequest var authSubParams : URLVariables = new URLVariables(); authSubParams['scope'] = 'http://photos.googleapis.com/data'; // photos API authSubParams['session'] = 1; // single-use token authSubParams['secure'] = 0; // non-secure apps authSubParams['next'] = 'photos.swf'; // The URL of this app. getTokenPage.data = authSubParams; navigateToURL(getTokenPage, '_top');این روش به یک مقدار محدوده نیاز دارد. هر سرویس Google محدوده دسترسی‌ای را که اجازه می‌دهد تعریف می‌کند، و شما باید به آن محدوده در درخواست توکن اشاره کنید. برای تعیین اینکه از چه مقدار دامنه استفاده کنید، اسناد سرویس Google را که می خواهید به آن دسترسی داشته باشید بررسی کنید. محدوده به نظر می رسد مانند یک URL. ممکن است یک URL ساده برای شناسایی سرویس باشد، یا ممکن است دسترسی محدودتری را مشخص کند، مانند محدود کردن دسترسی به فقط خواندنی. هنگامی که سرویس انتخابی از محدوده‌ها را ارائه می‌دهد، توکن‌های با بیشترین محدوده ممکن را درخواست کنید. برای مثال، برای دسترسی به فیدهای داده تقویم Google، از دامنه
'http://www.google.com/calendar/feeds'استفاده کنید، نه'http://www.google.com/calendar'.نکات :
- اکیداً توصیه می‌کنیم که یک دکمه ورود به سیستم یا مکانیزم ورودی کاربر دیگر را ارائه کنید تا از کاربر بخواهد فرآیند ورود را به صورت دستی شروع کند. اگر در عوض، بلافاصله پس از بارگیری، بدون انتظار برای تعامل کاربر، بررسی و تغییر مسیر دهید، اولین چیزی که کاربر هنگام ورود به صفحه شما می بیند یک صفحه ورود به سیستم گوگل است. اگر کاربر تصمیم گرفت وارد سیستم نشود، گوگل آنها را به صفحه شما هدایت نمی کند. بنابراین از نظر کاربر، آنها سعی کردند از صفحه شما بازدید کنند اما فرستاده شدند و هرگز برنگشتند. این سناریو ممکن است برای کاربران گیج کننده و خسته کننده باشد.
- برنامه هایی که نیاز به دسترسی به بیش از یک سرویس گوگل برای یک کاربر دارند، باید برای هر سرویس جدید یک توکن جدید درخواست کنند (زیرا هر سرویس دامنه متفاوتی دارد).
- درخواست یک توکن احراز هویت
نقطه پایانی
AuthSubRequestبا تنظیم URL مرورگر کاربر رویhttp://yourWebAppUrl?token= singleUseTokenیک نشانه یکبار مصرف را به برنامه شما برمی گرداند. هنگامی که برنامه شما رمز یکبار مصرف خود را دریافت کرد، باید توکن را با یک توکن چند بار مصرف (با عمر طولانی) مبادله کند، که سپس می تواند برای درخواست در برابر فیدهای Google Data استفاده شود. برای انجام این کار، متدAuthSubSessionTokenرا با توکن یکبار مصرف فراخوانی کنید.برنامه شما باید پارامتر
tokenدر URL را هنگام بارگیری بررسی کند:private function onLoaded() : void { // Once the application has loaded, check to see if an AuthSub token was
// placed into the current page's URL. If it was, the user has already
// authenticated, and we can continue to connect to the the service itself. var searchPortion : String = ExternalInterface.call('window.location.search.toString'); if (searchPortion.length > 0) { // remove the ? from the token and extract the token. searchPortion = searchPortion.substring(1); // NOTE: Real applications should parse the URL properly. if (searchPortion.indexOf('token=') == 0) { getLongLivedToken(searchPortion.substring(6)); return; } // more code ... }اگر توکن پیدا شد، باید متدی مانند
getLongLivedTokenفراخوانی کند که نقطه پایانیAuthSubSessionTokenرا فراخوانی می‌کند:private function getLongLivedToken(singleUseToken : String) : void { // Construct a call to the AuthSub for ActionScript endpoint on accounts.googleapis.com. // This call will exchange the single use token given to use by AuthSub for a long-term // token that we can use to make requests to endpoints such as Photos. var getTokenRequest : URLRequest = new URLRequest('https://accounts.googleapis.com/accounts/AuthSubSessionToken'); // Due to a bug in Flash, a URLRequest with a GET request will // not properly send headers. We therefore use POST for this and *ALL* // requests. getTokenRequest.method = URLRequestMethod.POST; // Due to a bug in Flash, a URLRequest without a valid parameter will // not properly send headers. We therefore add a useless parameter to // make this code work. getTokenRequest.data = new URLVariables('pleaseignore=ignore'); // Add the AuthSub for ActionScript headers. getTokenRequest.requestHeaders.push(new URLRequestHeader('Authorization', 'AuthSub token="' + singleUseToken + '"')); // Create the loader to get the token itself. The loader will callback // to the following event handlers if and when the server responds. var getToken : URLLoader = new URLLoader(); getToken.addEventListener(Event.COMPLETE, onGetTokenResult); getToken.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onGetTokenFailed); getToken.addEventListener(IOErrorEvent.IO_ERROR, onGetTokenFailed); try { getToken.load(getTokenRequest); } catch (e : Error) { Alert.show('Some error occurred: ' + e); }روشی مانند کنترل کننده
onGetTokenResultباید توکن بازگشتی را ذخیره کند:private function onGetTokenResult(e : Event) : void { // Load the parameters from the response. var getToken : URLLoader = URLLoader(e.target); var params : URLVariables = new URLVariables(getToken.data); // Parse the session token from the result. Real applications // might at this point store the token in a long-term cookie so // that repeated usages of the application do not require this entire // authentication process. sessionToken = params.Token; // Trim the newline from the end of the session token. sessionToken = sessionToken.substring(0, sessionToken.length - 1); }نکات :
- ما قویاً توصیه می کنیم که برنامه شما رمز بلندمدت را در یک کوکی ذخیره کند و قبل از بررسی توکن کوتاه مدت آنها را بررسی کند. این امر باعث می‌شود که کاربران مجبور نباشند هر بار که می‌خواهند از برنامه شما استفاده کنند، از صفحه تأیید AuthSub بازدید کنند.
- استفاده از رمز احراز هویت
برای استفاده از کد احراز هویت، آن را از طریق یک سرصفحه
Authorizationبه هر درخواستی که به یک سرویس Google ارسال می شود، پیوست کنید:Authorization: AuthSub token="(session token goes here)"
مثال در ActionScript برای سرویس Photos:
// Prepare a request to the photos API for the private album // of the user. var albumRequest : URLRequest = new URLRequest('http://photos.googleapis.com/data/feed/api/user/default'); albumRequest.data = new URLVariables('access=private&v=2&err=xml'); // Due to a bug in Flash, a URLRequest with a GET request will // not properly send headers. We therefore use POST for this and *ALL* // requests. albumRequest.method = URLRequestMethod.POST; var authsubHeader : String = 'AuthSub token="' + sessionToken + '"'; // Add the Authorization header which uses the session token. albumRequest.requestHeaders.push(new URLRequestHeader('Authorization', authsubHeader)); // The X-HTTP-Method-Override header tells the Photos API to treat this request // as a GET request, even though it is being conducted as a POST (due to the bug // mentioned above). This is very important, as GData APIs will react differently // to different HTTP request types. albumRequest.requestHeaders.push(new URLRequestHeader('X-HTTP-Method-Override', 'GET')); // We expect ATOM XML to be returned. albumRequest.requestHeaders.push(new URLRequestHeader('Content-Type', 'application/atom+xml'));
گوگل پیشنهاد می کند یک ویژگی خروج دستی مانند دکمه خروج یا یک لینک قابل کلیک ارائه کنید. این رویکرد به کاربران این امکان را می دهد که در صورت انتخاب از سیستم خارج شوند، یا اینکه وارد سیستم شوند و فیدهای داده خود را برای دفعه بعد که به برنامه شما دسترسی پیدا کردند به راحتی در دسترس قرار دهند.
در مورد توکن ها
این بخش توکن های مورد استفاده توسط AuthSub برای ActionScript را توضیح می دهد. در بیشتر زمینه ها، نیازی به دانستن این اطلاعات نخواهید داشت.
هر کد احراز هویت مختص داده های زیر است:
- محدوده خدمات گوگل
- اکانت گوگل کاربر
- درخواست مشتری
داده های نشانه تضمین می کند که فقط برنامه شخص ثالث مشخص شده می تواند داده ها را درخواست کند و این درخواست محدود به داده های محدوده و حساب کاربری مشخص شده است.
فقط یک نشانه برای این ترکیب از محدوده، کاربر و مشتری می تواند در هر زمان معتبر باشد. یک برنامه وب باید هر بار که نیاز به دسترسی به سرویس جدید Google برای یک کاربر خاص داشته باشد، یک توکن جدید درخواست کند. دامنه دسترسی تحت پوشش توکن به سرویس Google بستگی دارد که ممکن است دسترسی به انواع خاصی از داده ها یا فعالیت ها مانند دسترسی فقط خواندنی را محدود کند.
رمز بازگردانده شده توسط رابط AuthSub برای ActionScript را می توان هر چند بار که لازم است استفاده کرد تا زمانی که لغو شود. این به برنامه شما بستگی دارد که عمر توکن را مدیریت کند و امنیت را با راحتی متعادل کند. گوگل توصیه می کند هر بار که جلسه جدیدی شروع می شود، یک توکن جدید درخواست کنید.
برخی از سرویس‌های Google ممکن است فقط به برنامه‌های کاربردی وب که ثبت‌شده و از نشانه‌های امن استفاده می‌کنند اجازه دسترسی دهند. AuthSub برای ActionScript برای چنین خدماتی پشتیبانی نمی شود. برای استفاده از نشانه‌های ایمن ، سازمان شما باید گواهی SSL را در Google ثبت کند و همه درخواست‌ها را برای آن فیدهای داده امضا کند.