OAuth'u Google Veri API'larıyla kullanma

Eric Bidelman, Google Veri API'leri Ekibi
Eylül 2008

Giriş

Geliştiriciler için heyecan verici bir dönemden geçiyoruz. Web'de bazı açık standartların benimsendiğini görmeye başlıyoruz. Bildiğiniz gibi Google, her zaman standartların hayranı ve açık kaynak topluluğunu teşvik ediyor.

Son zamanlarda tüm Google Veri API'leri, kullanıcıların gizli verilerine masaüstü ve web uygulamalarının erişme şeklini standartlaştırmayı amaçlayan açık bir protokol olan OAuth desteğini benimsedi. OAuth, standart ve güvenli bir şekilde API kimlik doğrulaması gerçekleştirmek için bir araç sağlar. Programcı olarak bize kodu mümkün olduğunca yeniden kullanmamız öğretiliyor. OAuth, geliştiricilerin yazdıkları yinelenen kod miktarını azaltmalarına yardımcı olur. Ayrıca, farklı sağlayıcılara ait birden çok hizmetle çalışan araçlar oluşturmayı kolaylaştırır.

Kitle

Bu makalede, Google Veri API'lerinden bir veya daha fazlası hakkında bilgi sahibi olduğunuz varsayılmıştır ancak OAuth'un altında yatan kavramlar yoktur. Yeni başlıyorsanız veya OAuth'u merak ediyorsanız daha fazla bilgi edinmeyin. Bu makale, kavramların temelini oluşturmaktadır. Ayrıca, Google'ın OAuth uygulamasıyla ilgili ayrıntıları da ele alacağız.

Bu doküman, özellikle gelişmiş güvenlikle kaydolundu modunda AuthSub'ı kullanmaya aşina olan geliştiriciler için hazırlanmıştır. İlerleyen süreçte, iki protokol arasındaki benzerlikleri ve farkları vurgulamaya çalışacağım. AuthSub kullanan uygulamalarınız varsa daha açık ve modern bir protokol olan OAuth'a geçiş yapmak için bu bilgileri kullanabilirsiniz.

Biraz terminoloji

OAuth'u anlamak, terminolojisini anlamakla ilgilidir. OAuth spesifikasyonu ve Google'ın Web Uygulamaları için OAuth Kimlik Doğrulaması belgeleri çoğunlukla belirli tanımlara dayanır. Bu nedenle, Google'ın OAuth uygulaması bağlamında her birinin ne anlama geldiğine açıklık getirelim.

  1. "OAuth dans"

    OAuth kimlik doğrulama/yetkilendirme sürecinin tamamını açıklayan resmi olmayan terimim.

  2. (OAuth) Jeton iste

    Google'a uygulamanızın Google Veri API'lerinden birine erişim istediğini bildiren ilk jeton. OAuth dansının ikinci adımı, kullanıcının verilerine manuel olarak erişim izni vermesidir. Bu adım başarılı olursa istek jetonu yetkilendirilir.

  3. (OAuth) Erişim jetonu

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

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

  4. (OAuth) Uç Noktalar

    Bunlar, bir uygulamanın kimliğini doğrulamak ve erişim jetonu almak için gereken URI'lardır. OAuth sürecinin her adımı için bir tane olmak üzere toplam üç dosya vardır. Google'ın OAuth uç noktaları şunlardır:

    Bir istek jetonu alın:https://www.google.com/accounts/OAuthGetRequestToken
    İstek jetonunu yetkilendirin:https://www.google.com/accounts/OAuthAuthorizeToken
    Erişim jetonuna geçin:https://www.google.com/accounts/OAuthGetAccessToken

    AuthSub ile benzerlik:
    Bir erişim jetonu için yetkili istek jetonunun değiştirilmesi, tek kullanımlık AuthSub jetonunu sırasıyla https://www.google.com/accounts/AuthSubRequestToken ve https://www.google.com/accounts/AuthSubSessionToken konumunda uzun ömürlü bir oturum jetonuna yükseltmeye benzer. Aradaki fark, AuthSub'ın başlangıç istek jetonu kavramının olmamasıdır. Bunun yerine, kullanıcı jeton işlemini AuthSubRequestToken yetkilendirme sayfasından başlatır.

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

    Google Veri API'leri söz konusu olduğunda bu sağlayıcı Google'dır. Servis sağlayıcı genellikle OAuth uç noktalarını sağlayan web sitesini veya web hizmetini tanımlamak için kullanılır. OAuth hizmet sağlayıcısına bir başka örnek de MySpace'tir.

  6. (OAuth) Tüketici

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

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

Başlayın

Kayıt

OAuth'u Google Veri API'larıyla kullanmaya başlayabilmeniz için az sayıda kurulum gereklidir. Tüm OAuth isteklerinin dijital olarak imzalanması gerektiğinden öncelikle alanınızı kaydettirmeniz ve Google'a herkese açık bir sertifika yüklemeniz gerekir. Bunun nasıl yapılacağı hakkında daha fazla bilgi edinmek için Web Tabanlı Uygulamalara Kayıt ve Kayıtlı mod ile kullanılacak anahtarlar ve sertifikalar oluşturma başlıklı makalelere bakın.

İmzalama istekleri

Alanınız kaydedildikten sonra istekleri imzalamaya başlayabilirsiniz. OAuth'un en zor kavramlarından biri, oauth_signature ve imzaya dayalı temel dize kavramının doğru şekilde nasıl yapılandırılacağı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, http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime adresinde bir kullanıcının Google Takvimlerinin listesi

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: Burada amaç yalnızca temsil etmektir. oauth_signature cihazınız çok daha uzun olacak.

Temel dizeyle ilgili notlar:

  • orderby=starttime sorgu parametresi, söz dizimi bayt değeri değeri sıralamasındaki diğer oauth_* parametreleriyle birlikte sıralanır.
  • Bu dize bir '?' karakteri de içermez.
  • base-http-request-url bölümü yalnızca URL kodlamalı temel URL'yi içeriyor: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull.
  • oauth_token çift url olarak kodlanmıştır.

Authorization başlığıyla ilgili notlar:

  • Authorization başlığında oauth_* parametrelerinin sıralaması önemli değildir.
  • Üstbilgide olduğu gibi, başlık orderby=starttime içermemektedir. Bu sorgu parametresi, istek URL'si kapsamında tutulur.

OAuth kullanarak istekleri imzalama hakkında daha fazla bilgi edinmek için OAuth İsteklerini İmzalama konusuna bakın.

AuthSub ile arasındaki fark:
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 istek imzalama hakkında daha fazla bilgi edinmek için AuthSub İsteklerini İmzalama bölümüne bakın.

OAuth Playground Aracı

Amaç

Bazı kullanıcılar OAuth'un yüksek bir öğrenme eğrisine sahip olduğunu önermiştir. Google'ın diğer kimlik doğrulama API'leriyle karşılaştırıp kabul ediyorum. Uygulamanızı diğer (Google dışı) hizmetleri kullanacak şekilde genişlettiğinizde OAuth'un avantajı ortaya çıkar. Farklı servis sağlayıcılarda ve API'lerinde çalışan tek bir kimlik doğrulama kodu yazmak benim için iyi geliyor. Protokolü daha sonra öğrendiğiniz için kendinize teşekkür edersiniz.

OAuth Playground, geliştiricilerin OAuth sorunlarını gidermesine yardımcı olmak için oluşturduğum bir araçtır. Sorunları gidermek, kendi uygulamanızı kontrol etmek veya Google Veri API'leriyle denemeler yapmak için Playground'u kullanabilirsiniz.

Bu sekme ne işe yarar?

  1. OAuth kimlik doğrulama akışını gösterir: istek jetonu alma, jetonu yetkilendirme ve jetonu bir erişim jetonuna yükseltme.
  2. Her istek için doğru imza temel dizesini gösterir.
  3. Her istek için doğru Authorization üstbilgisini gösterir.
  4. Kimliği doğrulanmış bir Google Veri feed'i ile etkileşim kurmak için oauth_token etiketinin nasıl kullanıldığını gösterir. GET/POST/PUT/DELETE veri oluşturabilirsiniz.
  5. Kimliği doğrulanmış bir feed'i doğrudan tarayıcınızda görüntüleyin.
  6. Kendi oauth_consumer_key (kayıtlı alanınız) ve özel anahtarınızı test etmenize olanak tanır.
  7. oauth_token cihazınızda hangi Google Veri feed'i hizmetlerinin kullanılabileceğini keşfedin.

Demonun Yayını

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 tanıtımda Blogger ve Google Kişiler ile çalışacak bir jeton istiyorum.

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

2. Adım: OAuth Parametrelerini ve Ayarlarını Değiştirin

Şimdilik "OAuth Parametrelerini Değiştir" kutusunda herhangi bir ayarı değiştirmeyin. Daha sonra, oauth_consumer_key öğesini kayıtlı alan adınızla değiştirip "kendi özel anahtarınızı kullanın"ı tıklayarak özel anahtarınızı girerek kendi özel anahtarınızla test edebilirsiniz. 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 otomatik olarak oluşturulur.

RSA-SHA1 alanına ek olarak oauth_signature_method için HMAC-SHA1 kullanmayı da tercih edebilirsiniz. Bu durumda Playground'ta kendi oauth_consumer_key ve tüketici sırrınızı girmeniz gereken ek kutular gösterilir. Bu değerler, kayıtlı alanınızın https://www.google.com/accounts/ManageDomains sayfasında bulunabilir.

AuthSub'dan fark:
Güvenli AuthSub'da, alan adını açık bir şekilde belirleyen bir parametre yoktur. Alan adı, next URL parametresinin bir parçası olarak eklenir. OAuth'ta böyle bir parametre vardır: oauth_consumer_key. Bu alanı kayıtlı alanınıza ayarlayın.

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

OAuth erişim jetonu almanın üç adımı vardır. İlk adım, bir istek jetonu almaktır. Böylece Google, uygulamanızın OAuth dansını başlatacağını bilir.

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

Belirli alanlar verilerle doldurulacaktır.

  • "İmza temel dizesi", oauth_signature parametresini oluşturmak için kullanılan temel dizenin doğru biçimini gösterir.
  • "Yetkilendirme başlığı", isteğe karşılık gelen Authorization üst bilgisini gösterir.
  • "OAuth Parametrelerini Değiştir" kutusu, istekte gönderilen oauth_nonce ve oauth_timestamp değerleriyle doldurulur.
  • oauth_token girişi, yanıt gövdesinde döndürülen ilgili değerle dolduruldu. Playground, şu anda sahip olduğumuz oauth_token türünü de gösterir. Şu an için bu bir istek jetonudur.

Ardından, "Jetonu al" kutusundaki "Yetkilendir" düğmesini tıklayın.

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

AuthSub ile benzerlik:
Bu yetkilendirme sayfası AuthSub için aynıdır.

AuthSub'dan fark:
AuthSub'ın next URL parametresi, oauth_callback parametresine benzer. Aralarındaki fark, OAuth'ta oauth_callback özelliğinin isteğe bağlı olmasıdır. Kullanıcı "Erişim izni ver" düğmesini tıkladıktan sonra, istek jetonu yetkilendirilir ve jeton https://www.google.com/accounts/OAuthGetAccessToken sürümüne eşzamansız olarak gerçekleştirilebilir.

İpucu: Daha iyi bir kullanıcı deneyimi sağladığı için bir web uygulaması yazıyorsanız 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" ile belirtildiği gibi) yeni sürüme geçirir.

Yeni bir jeton getirmek isterseniz OAuth dansını yeniden başlatmak için "baştan başla"yı tıklayın.

Şimdi ilginç bir şey yapabiliriz.

Erişim jetonunu kullanma

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

İpucu: Erişim jetonunuzun sunduğu feed'leri keşfetmek için "kullanılabilir feed'ler" düğmesini tıklayın.

Örnek bir 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. Döndürülen özet akışını/girişi, söz dizimi vurgulanmış alanın altındaki "Tarayıcıda görüntüle" bağlantısını tıklayarak doğrudan tarayıcınızda da görüntüleyebilirsiniz.

Örnek: Bir yayını güncelleme

  1. Güncellemek istediğiniz yayında rel="edit" bulunan <link> öğesini bulun. Bu değer şu şekilde görünmelidir: 
    <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 "düz görünümü göster"i tıklayarak mevcut girişin XML'ini kopyalayın. Üstbilgileri değil, yalnızca yanıt gövdesini kopyalayın.
  3. HTTP yöntemi açılır menüsünü PUT olarak değiştirin.
  4. Söz konusu açılır menünün altındaki "gönderme verilerini girin" seçeneğini tıklayın ve <entry> XML dosyasını pop-up penceresine yapıştırın.
  5. "Yürüt" düğmesini tıklayın.

Sunucu, 200 OK komutuyla yanıt verir.

İpucu: edit bağlantısını manuel olarak kopyalamak yerine "Söz Dizimi Vurgulanıyor mu?" 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'i ileriye taşımaya yardımcı olur. Bu standartları benimsemeye başlayan sitelerin sayısı giderek artmaktadır. Öldürücü bir uygulama oluşturmak aniden daha az göz korkutucu olabilir.

OAuth Playground veya Google API'leriyle OAuth kullanma hakkında sorularınız ya da yorumlarınız varsa lütfen G Suite API'leri ve Marketplace API'leri Destek Forumu'nda bizi ziyaret edin.

Kaynaklar