Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

İlgili Belgeler

OAuth 2.0, RFC 6749 olarak standartlaştırılmıştır. https://oauth.net/2 adresinde ayrıntılı bir belge bulunmaktadır. HTTP temel kimlik doğrulaması, RFC 2617'nin 2. bölümünde tanımlanmıştır.

Genel Bakış

Genellikle, üçüncü taraf uygulamalarına veri planı ve cüzdan ayrıntıları gibi kısıtlanmış kaynaklara erişim izni vermek 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 geniş erişim ve şifre sızıntısı gibi çeşitli sorunlara ve sınırlamalara yol açar. OAuth 2.0, bir yetkilendirme katmanı sunarak bu sorunları ele alır ve böylece son kullanıcının korunan kaynaklarına erişimi güvenli hale getirip sınırlar.

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'ye verilir. Ardından 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, üst düzey bilgi akışı gösterilmektedir:

Şekil 1. Abstract OAuth Flow.

Erişim Jetonları

Erişim jetonları, GTAF'nin operatörün DPA'sından veri planı ayrıntılarına erişmek için kullandığı kimlik bilgileridir. Erişim jetonu, GTAF'ye verilen bir yetkilendirmeyi temsil eden dizedir. Dize genellikle GTAF için opak olur. Jetonlar, son kullanıcı tarafından operatöre verilen ve DPA ile operatörün OAuth sunucusu tarafından zorunlu kılınan belirli erişim kapsamlarını ve 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, erişim jetonlarının alınması için kullanılan yetkilendirme izninden daha kısıtlayıcı bir şekilde verilmesini sağlar ve DPA'nın çok çeşitli kimlik doğrulama yöntemlerini anlamasına gerek kalmaz.

Erişim jetonları, operatörün güvenlik koşullarına bağlı olarak farklı biçimlere, yapılara ve kullanım yöntemlerine (ör. şifreleme özellikleri) sahip olabilir. GTAF yalnızca [RFC6750] içinde tanımlanan taşıyıcı türü erişim jetonlarını destekler.

İstemci Kimlik Doğrulaması

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

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

İstemciyi devre dışı bırakarak veya kimlik bilgilerini değiştirerek güvenliği ihlal edilmiş bir istemciden kurtulma. Böylece, saldırganın çalınan yenileme jetonlarını kötüye kullanması önlenir. Tek bir istemci kimlik bilgilerini değiştirme işlemi, yenileme jetonlarının tamamını iptal etmeye kıyasla çok daha hızlıdır.
Kimlik doğrulama yönetimiyle ilgili en iyi uygulamaları hayata geçirme (bu uygulamalar, kimlik bilgilerinin düzenli olarak değiştirilmesini gerektirir).

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

Müşteri kimlik bilgilerini döndürme özelliği özellikle önemlidir. OAuth sunucusu, döndürme sırasında aynı anda iki kimlik bilgisi çiftini destekleyebilmeli ve kimlik bilgilerini devre dışı bırakabilmelidir. Normal bir kimlik bilgisi değişim döngüsünde:

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

OAuth sunucusu, yukarıdaki döndürme sürecini destekleyebilmelidir.

Jeton uç noktası

Jeton uç noktası, yetkilendirme erişim iznini veya yenileme jetonunu sunarak erişim jetonu almak için GTAF tarafından kullanılır. Jeton uç noktası, örtülü izin türü hariç her yetkilendirme izniyle birlikte kullanılır (çünkü erişim jetonu doğrudan verilir).

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

Jeton uç noktasının konumu, hizmet dokümanlarında belirtilmelidir.
Uç nokta URI'si, "application/x-www-form-urlencoded" biçimli bir sorgu bileşeni içerebilir. Ek sorgu parametreleri eklenirken bu bileşen korunmalıdır. Uç nokta URI'si bir parça bileşeni içermemelidir.
Jeton bitiş noktasına yapılan istekler, düz metin kimlik bilgilerinin (HTTP isteğinde ve yanıtında) iletilmesine neden olduğundan operatörün OAuth sunucusu, jeton bitiş noktasına istek göndermek için TLS kullanmalıdır.
GTAF, erişim jetonu isteğinde bulunurken HTTP "POST" yöntemini kullanır.
Değer olmadan gönderilen parametreler, istekten çıkarılmış olarak değerlendirilmelidir. OAuth sunucusu, tanınmayan istek parametrelerini yoksaymalıdır. İstek ve yanıt parametreleri birden fazla kez dahil edilmemelidir.
GTAF yalnızca taşıyıcı türü erişim jetonlarını destekler.

Erişim Jetonu Kapsamı

Yetkilendirme ve jeton uç noktaları, istemcinin "scope" istek parametresini kullanarak erişim isteğinin kapsamını belirtmesine olanak tanır. Buna karşılık, yetkilendirme sunucusu, verilen erişim jetonunun kapsamı hakkında istemciyi bilgilendirmek için "scope" yanıt parametresini kullanır.

Kapsam parametresinin değeri, boşlukla ayrı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 kapsamda ek bir erişim aralığı oluşturur.

 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 3.3 bölümüne bakın.

Erişim jetonu verme

GTAF tarafından gönderilen erişim jetonu isteği geçerli ve yetkiliyse OAuth sunucusu bir erişim jetonu ve isteğe bağlı olarak yeni kod jetonu verir. İ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ı yenileme jetonu yayınlar ve 200 (OK) durum koduna sahip HTTP yanıtının varlık gövdesine aşağıdaki parametreleri ekleyerek yanıtı oluşturur: \

access_token: ZORUNLU. OAuth sunucusu tarafından verilen erişim jetonu. GTAF, jeton uç noktasının taşıyıcı jeton döndürmesini bekler.
expires_in: ZORUNLU. Erişim jetonunun kullanım ömrü (saniye). Örneğin, "3600" değeri, yanıt oluşturulduktan bir saat sonra erişim jetonunun süresinin dolacağını gösterir. Atlanırsa OAuth sunucusu, son kullanma zamanını başka yollarla 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 7.1 Bölümü'ne bakın. Değer, büyük/küçük harfe duyarlı değildir. GTAF, bu makalenin yazıldığı sırada yalnızca taşıyıcı jetonlarını desteklemektedir.
refresh_token: İSTEĞE BAĞLI. Aynı yetkilendirme izni kullanılarak yeni erişim jetonları almak için kullanılabilen yenileme jetonu.
scope: İSTEĞE BAĞLI, uygulanırsa ve GTAF tarafından istenen kapsamla aynıysa; aksi takdirde ZORUNLU.

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

Yetkilendirme sunucusu, jeton, kimlik bilgisi veya diğer hassas bilgileri içeren tüm yanıtlarda "no-store" değerine sahip HTTP "Cache-Control" yanıt üstbilgi alanını ve "no-cache" değerine sahip "Pragma" yanıt üstbilgi alanını içermelidir.

Ö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"
     }

Dikkate alınması gereken bazı önemli noktalar şunlardır:

GTAF, yanıttaki tanınmayan değer adlarını yoksayar.
OAuth sunucusundan alınan jetonların ve diğer değerlerin boyutları tanımlanmamış olarak bırakılır.
GTAF, değer boyutları hakkında varsayımlarda bulunmaktan kaçınmalıdır. OAuth sunucusu, verdiği değerlerin boyutunu belgelemelidir.

Hata Yanıtı

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

GTAF'de yetkilendirme izni

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

GTAF, client_credentials yetkilendirme türünü kullanır. client_credentials yetkilendirme türünde, GTAF bir HTTP POST isteği ve HTTP Temel Kimlik Doğrulaması kullanarak jeton ister. Tüm istekler TLS üzerinden gönderilir (ör. HTTPS) ve GTAF, geçerli bir TLS sertifikası olmadan OAuth sunucusuyla entegre olamaz. GTAF, yapılandırılabilir bir jeton kapsamı iletebilir ve yapılandırılmamışsa boş bir kapsam iletir.

GTAF, "expires_in" değeriyle birlikte bir erişim jetonunun döndürülmesini bekler (geçerlilik süresi). expires_in değeri en az 900 saniye olmalı ve birkaç saati geçmemelidir. Yeni jeton isteğinde bulunmak, mevcut jetonların süresinin erken dolmasına neden olmamalıdır.

Çeşitli izin 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'nin 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 gizli anahtarı, örnekte gösterilenden çok daha güvenli olmalıdır.

Yetkilendirme dizesini oluşturmak için istemci kimliği, ":" ve şifre birleştirilir ve base64 kodlu hale getirilir. Bu işlem, komut satırı arayüzünde şu şekilde tekrarlanabilir:

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

Ardından GTAF, bu kimlik bilgilerini, client_credentials grant_type'ı ve yapılandırılmış kapsamı kullanarak OAuth sunucusuna bir HTTPS POST isteği gönderir. Örnekte, GTAF'nin isteği, aşağıdakiler tarafından oluşturulan isteğe benzer:

$ 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, yetkilendirme başlığı aynı olsa da curl tarafından gönderilen başlıklarla eşleşmez.

GTAF, şu biçimde bir yanıt bekler:

{
"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ı

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

Ö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	Neden
HTTP 400	invalid_request	İstek, gerekli bir parametreyi içermiyor, 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 bir şekilde hatalı biçimlendirilmiş.
HTTP 401	invalid_client	İstemci kimlik doğrulaması başarısız oldu (ör. bilinmeyen istemci, istemci kimlik doğrulaması dahil edilmedi veya desteklenmeyen kimlik doğrulama yöntemi). OAuth sunucusu, hangi HTTP kimlik doğrulama şemalarının desteklendiğini belirtmek için HTTP 401 (Yetkisiz) durum kodunu döndürebilir. İstemci, "Authorization" istek başlığı alanı aracılığıyla kimlik doğrulamaya çalıştıysa OAuth sunucusu, HTTP 401 (Yetkisiz) durum koduyla yanıt vermeli ve istemci tarafından kullanılan kimlik doğrulama düzeniyle eşleşen "WWW-Authenticate" yanıt başlığı alanını içermelidir.
HTTP 500	OAuth sunucusu hatası

Hata ayıklama için kullanılabilecek diğer yanıtların ayrıntıları için RFC 6749'un 5.2 numaralı bölümüne bakın.

Veri Planı Aracı API'sı için OAuth Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.