استخدام AuthSub في ActionScript

يوضّح هذا المستند كيفية استخدام نظام المصادقة AuthSub من Google من تطبيق Flash أو Silverlight.

ملاحظة: إذا كنت على دراية بخدمة AuthSub، وهي خدمة مصادقة الحساب من Google للتطبيقات المستندة إلى الويب، ستلاحظ أنّ خدمة AuthSub لـ ActionScript تتشابه معها من الناحية المفاهيمية. يختلف التنفيذ الأساسي، ولكن هذه الاختلافات ليست مهمة بالنسبة إليك كمطوّر لتطبيق العميل. في بعض المستندات، وفي السياقات التي لا يكون فيها التمييز مهمًا، نشير إلى AuthSub لـ ActionScript باسم "AuthSub" باختصار.

تتيح واجهة AuthSub لـ ActionScript للتطبيقات المستندة إلى Flash أو Silverlight المصادقة على خلاصات Google Data API المحمية بالنيابة عن المستخدم. للحفاظ على مستوى عالٍ من الأمان، تتيح الواجهة للتطبيق الحصول على رمز مميّز للمصادقة بدون الحاجة إلى معالجة معلومات تسجيل الدخول إلى حساب المستخدم.

‫AuthSub لـ ActionScript هو نوع من AuthSub لـ JavaScript. مثل AuthSub لـ JavaScript، يوفّر هذا الإطار طريقة متعددة النطاقات لتطبيقات العميل من أجل المصادقة من صفحة ويب مستضافة على نطاق غير تابع لـ Google. يختلف عن AuthSub العادي في أنّ خدمة المصادقة تقع على نطاق مختلف (accounts.googleapis.com بدلاً من www.google.com) وتوفّر ملف crossdomain.xml يسمح بالوصول إلى هذا النطاق من المواقع الإلكترونية الخارجية.

يمكنك أيضًا الاطّلاع على مجموعة Google Accounts API لمناقشة استخدام جميع واجهات برمجة التطبيقات لخدمة المصادقة.

الجمهور

هذا المستند موجّه إلى المبرمجين الذين يطوّرون تطبيقات ويب تستخدم Flash أو Silverlight وتصل إلى خدمات Google.

يفترض هذا المستند أنّك على دراية بالأفكار العامة التي تستند إليها بروتوكولات Google Data APIs وواجهة AuthSub. ويفترض أيضًا أنّك تعرف كيفية البرمجة بلغة ActionScript.

البيئات المتوافقة

يتوافق AuthSub مع ActionScript حاليًا مع الإصدار 1.5 والإصدارات الأحدث من Firefox والإصدار 6.0 والإصدارات الأحدث من Internet Explorer، مع الإصدار 9.0 أو الإصدارات الأحدث من Flash أو الإصدار 2.0 أو الإصدارات الأحدث من Silverlight.

طريقة عمل AuthSub لـ ActionScript

في ما يلي ملخّص سريع لطريقة عمل الاتصال بين تطبيق ويب وخدمة "مصادقة Google" وخدمة "بيانات Google":

للوصول إلى إحدى خدمات "بيانات Google" نيابةً عن مستخدم، يجب أن يتضمّن تطبيق الويب رمزًا مميزًا صالحًا للمصادقة. عادةً، تخزِّن التطبيقات هذا الرمز المميز في ملف تعريف ارتباط. وإذا لم يكن هناك ملف تعريف ارتباط من هذا النوع، يجب أن يحصل تطبيق الويب على الرمز المميز من خلال AuthSub. للحصول على رمز مميز، يرسل تطبيق الويب طلب تسجيل دخول AuthSub إلى خدمة المصادقة، مع تحديد الخدمة المطلوب الوصول إليها.
عند تلقّي الطلب من تطبيق الويب، تعيد خدمة المصادقة توجيه المستخدم إلى صفحة "طلب الوصول". تطلب هذه الصفحة من المستخدم تسجيل الدخول إلى حسابه على Google، كما تطلب منه منح الإذن بالوصول إلى خدمة Google أو رفضه.
يقرّر المستخدم ما إذا كان سيمنح تطبيق الويب إذن الوصول إلى البيانات أو يرفضه. إذا رفض المستخدم منح الإذن، سيتم توجيهه إلى صفحة Google بدلاً من العودة إلى تطبيق الويب.
إذا سجّل المستخدم الدخول بنجاح ومنح الإذن بالوصول، ستعيد خدمة المصادقة توجيه المستخدم إلى عنوان URL لتطبيق الويب الذي أجرى الطلب الأصلي. تعمل عملية إعادة التوجيه على تقديم رمز مصادقة للخدمة المحدّدة من خلال مَعلمة طلب بحث. يجب أن يخزّن التطبيق الرمز المميّز كملف تعريف ارتباط في متصفّح المستخدم ضمن نطاق تطبيق الويب. يكون الرمز المميز صالحًا إلى أن يتم إبطاله. (يُرجى الاطّلاع على قسم لمحة عن الرموز المميزة للحصول على نصائح حول الوقت المناسب لإبطال الرموز المميزة).
يتواصل تطبيق الويب مع خدمة "بيانات Google" ويرسل الرمز المميز للمصادقة مع كل طلب يتم إرساله إلى الخدمة.
إذا تعرّفت خدمة "بيانات Google" على الرمز المميز، فإنّها تقدّم البيانات المطلوبة.

استخدام واجهة AuthSub لـ ActionScript

توفّر AuthSub لـ ActionScript، أو AuthSubAS، نقطة نهاية AuthSub متعددة النطاقات لتطبيقات Flash (أو Silverlight) التي تستخدم Google Data APIs.

توفّر AuthSubAS نسخة طبق الأصل من نقاط نهاية AuthSub المتوفّرة على google.com، مع ملف crossdomain.xml إضافي يتيح لبرنامج Flash (أو Silverlight) الوصول إلى نقاط النهاية هذه. على سبيل المثال، يمكن استخدام نقطة النهاية AuthSubSessionToken من خلال الوصول إلى https://accounts.googleapis.com/accounts/AuthSubSessionToken.

توضّح الخطوات التالية عملية الحصول على رمز مصادقة واستخدامه للوصول إلى إحدى خدمات Google من تطبيق Flash.

إعداد السياسات على جميع النطاقات

لاستخدام 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'.

ملاحظات:
- ننصحك بشدة بتوفير زر تسجيل دخول أو آلية أخرى لإدخال بيانات المستخدم تطلب منه بدء عملية تسجيل الدخول يدويًا. إذا وضعت علامة في المربّع وأعدت التوجيه فور التحميل بدون انتظار تفاعل المستخدم، فإنّ أول ما يراه المستخدم عند وصوله إلى صفحتك هو صفحة تسجيل الدخول إلى Google. إذا قرّر المستخدم عدم تسجيل الدخول، لن يعيده Google إلى صفحتك، وبالتالي من وجهة نظر المستخدم، حاول زيارة صفحتك ولكن تم إرساله بعيدًا ولم تتم إعادته. قد يكون هذا السيناريو محيِّرًا ومحبطًا للمستخدمين.
- يجب أن تطلب التطبيقات التي تحتاج إلى الوصول إلى أكثر من خدمة واحدة من Google للمستخدم رمزًا مميزًا جديدًا لكل خدمة جديدة (لأنّ لكل خدمة نطاقًا مختلفًا).

اطلب رمزًا مميزًا للمصادقة.

ستعرض نقطة النهاية AuthSubRequest رمزًا مميزًا صالحًا للاستخدام مرة واحدة في تطبيقك من خلال ضبط عنوان URL لمتصفّح المستخدم على http://yourWebAppUrl?token=singleUseToken. بعد أن يتلقّى تطبيقك الرمز المميز للاستخدام لمرة واحدة، يجب أن يستبدله برمز مميز متعدد الاستخدامات (طويل الأمد)، والذي يمكن استخدامه بعد ذلك لتقديم طلبات إلى خلاصات بيانات Google. لإجراء ذلك، استدعِ طريقة 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 لخدمة "صور Google":

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

عرض النموذج الكامل

تنصح Google بتوفير ميزة تسجيل الخروج يدويًا، مثل زر تسجيل الخروج أو رابط قابل للنقر. يمنح هذا الأسلوب المستخدمين خيار تسجيل الخروج متى أرادوا، أو البقاء مسجّلين الدخول وإبقاء خلاصات البيانات متاحة بسهولة عند الوصول إلى تطبيقك في المرة القادمة.

لمحة عن الرموز المميزة

يوضّح هذا القسم الرموز المميزة التي تستخدمها AuthSub لـ ActionScript. في معظم السياقات، لن تحتاج إلى معرفة هذه المعلومات.

يكون كل رمز مميز للمصادقة خاصًا بالبيانات التالية:

نطاق خدمة Google
حساب المستخدم على Google
تطبيق العميل

تضمن بيانات الرمز المميّز أنّه يمكن للتطبيق الخارجي المحدّد فقط طلب البيانات وأنّ الطلب يقتصر على البيانات من النطاق وحساب المستخدم المحدّدين.

يمكن أن تكون رمز مميّز واحد فقط صالحًا لهذه المجموعة من النطاق والمستخدم والعميل في أي وقت. يجب أن يطلب تطبيق الويب رمزًا مميّزًا جديدًا في كل مرة يحتاج فيها إلى الوصول إلى خدمة جديدة من Google لمستخدم معيّن. يعتمد نطاق الوصول الذي يغطّيه الرمز المميّز على خدمة Google، التي يمكنها اختيار حصر الوصول إلى أنواع معيّنة من البيانات أو الأنشطة، مثل إذن الوصول للقراءة فقط.

يمكن استخدام الرمز المميز الذي تعرضه واجهة AuthSub لـ ActionScript عدة مرات حسب الحاجة إلى أن يتم إبطاله. ويعود إلى تطبيقك إدارة مدة صلاحية الرمز المميز، مع تحقيق التوازن بين الأمان والراحة. تنصح Google بطلب رمز مميّز جديد في كل مرة يتم فيها بدء جلسة جديدة.

قد تسمح بعض خدمات Google بالوصول إليها من خلال تطبيقات الويب المسجّلة والتي تستخدم الرموز المميزة الآمنة فقط. لا تتوافق خدمة AuthSub مع ActionScript في هذه الخدمات. لاستخدام الرموز المميزة الآمنة، يجب أن تسجّل مؤسستك شهادة SSL لدى Google وتوقّع جميع الطلبات الخاصة بخلاصات البيانات هذه.

الرجوع إلى الأعلى

استخدام AuthSub في ActionScript تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الجمهور

البيئات المتوافقة

طريقة عمل AuthSub لـ ActionScript

استخدام واجهة AuthSub لـ ActionScript

لمحة عن الرموز المميزة

استخدام AuthSub في ActionScript