.NET Client Library ile AuthSub'ı kullanma

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

Giriş: AuthSub Neden Önemli?

Google Veri API'lerinin en iyi yönü ("kısaca GData"), geliştiricilerin Google hizmetleriyle etkileşime giren uygulamalar derlemelerine olanak tanımasıdır. Daha ayrıntılı belirtmek gerekirse, bu politikalar, uygulamanızda kullanılmak üzere gizli kullanıcı verilerine erişmenize olanak tanır. API'ler, verileri senkronize etmek, içe aktarmak, dışa aktarmak veya başka şekilde yönetmek için uygulama yazmanıza olanak tanır. API'ler size bu güçlü özellikleri sunar, ancak bunları sorumlu bir şekilde kullanmayı unutmayın. Kullanıcı verileri gizli olduğundan, doğal olarak bunlara güvenli bir şekilde erişmek istersiniz. Bunun önemli bir parçası da Google sunucuları için güvenli bir şekilde kimlik doğrulaması yapabilmektir.

Google web hizmetlerinde depolanan verilere bağlı olmasını istediğiniz harika bir yeni web uygulamanız olduğunu varsayalım. Şimdi bu gizli verilere erişmek için kimlik doğrulaması yapmak istiyorsunuz. Neden sadece ClientLogin gibi basit bir hizmet kullanmıyorsunuz? Aslında bu sorunu çözecektir ama siz daha gizli verileri işliyorsunuz: Kullanıcının giriş kimlik bilgileri. ClientLogin, uygulamanızın kullanıcının Google kullanıcı adını ve şifresini istemesini gerektirir. Bu, kullanıcının kişisel makinesinde çalışan bir masaüstü uygulaması için uygundur, ancak web tabanlı bir uygulama için idealdir. Bu kimlik bilgilerini kendi sunucunuzda yönetmenin sorumluluğu dışında, daha dikkatli olan bazı kullanıcılarınız da bilgilerini saklamaktan korkabilir. Kullanıcılar, bir program için yalnızca belirli bir hizmete (Google Takvim'deki etkinlikler gibi) erişim vermek isterlerken diğer bir hizmete (Google Dokümanlar gibi) erişim vermek isterler. AuthSub bir kullanıcının Google sunucuları üzerinden kimlik doğrulaması yapmasına izin vererek bu iki sorunu da çö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, şimdi kodlamaya geçebiliriz. Bu makale için işleri basit tutmayı ve her şeyi tek bir ASP sayfasında yapmayı seçtim, ancak burada gösterilen teknikleri kendi uygulamanıza kolayca entegre edebilmeniz gerekir.

Kimlik Doğrulaması İşleme

Peki, web uygulamanızda AuthSub'ı gerçekten kullanmak için ne gerekir? Öncelikle, GData istemci kitaplığından bazı standart içe aktarma işlemleri vardır:

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

Yapmanız gereken ilk şey kullanıcıyı özel olarak tasarlanmış bir URL'ye göndermektir. Bu, Google sunucularının kimlik doğrulamayı işlemesine ve ardından kullanıcıyı tekrar web sitenize yönlendirmesine olanak tanır. Neyse ki, bu işlemi sizin için yapabileceğiniz çeşitli yöntemler olduğundan manuel olarak bu URL'yi oluşturmanız gerekmiyor. Bir örneğe bakalım:

authSubUrl = AuthSubUtil.getRequestUrl(target, scope, secure, session);
  • target Bu, web uygulamanızın URL'sini içeren bir dizedir. Kimlik doğrulamasından sonra kullanıcı bu adrese yönlendirilir.
  • kapsam Bu dize, kullandığınız API'ye göre belirlenir. GData API'sindeki feed'lerden birine karşılık gelir. Örneğin, bir kullanıcıya ilişkin tüm takvim bilgilerini içeren özet akışı "http://www.google.com/calendar/feeds/default/private/full"dur.
  • secure Bu, sunucuya Google'a kaydolduğunuzu bildiren ve isteklerinizi sunucuya kriptografik olarak imzalayacak bir boole'dir. Özellikle bir test ortamında çalışırken bu bağımsız değişken varsayılan olarak yanlıştır.
  • Oturum "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ü biraz sonra daha net hale gelecek.

Oluşturulan URL'yi tıklayan kullanıcılar, Google hesaplarında oturum açmalarına olanak tanıyan bir Google Hesapları sayfasına yönlendirilir. Bu URL'ler, daha sonra "hedef" değişkeninde belirttiğiniz web sayfasına, ancak tek kullanımlık jeton içeren bir sorgu parametresi olan "jeton"a tekrar yönlendirilir. Normalde bu jeton yalnızca bir kez kullanılabilir. Yani belirli bir feed'de bir işlem gerçekleştirmek için kullanılabilir. Ancak "session" parametresini true olarak belirlediyseniz bu parametre, kullanıcı oturumu sonlandırana kadar yeniden kullanılabilen bir "oturum jetonu" ile değiştirilebilir. Bunu aşağıdaki şekilde yapabilirsiniz:

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

Burada, jetonu sorgu parametresinden çıkarır ve "oturum jetonu" ile değiştirirsiniz. Ardından, bu jetonun daha sonra kullanılmak üzere kaydedilebilmesi için .NET'in otomatik Session dizisinde saklamayı seçebilirsiniz. Doğal olarak, jetonu bir veritabanında saklamayı da seçebilirsiniz. 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ğrulaması için AuthSub'ı kullanarak Google Calendar API ile etkileşimde bulunacak bir TakvimService nesnesi oluşturabilirsiniz. GAuthSubRequestFactory için oluşturucuda kullanılan "cl" ifadesinin Takvim için hizmet adı olduğunu unutmayın. Diğer hizmet adları için Google Veri API'leri Hakkında SSS bölümünü inceleyebilirsiniz.

Güvenli (Kayıtlı) AuthSub

Web uygulamanızı kaydetmeyi seçerseniz AuthSub'ı kullanırken ek bir güvenlik düzeyini etkinleştirebilirsiniz. Bu işlem, kodunuzdan yapılan tüm istekleri dijital olarak imzalamanızı sağlar. Böylece özel anahtarınız yoksa bir kullanıcı size verilen AuthSub jetonlarını kullanamaz. İlk adım, "secure" bağımsız değişkenini true olarak ayarlayarak AuthSubUtil.getRequestUrl yöntemini çağırırken 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 "rsaKey" değişkenini exchangeForSessionToken yöntemine ilettiğinizi unutmayın. Aynı değişken, hizmetle bağlantıyı ayarlarken GAuthSubRequestFactory özelliğimizin ö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 değeridir.

Özellikle .NET çerçevesi PEM biçiminde depolanan anahtarları veya sertifikaları anlamadığından, bir RSA özel anahtarı ve kendinden imzalı sertifika oluşturmak biraz kafa karıştırıcı olabilir. Aşağıdaki komutlar, OpenSSL araç paketini kullanarak nasıl özel anahtar ve genel sertifika oluşturacağınızı 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ım, sırasıyla "test_key.pem" ve "test_cert.pem" adlı PEM biçiminde bir özel anahtar ve bir genel X509 sertifikası oluşturur. Sertifikanın Mountain View, CA, ABD'de bulunan "www.example.com" adresine kaydedilecek şekilde ayarlandığını unutmayın. Buraya şirketiniz için uygun değerleri girin. "test_cert.pem" dosyası, AuthSub kayıt sayfasında göndermeniz gereken bilgileri içerir.

İkinci adım, özel anahtarınızdan ve sertifikanızdan bir PFX dosyası oluşturur. 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 tarafından tanımlanan getRsaKey() işlevi, API'lere kimlik doğrulaması yapmak için kullanıldığında yukarıda gösterilen "rsaKey" değişkeninin yerine kullanılabilir. Doğal olarak dosya yolu, oluşturduğunuz PFX dosyasının uygun konumuyla değiştirilmelidir.

Kod Listesini Tamamlayın

Önceki bölümde gösterilen yöntemlerin nasıl kullanılacağını göstermenin en kolay yolu, canlı bir örnektir. Aşağıdaki örnek kod, kullanıcının kimliğini doğrulamak için AuthSub'ı kullanan ve ardından kullanıcının Google Takvim'indeki etkinliklerini 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 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şlamanıza yardımcı olmak için hazırlanmıştır. Bununla birlikte, danışmanızı önerdiğimiz ek kaynaklar mevcuttur: