استخدام AuthSub مع مكتبة برامج ‎ .NET

جيف فيشر، فريق Google Data APIs
أغسطس 2007

مقدمة: ما أهمية AuthSub؟

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

لنفترض أنّ لديك تطبيق ويب جديدًا رائعًا تريد ربطه بالبيانات المخزّنة في خدمات الويب من Google. عليك الآن إثبات هويتك للوصول إلى هذه البيانات الخاصة. لماذا لا نستخدم شيئًا بسيطًا، مثل ClientLogin؟ حسنًا، سيؤدي ذلك الغرض، ولكنّك ستتعامل بعد ذلك مع المزيد من البيانات الخاصة، وهي بيانات اعتماد تسجيل الدخول الخاصة بالمستخدم. يتطلّب ClientLogin أن يطلب تطبيقك من المستخدم إدخال اسم المستخدم وكلمة المرور المرتبطين بحساب Google. لا بأس في ذلك بالنسبة إلى تطبيق كمبيوتر مكتبي يعمل على جهاز المستخدم الشخصي، ولكنّه ليس مثاليًا لتطبيق مستند إلى الويب. بالإضافة إلى مسؤولية التعامل مع بيانات الاعتماد هذه على الخادم الخاص بك، قد يخشى بعض المستخدمين الأكثر حذرًا من أن تخزّن معلوماتهم. من المخاوف الشائعة الأخرى لدى المستخدمين ما إذا كانوا يريدون منح برنامج إذن الوصول إلى خدمة معيّنة فقط (مثل الأحداث في "تقويم Google") وليس إلى خدمة أخرى (مثل "مستندات Google"). يحلّ AuthSub هاتين المشكلتين من خلال السماح للمستخدم بالمصادقة من خلال خوادم Google والسماح لبرنامجك بطلب الوصول الذي يحتاج إليه فقط.

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

التعامل مع المصادقة

إذًا، ما هي المتطلبات اللازمة لاستخدام AuthSub في تطبيق الويب؟ أولاً، هناك بعض عمليات الاستيراد العادية من مكتبة برامج GData:

<%@ Import Namespace="Google.GData.Client" %>
<%@ Import Namespace="Google.GData.Extensions" %>
<%@ Import Namespace="System.Net" %>

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

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target: هذه السمة عبارة عن سلسلة تحتوي على عنوان URL لتطبيق الويب. هذا هو المكان الذي سيتم إعادة توجيه المستخدم إليه بعد المصادقة.
  • النطاق: يتم تحديد هذه السلسلة حسب واجهة برمجة التطبيقات التي تستخدمها. وهي تتوافق مع إحدى الخلاصات في GData API. على سبيل المثال، الخلاصة التي تحتوي على جميع معلومات التقويم الخاصة بمستخدم هي "http://www.google.com/calendar/feeds/default/private/full".
  • secure: قيمة منطقية تُعلم الخادم بأنّك سجّلت لدى Google وأنّك ستوقّع طلباتك إلى الخادم بشكل مشفّر. عادةً ما تكون قيمة هذا الوسيط خطأ تلقائيًا، خاصةً عند العمل في بيئة اختبار.
  • session: قيمة منطقية أخرى تشير إلى أنّك تريد "رمزًا مميزًا للجلسة" بدلاً من "رمز مميز للاستخدام لمرة واحدة". سيتضح دور هذه الحجة بعد قليل.

بعد أن ينقر المستخدم على عنوان URL الذي تم إنشاؤه، سيتم نقله إلى صفحة "حسابات Google" التي تتيح له تسجيل الدخول إلى حسابه على Google. بعد ذلك، ستتم إعادة توجيههم إلى صفحة الويب التي حدّدتها في المتغيّر "target"، ولكن مع مَعلمة طلب البحث "token" التي تحتوي على رمز مميّز يُستخدَم لمرة واحدة. عادةً، يمكن استخدام هذا الرمز المميز مرة واحدة فقط. وهذا يعني أنّه يمكن استخدامها لتنفيذ إجراء واحد على خلاصة معيّنة. ومع ذلك، إذا حدّدت المَعلمة "session" على true، يمكن استبدالها بـ "رمز مميّز للجلسة" يمكن إعادة استخدامه إلى أن ينهي المستخدِم الجلسة. يمكنك إجراء ذلك باتّباع الخطوات التالية:

String token = Request.QueryString["token"];
Session["token"] = AuthSubUtil.exchangeForSessionToken(token, null).ToString();

في هذه الخطوة، يمكنك استخراج الرمز المميّز من مَعلمة طلب البحث واستبداله بـ "رمز مميّز للجلسة". بعد ذلك، ولحفظه لاستخدامه لاحقًا، يمكنك اختيار تخزينه في مصفوفة Session التلقائية في .NET. وبطبيعة الحال، يمكنك أيضًا اختيار تخزين الرمز المميز في قاعدة بيانات. الخطوة التالية هي استخدام هذا الرمز المميز لتقديم طلب مصادقة:

GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "My-Cool-Application");
authFactory.Token = (String) Session["token"];
CalendarService service = new CalendarService(authFactory.ApplicationName);
service.RequestFactory = authFactory;

يمكنك هنا إعداد عنصر CalendarService للتفاعل مع واجهة برمجة التطبيقات Google Calendar API باستخدام AuthSub للمصادقة. يُرجى العِلم أنّ "cl" المستخدَمة في الدالة الإنشائية لـ GAuthSubRequestFactory هي اسم خدمة "تقويم Google". يمكنك الرجوع إلى الأسئلة الشائعة حول Google Data APIs لمعرفة أسماء الخدمات الأخرى.

Secure (Registered) AuthSub

إذا اخترت تسجيل تطبيق الويب، يمكنك تفعيل مستوى أمان إضافي أثناء استخدام AuthSub. يتيح لك ذلك التوقيع رقميًا على جميع الطلبات التي يقدّمها الرمز البرمجي، ما يمنع أي شخص من استخدام رموز AuthSub المميزة الصادرة لك ما لم يكن لديه مفتاحك الخاص. تتمثّل الخطوة الأولى في التأكّد من إنشاء رابط AuthSub الصحيح عند طلب AuthSubUtil.getRequestUrl من خلال ضبط وسيطة "secure" على true. هناك تغييران آخران على الرمز عليك إجراؤهما:

String token = Request.QueryString["token"];
Session["token"] = AuthSubUtil.exchangeForSessionToken(token, rsaKey).ToString();

...

authFactory.PrivateKey = rsaKey;

أولاً، بدلاً من null، يمكنك الآن تمرير المتغيّر "rsaKey" إلى الطريقة exchangeForSessionToken. يتم استخدام المتغيّر نفسه أيضًا لضبط إحدى خصائص GAuthSubRequestFactory عند إعداد عملية الربط بالخدمة. المتغير "rsaKey" هو RSACryptoServiceProvider يتوافق مع مكوّن المفتاح الخاص لشهادة x509 التي سجّلتها لدى Google.

قد يكون إنشاء مفتاح خاص RSA وشهادة موقعة ذاتيًا أمرًا مربكًا بعض الشيء، خاصةً أنّ إطار عمل ‎ .NET لا يفهم المفاتيح أو الشهادات المخزَّنة بتنسيق PEM. توضّح الأوامر التالية كيفية إنشاء مفتاح خاص وشهادة عامة باستخدام مجموعة أدوات OpenSSL:

openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  test_key.pem -out test_cert.pem

openssl pkcs12 -export -in test_cert.pem -inkey test_key.pem \
  -out test_cert.pfx -name "Testing Certificate"

تنشئ الخطوة الأولى مفتاحًا خاصًا وشهادة X509 عامة بتنسيق PEM، ويُطلق عليهما اسم "test_key.pem" و "test_cert.pem" على التوالي. لاحظ أنّه تم ضبط الشهادة ليتم تسجيلها على "www.example.com" في ماونتن فيو، كاليفورنيا، الولايات المتحدة. استبدِل القيم المناسبة لشركتك هنا. يحتوي الملف "test_cert.pem" على المعلومات التي تحتاج إلى إرسالها في صفحة تسجيل AuthSub.

تنشئ الخطوة الثانية ملف PFX من مفتاحك الخاص وشهادتك. يمكن استيراد هذا الملف إلى مكتبة برامج عميل ‎ .NET لتوقيع الطلبات المرسَلة إلى GData APIs رقميًا. يوضّح الرمز التالي كيفية استيراد المفتاح الخاص من ملف PFX إلى تطبيق ويب:

protected AsymmetricAlgorithm getRsaKey()
{

  X509Certificate2 cert = new X509Certificate2("C:/MyAspSite/test_cert.pfx","");
  RSACryptoServiceProvider privateKey = cert.PrivateKey as RSACryptoServiceProvider;

  return privateKey;
}

يمكن استخدام الدالة getRsaKey() المحدّدة بواسطة هذا المقتطف بدلاً من المتغيّر "rsaKey" الموضّح أعلاه عند استخدامها للمصادقة على واجهات برمجة التطبيقات. بالطبع، يجب استبدال مسار الملف بالموقع المناسب لملف PFX الذي أنشأته.

قائمة الرموز البرمجية الكاملة

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

<%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<%@ Import Namespace="Google.GData.Client" %>
<%@ Import Namespace="Google.GData.Extensions" %>
<%@ Import Namespace="Google.GData.Calendar" %>
<%@ Import Namespace="System.Net" %>

<script runat="server">
    void PrintCalendar() {

        GAuthSubRequestFactory authFactory = new GAuthSubRequestFactory("cl", "TesterApp");
        authFactory.Token = (String) Session["token"];
        CalendarService service = new CalendarService(authFactory.ApplicationName);
        service.RequestFactory = authFactory;

        EventQuery query = new EventQuery();

        query.Uri = new Uri("http://www.google.com/calendar/feeds/default/private/full");

        try
        {
            EventFeed calFeed = service.Query(query);
            foreach (Google.GData.Calendar.EventEntry entry in calFeed.Entries)
            {
                Response.Write("Event: " + entry.Title.Text + "<br/>");
            }
        }
        catch (GDataRequestException gdre)
        {
            HttpWebResponse response = (HttpWebResponse)gdre.Response;
            
            //bad auth token, clear session and refresh the page
            if (response.StatusCode == HttpStatusCode.Unauthorized)
            {
                Session.Clear();
                Response.Redirect(Request.Url.AbsolutePath, true);
            }
            else
            {
                Response.Write("Error processing request: " + gdre.ToString());
            }
        }
    }

</script>


<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Test Site</title>
</head>
<body>

    <form id="form1" runat="server">
    <h1>AuthSub Sample Page</h1>
    <div>
    <%
        GotoAuthSubLink.Visible = false;
        
        if (Session["token"] != null)
        {
            PrintCalendar();
        }
        else if (Request.QueryString["token"] != null)
        {
            String token = Request.QueryString["token"];
            Session["token"] = AuthSubUtil.exchangeForSessionToken(token, null).ToString();
            Response.Redirect(Request.Url.AbsolutePath, true);
        }
        else //no auth data, print link
        {
            GotoAuthSubLink.Text = "Login to your Google Account";
            GotoAuthSubLink.Visible = true;
            GotoAuthSubLink.NavigateUrl = AuthSubUtil.getRequestUrl(Request.Url.ToString(),
                "http://www.google.com/calendar/feeds/",false,true);
        }
        
     %>
    <asp:HyperLink ID="GotoAuthSubLink" runat="server"/>

    </div>
    </form>
</body>
</html>

الخاتمة

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