Google Veri API'leri ile OAuth'u kullanma

Eric Bidelman, Google Data APIs team
Eylül 2008

Giriş

Geliştiriciler için heyecan verici bir dönem. Web'de bir dizi açık standardın benimsenmeye başladığını görüyoruz. Bildiğiniz gibi Google, standartların ve açık kaynak topluluğunun geliştirilmesinin her zaman büyük bir destekçisi olmuştur.

Google Veri API'lerinin tamamı kısa süre önce, masaüstü ve web uygulamalarının kullanıcının özel verilerine erişme şeklini standartlaştırmayı amaçlayan açık bir protokol olan OAuth desteğini kullanmaya başladı. OAuth, API kimlik doğrulamasını standart ve güvenli bir şekilde gerçekleştirme olanağı sunar. Programcılar olarak, mümkün olduğunda kodu yeniden kullanmamız öğretilir. OAuth, geliştiricilerin yazdıkları yinelenen kod miktarını azaltmalarına ve çeşitli sağlayıcıların birden fazla hizmetiyle çalışan araçlar oluşturmalarını kolaylaştırmaya yardımcı olur.

Kitle

Bu makalede, Google Veri API'lerinden en az birini bildiğiniz ancak OAuth'un temel kavramlarını bilmediğiniz varsayılır. Yeni başlıyorsanız veya OAuth hakkında bilgi edinmek istiyorsanız doğru yerdesiniz. Bu makale, kavramlarla ilgili temel bilgileri edinmenize yardımcı olacaktır. Ayrıca Google'ın OAuth uygulamasının ayrıntılarını da ele alacağım.

Bu belge, özellikle gelişmiş güvenlik ile kayıtlı modda AuthSub kullanımına aşina olan geliştiriciler için de hazırlanmıştır. İlerleyen bölümlerde, iki protokol arasındaki benzerlikleri ve farklılıkları vurgulamaya çalışacağım. AuthSub kullanan uygulamalarınız varsa daha açık ve modern bir protokol olan OAuth'a geçmek için bu bilgileri kullanabilirsiniz.

Biraz terminoloji

OAuth'u anlamak, terminolojisini anlamakla ilgilidir. OAuth spesifikasyonu ve Google'ın Web Uygulamaları İçin OAuth Kimlik Doğrulaması dokümanları belirli tanımlara büyük ölçüde dayanır. Bu nedenle, Google'ın OAuth uygulaması bağlamında her birinin ne anlama geldiğini açıklayalım.

  1. "OAuth dance"

    Tam OAuth kimlik doğrulama/yetkilendirme sürecini açıklamak için kullandığım resmi olmayan terim.

  2. (OAuth) İstek jetonu

    Google'a uygulamanızın Google Veri API'lerinden birine erişim istediğini bildiren bir başlangıç jetonu. OAuth dansının ikinci adımında kullanıcının verilerine manuel olarak erişim izni vermesi gerekir. Bu adım başarılı olursa istek jetonu yetkilendirilir.

  3. (OAuth) Erişim jetonu

    Dansın son adımı, yetkilendirilmiş istek jetonunu erişim jetonuyla değiştirmektir. Uygulamanız bu jetona sahip olduğunda, jeton iptal edilmediği sürece kullanıcının OAuth sürecini tekrar uygulaması gerekmez.

    AuthSub ile benzerlik:
    OAuth erişim jetonu, güvenli bir AuthSub oturum jetonuyla aynı şeydir.

  4. (OAuth) Uç Noktalar

    Bunlar, bir uygulamanın kimliğini doğrulamak ve erişim jetonu almak için gereken URI'lerdir. Toplamda üç tane vardır. Bunlardan biri OAuth sürecinin her adımı için geçerlidir. Google'ın OAuth uç noktaları şunlardır:

    İstek jetonu alma:https://www.google.com/accounts/OAuthGetRequestToken
    İstek jetonunu yetkilendirin:https://www.google.com/accounts/OAuthAuthorizeToken
    Erişim jetonuna yükseltme:https://www.google.com/accounts/OAuthGetAccessToken

    AuthSub ile benzerlik:
    Yetkilendirilmiş bir istek jetonunu erişim jetonuyla değiştirme, sırasıyla https://www.google.com/accounts/AuthSubRequestToken ve https://www.google.com/accounts/AuthSubSessionToken'de tek kullanımlık bir AuthSub jetonunu uzun süreli bir oturum jetonuna yükseltmeye benzer. Aradaki fark, AuthSub'da ilk istek jetonu kavramının olmamasıdır. Bunun yerine, kullanıcı jeton sürecini AuthSubRequestToken yetkilendirme sayfasından başlatır.

  5. (OAuth) Hizmet Sağlayıcı

    Google Veri API'leri söz konusu olduğunda bu sağlayıcı Google'dır. Genel olarak, hizmet sağlayıcı, OAuth uç noktalarını sağlayan web sitesini veya web hizmetini tanımlamak için kullanılır. OAuth hizmet sağlayıcılarına bir diğer örnek de MySpace'tir.

  6. (OAuth) Tüketici

    Kullanıcının verilerine erişmek için izin isteyen program (ör. uygulamanız). OAuth protokolü, çok çeşitli farklı istemci türlerine (web, yüklü, masaüstü, mobil) izin verdiği için esnektir.

Not: OAuth protokolü, masaüstü/yüklü uygulama kullanım alanını desteklese de Google yalnızca web uygulamaları için OAuth'u destekler.

Başlarken

Kayıt

Google Veri API'lerinde OAuth'u kullanmaya başlamadan önce küçük bir kurulum yapmanız gerekir. Tüm OAuth isteklerinin dijital olarak imzalanması gerektiğinden öncelikle alanınızı kaydetmeniz ve Google'a herkese açık bir sertifika yüklemeniz gerekir. Bunu nasıl yapacağınız hakkında daha fazla bilgi için Web Tabanlı Uygulamalara Kayıt ve Kayıtlı modda kullanılacak anahtarlar ve sertifikalar oluşturma başlıklı makaleleri inceleyin.

İmza istekleri

Alanınız kaydedildikten sonra istekleri imzalamaya başlayabilirsiniz. OAuth'un en zor kavramlarından biri, oauth_signature öğesinin nasıl düzgün şekilde oluşturulacağı ve imza tabanı dizesi kavramıdır. Temel dize, özel anahtarınızla (RSA_SHA1 kullanarak) imzaladığınız verilerdir. Sonuç, oauth_signature için ayarladığınız değerdir.

Örnek istek

GET kullanıcının Google Takvimlerinin listesi http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime

Temel dize biçimi base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters
Örnek temel dize GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Örnek HTTP isteği 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Not: Bu yalnızca bir temsildir. oauth_signature süreniz çok daha uzun olur.

Temel dizeyle ilgili notlar:

  • orderby=starttime sorgu parametresi, oauth_* parametrelerinin geri kalanıyla birlikte sözlük sıralamasına göre sıralanır.
  • Bu dize ? karakteri de içermez.
  • base-http-request-url bölümü yalnızca URL olarak kodlanmış temel URL'yi içerir: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • oauth_token, iki kez URL kodlanmıştır.

Authorization üstbilgisiyle ilgili notlar:

  • oauth_* parametrelerinin Authorization başlığındaki sırası önemli değildir.
  • Üstbilgi, temel dize orderby=starttime içerdiği halde bu karakteri içermiyor. Bu sorgu parametresi, istek URL'sinin bir parçası olarak korunur.

OAuth kullanarak imza isteğinde bulunma hakkında daha fazla bilgi için OAuth İsteklerini İmzalama başlıklı makaleyi inceleyin.

AuthSub'tan farkı:
Karşılaştırma için güvenli AuthSub'ın kullanıldığı aynı örneği aşağıda bulabilirsiniz:

Temel dize biçimi base_string = http-method http-request-URL timestamp nonce
Örnek temel dize 
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Örnek HTTP isteği 
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

AuthSub kullanarak istekleri imzalama hakkında daha fazla bilgi için AuthSub İsteklerini İmzalama başlıklı makaleyi inceleyin.

OAuth Playground Aracı

Amaç

Bazı kullanıcılar, OAuth'un öğrenme sürecinin zorlu olduğunu belirtmiştir. Google'ın diğer kimlik doğrulama API'leriyle karşılaştırıldığında bu ifadeye katılıyorum. OAuth'un avantajı, uygulamanızı diğer (Google dışı) hizmetleri kullanacak şekilde genişlettiğinizde belirginleşir. Farklı hizmet sağlayıcılar ve API'lerinde çalışan tek bir kimlik doğrulama kodu yazmak kulağa hoş geliyor. Protokolü şimdi öğrendiğiniz için daha sonra kendinize teşekkür edeceksiniz.

OAuth Playground, geliştiricilerin OAuth ile ilgili sorunlarını çözmelerine yardımcı olmak için oluşturduğum bir araçtır. Playground'u kullanarak sorunları ayıklayabilir, kendi uygulamanızı kontrol edebilir veya Google Veri API'leriyle denemeler yapabilirsiniz.

Bu sekme ne işe yarar?

  1. OAuth kimlik doğrulama akışını gösterir: istek jetonu getirme, jetonu yetkilendirme ve erişim jetonuna yükseltme.
  2. Her istek için doğru imza tabanı dizesini gösterir.
  3. Her istek için doğru Authorization üstbilgisini gösterir.
  4. Kimliği doğrulanmış bir Google verileri feed'iyle etkileşim kurmak için oauth_token özelliğinin nasıl kullanılacağını gösterir. Verileri GET/POST/PUT/DELETE.
  5. Doğrulanmış bir feed'i doğrudan tarayıcınızda görüntüleyin.
  6. oauth_consumer_key (Kayıtlı alanınız) ve özel anahtarınızı test etmenize olanak tanır.
  7. oauth_token için hangi Google veri feed'i hizmetlerinin kullanılabildiğini öğrenin.

Demo Run

1. adım: Kapsamlarınızı seçin

Öncelikle bir veya daha fazla kapsam seçerek hangi API'leri kullanmak istediğinize karar verin. Bu gösterimde, Blogger ve Google Kişiler ile çalışacak bir jeton istiyorum.

AuthSub ile benzerlik:
AuthSub, jetonun erişebileceği veri aralığını kontrol etmek için scope parametresini de gerektirir. Google, bu parametreyi OAuth spesifikasyonunda önerildiği şekilde uygulamıştır.

2. adım: OAuth parametrelerini ve ayarlarını değiştirin

Şimdilik "OAuth Parametrelerini Değiştirin" kutusundaki hiçbir ayarı değiştirmeyin. Daha sonra, oauth_consumer_key kısmını kayıtlı alanınızla değiştirip "kendi özel anahtarınızı kullanın"ı tıklayarak özel anahtarınızı girip kendi özel anahtarınızla test yapabilirsiniz. Lütfen yalnızca TEST özel anahtarı kullanın.

Not: Burada yalnızca oauth_signature_method ve oauth_consumer_key alanları düzenlenebilir. oauth_timestamp, oauth_nonce ve oauth_token sizin için otomatik olarak oluşturulur.

RSA-SHA1 dışında, oauth_signature_method için HMAC-SHA1 kullanmayı da tercih edebilirsiniz. Bu durumda, Playground'da kendi oauth_consumer_key ve tüketici gizli anahtarınızı girmeniz gereken ek kutular gösterilir. Bu değerleri, kayıtlı alanınızın https://www.google.com/accounts/ManageDomains sayfasında bulabilirsiniz.

AuthSub'dan farkı:
Güvenli AuthSub'da bir alan adını açıkça ayarlamak için parametre yoktur. Alan adı, next URL parametresinin bir parçası olarak eklenir. OAuth'ta oauth_consumer_key adlı bir parametre vardır. Kayıtlı alan adınıza ayarlayın.

3-5. adım: Erişim jetonunu alın

OAuth erişim jetonu almak için üç adım vardır. İlk adım, istek jetonunu almaktır. Bu, Google'a uygulamanızın OAuth dansına başladığını bildirir.

Öncelikle "Jetonu Al" kutusunda "Jeton iste" düğmesini tıklayın.

Belirli alanlar verilerle doldurulur.

  • "İmza için temel dize", oauth_signature parametresini oluşturmak için kullanılan temel dizenin doğru biçimini gösterir.
  • "Yetkilendirme üstbilgisi", istekle ilgili Authorization üstbilgisini gösterir.
  • İstekle gönderilen oauth_nonce ve oauth_timestamp değerleriyle doldurulmuş "OAuth Parametrelerini Değiştir" kutusu.
  • oauth_token girişi, yanıt gövdesinde döndürülen ilgili değerle dolduruldu. Playground'da şu anda hangi tür oauth_token'mız olduğu da gösterilir. Şu anda istek jetonu olarak kullanılıyor.

Ardından, "Get the token" (Jetonu al) kutusunda "Authorize" (Yetkilendir) düğmesini tıklayın.

Bu yetkilendirme sayfasında, istek jetonunu yetkilendirmek ve OAuth Playground'a geri yönlendirilmek için "Erişim İzni Ver" düğmesini tıklayın.

AuthSub ile benzerlik:
Bu yetkilendirme sayfası, AuthSub ile aynıdır.

AuthSub'dan farkı:
AuthSub'ın next URL parametresi, oauth_callback parametresine benzer. Fark, OAuth'ta oauth_callback değerinin isteğe bağlı olmasıdır. Kullanıcı "Erişim izni ver" düğmesini tıkladıktan sonra istek jetonu yetkilendirilir ve jetonun https://www.google.com/accounts/OAuthGetAccessToken olarak yükseltilmesi eşzamansız olarak gerçekleştirilebilir.

İpucu: Web uygulaması yazıyorsanız daha iyi bir kullanıcı deneyimi sağladığı için oauth_callback URL'si belirtmeniz tercih edilir.

Son olarak, "Jetonu Al" kutusunda "Erişim jetonu" düğmesini tıklayın.

Bu işlem, yetkili istek jetonunu (kırmızı "erişim jetonu" etiketiyle belirtildiği gibi) yükseltir.

Yeni bir jeton getirmek istiyorsanız OAuth dansını yeniden başlatmak için "başa dön"ü tıklayın.

Şimdi ilginç bir şeyler yapabiliriz.

Erişim jetonunu kullanma

Artık feed'leri sorgulamaya, veri eklemeye, güncellemeye veya silmeye hazırsınız. Gerçek verilerinizle çalıştığınız için lütfen bu son üç HTTP yöntemini uygularken dikkatli olun.

İpucu: Erişim jetonunuz için kullanılabilen feed'leri keşfetmek üzere "Kullanılabilir feed'ler" düğmesini tıklayın.

Örnek sorgu: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Bu örnek, belirli bir blogda en fazla üç yayın döndürür. Ayrıca, söz dizimi vurgulanmış alanın altındaki "Tarayıcıda görüntüle" bağlantısını tıklayarak döndürülen feed'i/girişi doğrudan tarayıcınızda görüntüleyebilirsiniz.

Örnek: Yayını güncelleme

  1. Güncellemek istediğiniz yayında <link> öğesini rel="edit" ile bulun. Şuna benzer bir şey görmelisiniz: 
    <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

    href URL'sini "Google veri feed'i girin" girişine yapıştırın.

  2. Söz dizimi vurgulanmış panelin üst kısmındaki "view plain " (düz metin olarak göster) seçeneğini tıklayarak mevcut girişin XML'sini kopyalayın. Başlıkları değil yalnızca yanıt gövdesini kopyalayın.
  3. HTTP yöntemi açılır listesini PUT olarak değiştirin.
  4. Bu açılır listenin altındaki "enter post data"yı (yayın verilerini girin) tıklayın ve <entry> XML'sini açılır pencereye yapıştırın.
  5. "Çalıştır" düğmesini tıklayın.

Sunucu 200 OK ile yanıt verir.

İpucu: edit bağlantısını manuel olarak kopyalamak yerine "Söz Dizimi Vurgulama?" onay kutusunun işaretini kaldırın. Bir sorgudan sonra XML yanıt gövdelerindeki bağlantıları tıklayabilirsiniz.

Sonuç

AtomPub/Atom Yayınlama Protokolü (Google Veri API'lerinin temel protokolü) ve OAuth gibi teknolojiler, web'in ilerlemesine yardımcı olur. Bu standartları benimseyen site sayısı arttıkça kazanan biz geliştiriciler olacağız. Çok iyi bir uygulama oluşturmak artık daha az korkutucu.

OAuth Playground veya Google API'leriyle OAuth kullanımı hakkında sorularınız ya da yorumlarınız varsa lütfen G Suite API'leri ve Marketplace API'leri Destek Forumu'nda bizimle iletişime geçin.

Kaynaklar