استفاده از AuthSub در اکشن اسکریپت

این سند نحوه استفاده از سیستم احراز هویت AuthSub گوگل را از طریق یک برنامه Flash یا Silverlight شرح می‌دهد.

توجه : اگر از قبل با AuthSub، سرویس احراز هویت حساب گوگل برای برنامه‌های تحت وب ، آشنا هستید، خواهید دید که AuthSub برای ActionScript از نظر مفهومی بسیار مشابه است. پیاده‌سازی اساسی متفاوت است، اما این تفاوت‌ها برای شما به عنوان یک توسعه‌دهنده برنامه کلاینت مهم نیستند. در برخی از مستندات، در زمینه‌هایی که تمایز بی‌ربط است، ما به AuthSub برای ActionScript به طور خلاصه "AuthSub" می‌گوییم.

رابط کاربری AuthSub برای ActionScript به برنامه‌های Flash یا Silverlight اجازه می‌دهد تا از طرف کاربر، از طریق فیدهای محافظت‌شده Google Data API احراز هویت شوند. برای حفظ سطح بالای امنیت، این رابط کاربری به برنامه این امکان را می‌دهد که بدون نیاز به مدیریت اطلاعات ورود به حساب کاربری، یک توکن احراز هویت دریافت کند.

AuthSub برای اکشن‌اسکریپت نوعی از AuthSub برای جاوااسکریپت است. مانند AuthSub برای جاوااسکریپت، این روش یک روش بین دامنه‌ای برای برنامه‌های کلاینت فراهم می‌کند تا از یک صفحه وب میزبانی شده در یک دامنه غیر گوگل، احراز هویت کنند. این روش با AuthSub استاندارد متفاوت است، زیرا سرویس احراز هویت در یک دامنه متفاوت (accounts.googleapis.com به جای www.google.com) قرار دارد و یک فایل crossdomain.xml ارائه می‌دهد که امکان دسترسی به آن دامنه را از سایت‌های خارجی فراهم می‌کند.

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

مخاطب

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

این سند فرض می‌کند که شما ایده‌های کلی پشت پروتکل Google Data APIs و رابط AuthSub را درک می‌کنید. همچنین فرض بر این است که شما می‌دانید چگونه با ActionScript برنامه‌نویسی کنید.

محیط‌های پشتیبانی‌شده

AuthSub برای اکشن‌اسکریپت در حال حاضر در فایرفاکس ۱.۵ و بالاتر و اینترنت اکسپلورر ۶.۰ و بالاتر، با فلش ۹.۰ یا بالاتر یا سیلورلایت ۲.۰ یا بالاتر پشتیبانی می‌شود.

نحوه کار AuthSub برای اکشن‌اسکریپت

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

  1. برای دسترسی به سرویس داده‌های گوگل از طرف یک کاربر، برنامه وب باید یک توکن احراز هویت معتبر داشته باشد. معمولاً برنامه‌ها این توکن را در یک کوکی ذخیره می‌کنند؛ اگر چنین کوکی وجود نداشته باشد، برنامه وب باید توکن را از طریق AuthSub به دست آورد. برای به دست آوردن یک توکن، برنامه وب یک فراخوانی ورود AuthSub برای ActionScript به سرویس احراز هویت ارسال می‌کند و سرویسی را که باید به آن دسترسی پیدا کند، مشخص می‌کند.
  2. با دریافت درخواست از برنامه وب، سرویس احراز هویت کاربر را به صفحه "درخواست دسترسی" هدایت می‌کند. این صفحه از کاربر می‌خواهد که وارد حساب گوگل خود شود و از او می‌خواهد که دسترسی به سرویس گوگل خود را اعطا یا رد کند.
  3. کاربر تصمیم می‌گیرد که آیا به برنامه وب دسترسی بدهد یا ندهد. اگر کاربر دسترسی را رد کند، به جای بازگشت به برنامه وب، به یک صفحه گوگل هدایت می‌شود.
  4. اگر کاربر با موفقیت وارد سیستم شود و دسترسی را اعطا کند، سرویس احراز هویت، کاربر را به آدرس اینترنتی برنامه وب که فراخوانی اولیه را انجام داده بود، هدایت می‌کند. این تغییر مسیر، یک توکن احراز هویت برای سرویس مشخص شده را از طریق یک پارامتر پرس و جو ارائه می‌دهد. برنامه باید توکن را به عنوان یک کوکی در مرورگر کاربر، تحت دامنه برنامه وب، ذخیره کند. این توکن تا زمان لغو معتبر است. (برای راهنمایی در مورد زمان لغو توکن‌ها، به بخش «درباره توکن‌ها» مراجعه کنید.)
  5. برنامه وب با سرویس داده گوگل (Google Data) تماس می‌گیرد و توکن احراز هویت (Authentication Token) را به همراه هر درخواستی که به این سرویس ارسال می‌شود، ارسال می‌کند.
  6. اگر سرویس داده گوگل توکن را تشخیص دهد، داده‌های درخواستی را ارائه می‌دهد.

استفاده از رابط AuthSub برای ActionScript

AuthSub برای اکشن‌اسکریپت یا AuthSubAS، یک نقطه پایانی AuthSub چند دامنه‌ای برای برنامه‌های فلش (یا سیلورلایت) که از APIهای داده گوگل استفاده می‌کنند، فراهم می‌کند.

AuthSubAS یک آینه از نقاط انتهایی AuthSub موجود در google.com را به همراه یک فایل crossdomain.xml اضافی فراهم می‌کند که به Flash (یا Silverlight) اجازه می‌دهد به آن نقاط انتهایی دسترسی داشته باشد. برای مثال، نقطه انتهایی AuthSubSessionToken را می‌توان با دسترسی به https://accounts.googleapis.com/accounts/AuthSubSessionToken استفاده کرد.

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

  1. سیاست‌های بین دامنه‌ای را تنظیم کنید.

    برای استفاده از فلش به صورت چند دامنه‌ای، باید برای هر دامنه خارجی که قرار است به آن دسترسی پیدا شود، یک سیاست (policy) مقداردهی اولیه شود. برای انجام این کار، متد Security.loadPolicyFile( policy ) از ActionScript را برای هر دامنه فراخوانی کنید، مانند زیر:

    <?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، که مثال بعداً به آن دسترسی پیدا می‌کند) هستیم.

  2. درخواست توکن یکبار مصرف.

    اولین قدم در فرآیند 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');

    مشاهده نمونه کامل

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

    نکات :

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

  3. درخواست توکن احراز هویت.

    نقطه پایانی AuthSubRequest با تنظیم URL مرورگر کاربر به http://yourWebAppUrl?token= singleUseToken یک توکن یکبار مصرف به برنامه شما برمی‌گرداند. پس از اینکه برنامه شما توکن یکبار مصرف خود را دریافت کرد، باید این توکن را با یک توکن چند منظوره (طولانی مدت) مبادله کند که سپس می‌تواند برای ارسال درخواست‌ها به فیدهای داده گوگل استفاده شود. برای انجام این کار، متد 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 handler باید توکن برگشتی را ذخیره کند:

        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 شوند.

  4. با استفاده از توکن احراز هویت.

    برای استفاده از توکن احراز هویت، آن را از طریق یک هدر Authorization header) به هر درخواستی که به یک سرویس گوگل ارسال می‌شود، پیوست کنید:

    Authorization: AuthSub token="(session token goes here)"

    مثال در اکشن‌اسکریپت برای سرویس عکس‌ها:

          // 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'));

    مشاهده نمونه کامل

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

درباره توکن‌ها

این بخش توکن‌های مورد استفاده توسط AuthSub برای ActionScript را شرح می‌دهد. در بیشتر موارد، نیازی به دانستن این اطلاعات نخواهید داشت.

هر توکن احراز هویت مختص داده‌های زیر است:

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

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

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

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

برخی از سرویس‌های گوگل ممکن است فقط به برنامه‌های وب ثبت‌شده و دارای توکن‌های امن اجازه دسترسی بدهند. AuthSub برای ActionScript برای چنین سرویس‌هایی پشتیبانی نمی‌شود. برای استفاده از توکن‌های امن ، سازمان شما باید یک گواهی SSL در گوگل ثبت کند و تمام درخواست‌های مربوط به آن فیدهای داده را امضا کند.

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