Veri Planı Aracı API'sı için OAuth

OAuth 2.0, RFC 6749 olarak standartlaştırılmıştır. Ayrıntılı belgeyi https://oauth.net/2 adresinde bulabilirsiniz. HTTP Temel Kimlik Doğrulaması, RFC 2617'nin 2. bölümünde tanımlanmaktadır.

Genel bakış

Genellikle üçüncü taraf uygulamalarına veri planı ve cüzdan ayrıntıları gibi kısıtlı kaynaklara erişim sağlamak için son kullanıcının (kaynak sahibi) kimlik bilgilerini üçüncü tarafla paylaşması gerekir. Bu durum kimlik bilgisi depolama, şifre kimlik doğrulaması, son kullanıcının kaynaklarına kapsamlı erişim ve şifre sızıntısı gibi çeşitli sorunlara ve sınırlamalara yol açar. OAuth2.0, bir yetkilendirme katmanı ekleyerek ve dolayısıyla son kullanıcının korunan kaynaklarına erişimi güvence altına alıp sınırlandırarak bu sorunları ele alır.

GTAF, veri planı ayrıntıları gibi korunan kaynaklara erişmek için son kullanıcının kimlik bilgilerini kullanmak yerine bir erişim jetonu alır. Erişim jetonları GTAF'nin kimlik bilgileri adına GTAF'ya verilir. Daha sonra GTAF, DPA tarafından barındırılan veri planı ayrıntılarına erişmek için erişim jetonunu kullanır.

Aşağıdaki şekilde yüksek düzeyde bilgi akışı sunulmaktadır:

Şekil 1. Soyut OAuth Akışı.

Erişim Jetonları

Erişim jetonları, GTAF tarafından operatörün DPA'sından veri planı ayrıntılarına erişmek için kullanılan kimlik bilgileridir. Erişim jetonu, GTAF'ya verilen yetkilendirmeyi temsil eden bir dizedir. Dize genellikle GTAF için opaktır. Jetonlar, son kullanıcı tarafından operatöre verilen ve DPA ile operatörün OAuth sunucusu tarafından uygulanan belirli kapsamları ve erişim sürelerini temsil eder.

Erişim jetonu, farklı yetkilendirme yapılarını (ör. kullanıcı adı ve şifre) DPA tarafından anlaşılan tek bir jetonla değiştirerek bir soyutlama katmanı sağlar. Bu soyutlama sayesinde erişim jetonları, bunları almak için kullanılan yetkilendirme hibesinden daha kısıtlayıcı olarak sunulur. DPA'ların kaldırılması, çok çeşitli kimlik doğrulama yöntemlerini anlamasını gerektirir.

Erişim jetonları, operatörün güvenlik gereksinimlerine bağlı olarak farklı biçimler, yapılar ve kullanım yöntemlerine (ör. kriptografik özellikler) sahip olabilir. GTAF, yalnızca [RFC6750]'de tanımlanan hamile türü erişim jetonlarını destekler.

İstemci Kimlik Doğrulaması

GTAF, "gizli bir istemci" olarak çalışır ve şifreleri güvende tutabilir. GTAF şu anda DPA ile kimlik doğrulaması için yalnızca HTTP Temel kimlik doğrulamasını desteklemektedir. İstemci tanımlayıcısı "kod/uygulama/x-www-form-urlkodu&kodlama" algoritması kullanılarak kodlanır ve kodlanmış değer kullanıcı adı olarak kullanılır. Şifre de aynı algoritma kullanılarak şifrelenir ve şifre olarak kullanılır.

İstemci kimlik bilgileri verilen GTAF gibi gizli istemciler, jeton uç noktasına istekte bulunurken operatörün OAuth sunucusuyla kimlik doğrulaması yapar. İstemci kimlik doğrulaması şunun için kullanılır: \

  • İstemciyi devre dışı bırakarak veya kimlik bilgilerini değiştirerek güvenliği ihlal edilmiş bir istemciden kurtarma ve böylece bir saldırganın çalınan yenileme jetonlarını kötüye kullanmasını önleme. Tek bir istemci kimlik bilgisi grubunu değiştirmek, tüm yenileme jetonu grubunu iptal etmekten çok daha hızlıdır.
  • Düzenli kimlik bilgisi rotasyonu gerektiren kimlik doğrulama yönetimi en iyi uygulamalarını gerçekleştirme.

GTAF, jeton uç noktasına istek gönderirken kendisini tanımlamak için "client_id" istek parametresi kullanır.

Müşterinin kimlik bilgilerini dönüşümlü sunabilmek özellikle önemlidir. OAuth sunucusu, rotasyon sırasında aynı anda iki kimlik bilgisi çiftini destekleyebilmeli ve kimlik bilgilerini devre dışı bırakabilmelidir. Normal kimlik bilgisi rotasyonunda:

  1. Operatör, OAuth sunucusunda yeni kimlik bilgileri oluşturur ve kimlik bilgilerini güvenli bir şekilde Teknik Hesap Yöneticisi'ne gönderir.
  2. Google, yeni kimlik bilgisini test eder ve GTAF yapılandırmasını yeni kimlik bilgisini kullanacak şekilde değiştirir.
  3. Google, operatöre eski kimlik bilgilerinin devre dışı bırakılabileceğini bildirir.
  4. Operatör kimlik bilgilerini devre dışı bırakır ve Google'ı bilgilendirir
  5. Google eski kimlik bilgilerinin artık geçerli olmadığını doğrular

OAuth sunucusu yukarıdaki rotasyon işlemini destekleyebilmelidir.

Jeton Uç Noktası

Jeton uç noktası, GTAF tarafından yetkilendirme izni veya yenileme jetonunu sunarak erişim jetonu almak için kullanılır. Jeton uç noktası, örtülü hibe türü (doğrudan bir erişim jetonu verildiği için) hariç her yetkilendirme hibesiyle birlikte kullanılır.

Aşağıda, bir jeton uç noktasını yapılandırırken göz önünde bulundurulması gereken bazı noktalar verilmiştir:

  • Jeton uç noktasının konumu, hizmet dokümanlarında sağlanmalıdır.
  • Uç nokta URI'sinde, ek sorgu parametreleri eklenirken saklanması gereken "application/x-www-form-urlencrypted" biçimli bir sorgu bileşeni bulunabilir. Uç nokta URI bir parça bileşeni içermemelidir.
  • Jeton uç noktasına yapılan istekler net metin kimlik bilgilerinin (HTTP isteği ve yanıtında) aktarılmasına neden olduğundan operatörün OAuth sunucusu, jeton uç noktasına istek göndermek için TLS'yi kullanmalıdır.
  • GTAF, erişim jetonu için istekte bulunurken HTTP "POST" yöntemini kullanır.
  • Değer olmadan gönderilen parametreler, istekten çıkarıldı olarak kabul edilmelidir. OAuth sunucusu tanınmayan istek parametrelerini yoksaymalıdır. İstek ve yanıt parametreleri birden fazla kez eklenmemelidir.
  • GTAF yalnızca hamile türü erişim jetonlarını destekler.

Erişim Jetonu Kapsamı

Yetkilendirme ve jeton uç noktaları, istemcinin "&quot kapsamı istek isteği parametresini kullanarak erişim isteğinin kapsamını belirtmesini sağlar. Buna karşılık, yetkilendirme sunucusu istemciye verilen erişim jetonunun kapsamı hakkında bilgi vermek için "kapsam" yanıt parametresini kullanır.

Kapsam parametresinin değeri, boşlukla sınırlandırılmış, büyük/küçük harfe duyarlı dizelerin listesi olarak ifade edilir. Dizeler, yetkilendirme sunucusu tarafından tanımlanır. Değer, boşlukla ayrılmış birden fazla dize içeriyorsa bunların sırası önemli değildir ve her dize, istenen kapsam için ek bir erişim aralığı ekler.

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF, kapsamın uygulanmasını gerektirmez ancak bu özelliği destekler. Daha fazla bilgi için RFC 6749'un Bölüm 3.3'e bakın.

Erişim Jetonu Verme

GTAF tarafından gönderilen erişim jetonu isteği geçerli ve yetkilendirilmişse OAuth sunucusu bir erişim jetonu ve isteğe bağlı yenileme jetonu yayınlar. İstek istemci kimlik doğrulamasında başarısız olursa veya geçersizse OAuth sunucusu aşağıdaki bölümde açıklandığı gibi bir hata yanıtı döndürür.

Başarılı Yanıt

GTAF bir istek gönderdiğinde, OAuth sunucusu bir erişim jetonu ve isteğe bağlı bir yenileme jetonu yayınlar ve aşağıdaki parametreleri, 200 (Tamam) durum koduyla HTTP yanıtının varlık gövdesine ekleyerek oluşturur: \

  • access_token: GEREKLİ. OAuth sunucusu tarafından verilen erişim jetonu. GTAF, jeton uç noktasının bir hamiline ait jeton döndürmesini bekler.
  • expires_in: ZORUNLU. Saniye cinsinden erişim jetonunun kullanım ömrü. Örneğin "3600" değeri, erişim jetonunun süresinin, yanıtın oluşturulduğu andan itibaren bir saat içinde sona ereceğini belirtir. Atlanırsa OAuth sunucusu başka yöntemler kullanarak geçerlilik süresini sağlamalı veya varsayılan değeri belgelemelidir.
  • token_type: ZORUNLU. Verilen jetonun türü. Farklı jeton türleri hakkında daha fazla bilgi için RFC 6749'un Bölüm 7.1'e bakın. Değer, büyük/küçük harfe duyarlı değildir. Bu yazı hazırlanırken, GTAF yalnızca hamiline ait jetonları desteklemektedir.
  • Refresh_token: İSTEĞE BAĞLI. Yeni yetkilendirme jetonlarını aynı yetkilendirme izniyle almak için kullanılabilecek yenileme jetonu.
  • scope: İSTEĞE BAĞLI ve GTAF tarafından istenen kapsamla aynıysa bu boyut gereklidir, aksi takdirde gereklidir.

Parametreler "application/json" kullanılarak HTTP yanıtının varlık gövdesine eklenir. Parametreler, her parametre en yüksek yapı düzeyinde eklenerek bir JavaScript Object Notation (JSON) yapısına serileştirilir. Parametre adları ve dize değerleri JSON dizeleri olarak eklenir. Sayısal değerler JSON numaraları olarak eklenir. Parametrelerin sırası önemli değildir ve farklı şekillerde değişebilir.

Yetkilendirme sunucusunun, jetonları, kimlik bilgilerini veya diğer hassas bilgileri içeren herhangi bir yanıtta "quot;store-Control" yanıt başlığı alanı içeren HTTP "&t;Cache-Control" yanıt başlığı alanının yanı sıra "quot;no-cache" değeri içeren "Pragma" yanıt başlığı alanı olması ZORUNLUDUR.

Örneğin:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Göz önünde bulundurulması gereken bazı önemli noktalar aşağıda verilmiştir:

  • GTAF, yanıttaki tanınmayan değer adlarını yoksayar.
  • OAuth sunucusundan alınan jetonların ve diğer değerlerin boyutları tanımsız olarak bırakılır.
  • GTAF, değer boyutlarıyla ilgili varsayımlarda bulunmaktan kaçınmalıdır. OAuth sunucusu, sorun teşkil ettiği tüm değerlerin boyutunu belgelemelidir.

Hata Yanıtı

Yetkilendirme isteği; eksik, geçersiz veya uyumsuz yönlendirme URI'si gibi bir nedenle başarısız olursa ya da istemci tanımlayıcısı eksik veya geçersizse OAuth sunucusu bir HTTP 400 (Hatalı İstek) durum koduyla (aksi belirtilmedikçe) yanıt vermeli ve Hata Yanıtı ve Kodlar bölümünde listelenen parametrelerden en az birini içermelidir.

GTAF'de Yetki Verme

Yetkilendirme izni, bir erişim jetonu almak için GTAF tarafından kullanılan, son kullanıcının yetkilendirmesini (veri bakiyesi bilgileri gibi korunan kaynaklarına erişmek için) temsil eden bir kimlik bilgisidir.

GTAF, client_credentials izin türünü kullanır. client_credentials izin türünde GTAF, bir HTTP POST isteği ve HTTP Temel Kimlik Doğrulaması kullanarak bir jeton ister. Tüm istekler TLS üzerinden gönderilir (ör. HTTPS) ve GTAF, geçerli bir TLS sertifikasına sahip olmayan bir OAuth sunucusuyla entegre olamaz. GTAF, yapılandırılabilir bir jeton kapsamını geçirebilir ve yapılandırılmazsa boş bir kapsam aktarır.

GTAF, bir erişim jetonunun "expires_in&quot değeriyle birlikte (yaşam süresi) döndürülmesini bekler. expiration_in değeri en az 900 saniye olmalı ve birkaç saatten fazla olmamalıdır. Yeni bir jetonun istenmesi, mevcut jetonların süresinin bitmesine neden olmamalıdır.

Çeşitli hibe türleri hakkında daha fazla bilgi için RFC 6749'un bölüm 1.3'üne bakın.

Örnek İstek ve Yanıt

GTAF'ın bir OAuth sunucusu için aşağıdaki yapılandırmaya sahip olduğunu varsayalım:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

Not: Gerçek bir DPA'nın istemci sırrı, örnekte gösterilenden çok daha güvenli olmalıdır.

Yetkilendirme dizesini oluşturmak için istemci kimliği olan ##39;:' ve şifre birleştirilir ve base64 kodludur. Bu, bir komut satırı arayüzünde aşağıdaki gibi çoğaltılabilir:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

Ardından GTAF bu kimlik bilgilerini, client_credentials izin türünü ve yapılandırılmış kapsamı kullanarak OAuth sunucusuna bir HTTPS POST isteği yapar. Örneğin, GTAF' tarafından oluşturulan istek, aşağıdakiler tarafından oluşturulan isteğe benziyor:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF tarafından kullanılan başlıklar, curl tarafından gönderilen üstbilgilerle eşleşmeyecektir, ancak yetkilendirme başlığı aynı olur.

GTAF, şu formda yanıt bekliyor:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

Aşağıda, geçerli bir yanıt örneği verilmiştir:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

Not: Yanıt geçerli JSON olmalıdır.

Hata Yanıtı ve Kodları

Hata Yanıtı bölümünde belirtilen nedenlerden herhangi biri nedeniyle GTAF'den gelen bir yetkilendirme isteği başarısız olursa OAuth sunucusu, bir HTTP 400 (Hatalı İstek) durum koduyla (aksi belirtilmedikçe) yanıt vermeli ve yanıtta aşağıdaki parametrelerden birini içermelidir:

Örneğin: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF, OAuth sunucusunun aşağıdaki hata yanıtlarını desteklemesini bekler:

Hata Kodu Yanıt Nedeni
HTTP 400 geçersiz_istek İstekte gerekli bir parametre eksik, desteklenmeyen bir parametre değeri (izin türü dışında) içeriyor, bir parametreyi tekrarlıyor, birden fazla kimlik bilgisi içeriyor, GTAF ile kimlik doğrulama için birden fazla mekanizma kullanıyor veya başka şekilde yanlış biçimlendirilmiş.
HTTP 401 geçersiz_istemci İstemci kimlik doğrulaması başarısız oldu (ör. bilinmeyen istemci, istemci kimlik doğrulaması yok veya desteklenmeyen kimlik doğrulama yöntemi). OAuth sunucusu, hangi HTTP kimlik doğrulama düzenlerinin desteklendiğini belirtmek için bir HTTP 401 (Yetkisiz) durum kodu döndürebilir. İstemci "Yetkilendirme" istek başlığı alanı üzerinden kimlik doğrulaması yapmaya çalışırsa OAuth sunucusu bir HTTP 401 (Yetkisiz) durum koduyla yanıt vermeli ve istemcinin kullandığı kimlik doğrulama şemasıyla eşleşen "WWW-Authentication" yanıt başlığı alanını içermelidir.
HTTP 500 OAuth sunucusu hatası

Hata ayıklama için kullanılabilecek diğer yanıtlarla ilgili ayrıntıları RFC 6749'un bölüm 5.2'de bulabilirsiniz.