.NET istemci kitaplığıyla AuthSub'ı kullanma

Jeff Fisher, Google Data API'leri Ekibi
Ağustos 2007

Giriş: AuthSub neden önemlidir?

Google Veri API'lerinin (kısaca "GData") en iyi özelliği, geliştiricilerin Google hizmetleriyle etkileşim kuran uygulamalar oluşturmasına olanak tanımasıdır. Daha spesifik olarak, uygulamanızda kullanmak üzere gizli kullanıcı verilerine erişmenize olanak tanırlar. API'ler, bu verileri senkronize etmek, içe ve dışa aktarmak ve başka şekillerde yönetmek için uygulamalar yazmanıza olanak tanır. API'ler size bu güçlü yetenekleri sunsa da bunları sorumlu bir şekilde kullanmanız gerektiğini unutmayın. Kullanıcı verileri gizli bilgiler olduğundan, bu verilere doğal olarak güvenli bir şekilde erişmek istersiniz. Bunun önemli bir parçası, Google'ın sunucularında güvenli bir şekilde kimlik doğrulaması yapabilmektir.

Google web hizmetlerinde depolanan verilere bağlanmasını istediğiniz harika bir yeni web uygulamanız olduğunu varsayalım. Şimdi bu özel verilere erişmek için kimlik doğrulaması yapmak istiyorsunuz. Neden ClientLogin gibi basit bir yöntem kullanmıyorsunuz? Bu yöntem işe yarar ancak bu durumda kullanıcının giriş kimlik bilgileri gibi daha fazla özel veriyi işlemeniz gerekir. ClientLogin, uygulamanızın kullanıcının Google kullanıcı adını ve şifresini istemesini gerektirir. Bu durum, kullanıcının kişisel makinesinde çalışan bir masaüstü uygulaması için uygundur ancak web tabanlı bir uygulama için ideal değildir. Bu kimlik bilgilerini kendi sunucunuzda işlemenin sorumluluğunun yanı sıra, daha temkinli kullanıcılarınızdan bazıları bilgilerini saklayabileceğinizden korkabilir. Kullanıcıların bir diğer yaygın endişesi de bir programa yalnızca belirli bir hizmete (ör. Google Takvim'deki etkinlikler) erişim izni vermek istemeleri ancak başka bir hizmete (ör. Google Dokümanlar) erişim izni vermek istememeleridir. AuthSub, kullanıcının Google'ın sunucuları üzerinden kimliğini doğrulamasına izin vererek bu sorunların ikisini de çözer ve programınızın yalnızca ihtiyaç duyduğu erişimi istemesine olanak tanır.

AuthSub'ın arkasındaki teori hakkında yeterince bilgi edindiğinize göre artık kodlamaya geçebilirsiniz. Bu makalede, her şeyi tek bir ASP sayfasında yaparak basit tutmayı tercih ettim ancak burada gösterilen teknikleri kendi uygulamanıza kolayca entegre edebilirsiniz.

Kimlik Doğrulamayı İşleme

Peki, web uygulamanızda AuthSub'ı kullanmak için ne gerekir? İlk olarak, GData istemci kitaplığından yapılan bazı standart içe aktarma işlemleri vardır:

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

Şimdi yapmanız gereken ilk şey, kullanıcıyı özel olarak hazırlanmış bir URL'ye yönlendirmektir. Bu, Google'ın sunucularının kimlik doğrulamayı işlemesine ve ardından kullanıcıyı web sitenize geri yönlendirmesine olanak tanır. Neyse ki bu URL'yi sizin için oluşturacak yöntemler olduğundan manuel olarak oluşturmanız gerekmez. Bunu bir örnek üzerinde inceleyelim:

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target: Bu, web uygulamanızın URL'sini içeren bir dizedir. Kullanıcı, kimlik doğrulama işleminden sonra buraya yönlendirilir.
  • scope: Bu dize, kullandığınız API'ye göre belirlenir. Bir GData API'sindeki feed'lerden birine karşılık gelir. Örneğin, bir kullanıcının tüm takvim bilgilerini içeren feed "http://www.google.com/calendar/feeds/default/private/full" şeklindedir.
  • secure: Bu, Google'a kaydolduğunuzu ve sunucuya yaptığınız istekleri kriptografik olarak imzalayacağınızı sunucuya bildiren bir boole değeridir. Bu bağımsız değişken genellikle varsayılan olarak yanlıştır. Özellikle test ortamında çalışırken bu durum geçerlidir.
  • session: Bu, "tek kullanımlık jeton" yerine "oturum jetonu" istediğinizi belirten başka bir boole değeridir. Bu bağımsız değişkenin rolü birazdan daha netleşecek.

Kullanıcı, oluşturulan URL'yi tıkladıktan sonra Google Hesabı'nda oturum açmasına olanak tanıyan bir Google Hesapları sayfasına yönlendirilir. Ardından, "target" değişkeninde belirttiğiniz web sayfasına geri yönlendirilirler. Ancak bu yönlendirme, tek kullanımlık bir jeton içeren "token" adlı bir sorgu parametresiyle yapılır. Normalde bu jeton tam olarak bir kez kullanılabilir. Yani, belirli bir feed'de tek bir işlem gerçekleştirmek için kullanılabilir. Ancak "session" parametresini true olarak belirttiyseniz bu parametre, kullanıcı oturumu sonlandırana kadar yeniden kullanılabilen bir "oturum jetonu" ile değiştirilebilir. Bu işlemi aşağıdaki şekilde yapabilirsiniz:

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

Burada, sorgu parametresinden jetonu çıkarıp "oturum jetonu" ile değiştirirsiniz. Daha sonra kullanmak üzere kaydetmek için .NET'in otomatik Session dizisinde saklamayı seçebilirsiniz. Elbette jetonu bir veritabanında da saklayabilirsiniz. Bir sonraki adım, kimliği doğrulanmış bir istekte bulunmak için bu jetonu kullanmaktır:

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

Burada, kimlik doğrulama için AuthSub'ı kullanarak Google Calendar API ile etkileşim kurmak üzere bir CalendarService nesnesi oluşturursunuz. GAuthSubRequestFactory oluşturucusunda kullanılan "cl"nin, Takvim'in hizmet adı olduğunu unutmayın. Diğer hizmet adları için Google Veri API'leri Hakkında SSS başlıklı makaleyi inceleyebilirsiniz.

Güvenli (kayıtlı) AuthSub

Web uygulamanızı kaydetmeyi seçerseniz AuthSub'ı kullanırken ek bir güvenlik düzeyi etkinleştirebilirsiniz. Bu sayede, kodunuz tarafından yapılan tüm istekleri dijital olarak imzalayabilirsiniz. Böylece, özel anahtarınız olmadan size verilen AuthSub jetonlarını kimse kullanamaz. İlk adım, AuthSubUtil.getRequestUrl çağrısı yaparken "secure" bağımsız değişkenini true olarak ayarlayarak doğru AuthSub bağlantısını oluşturduğunuzdan emin olmaktır. Yapmanız gereken iki kod değişikliği daha vardır:

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

...

authFactory.PrivateKey = rsaKey;

İlk olarak, null yerine artık "rsaKey" değişkenini exchangeForSessionToken yöntemine ilettiğinizi fark edin. Bu değişken, hizmetle bağlantı oluşturulurken GAuthSubRequestFactory özelliğini ayarlamak için de kullanılır. "rsaKey" değişkeni, Google'a kaydettiğiniz x509 sertifikasının özel anahtar bileşenine karşılık gelen bir RSACryptoServiceProvider.

RSA özel anahtarı ve kendinden imzalı sertifika oluşturmak biraz kafa karıştırıcı olabilir. Özellikle .NET Framework, PEM biçiminde depolanan anahtarları veya sertifikaları anlamadığından bu durum daha da zorlaşır. Aşağıdaki komutlar, OpenSSL araç paketini kullanarak özel anahtar ve genel sertifika oluşturma yöntemini gösterir:

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"

İlk adımda, sırasıyla "test_key.pem" ve "test_cert.pem" adlı PEM biçiminde bir özel anahtar ve bir ortak X509 sertifikası oluşturulur. Sertifikanın, Mountain View, CA, ABD'de bulunan "www.example.com" alanına kaydedileceğini unutmayın. Burada şirketiniz için uygun değerleri kullanın. "test_cert.pem" dosyası, AuthSub kayıt sayfasında göndermeniz gereken bilgileri içerir.

İkinci adımda, özel anahtarınız ve sertifikanızdan bir PFX dosyası oluşturulur. Bu dosya, GData API'lerine yapılan istekleri dijital olarak imzalamak için .NET istemci kitaplığına aktarılabilir. Aşağıdaki kod, özel anahtarı PFX dosyasından bir web uygulamasına nasıl aktarabileceğinizi gösterir:

protected AsymmetricAlgorithm getRsaKey()
{

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

  return privateKey;
}

Bu snippet'te tanımlanan getRsaKey() işlevi, API'lerin kimliğini doğrulamak için kullanıldığında yukarıda gösterilen "rsaKey" değişkeninin yerine kullanılabilir. Elbette dosya yolu, oluşturduğunuz PFX dosyasının uygun konumuyla değiştirilmelidir.

Tam Kod Listesi

Önceki bölümde gösterilen yöntemlerin nasıl kullanılacağını göstermenin en kolay yolu canlı bir örnek vermektir. Aşağıdaki örnek kod, kullanıcının kimliğini doğrulamak için AuthSub'ı kullanan ve ardından Google Takvim'deki etkinlikleri yazdıran basit bir ASP sayfasıdır.

<%@ 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>

Sonuç

AuthSub, web uygulamanızın bir kullanıcının Google Hesabı'nda depolanan verilere güvenli ve kontrollü bir şekilde erişmesine olanak tanır. .NET istemci kitaplığını kullanarak ASP tabanlı web sitenizi Google hizmetleriyle kolayca entegre edebilirsiniz. Bu makale, başlangıç sürecinde size yardımcı olmayı amaçlamaktadır. Ancak, incelemenizi önerdiğimiz ek kaynaklar da vardır: