İstemci Tarafı Web Uygulamaları için OAuth 2.0

Bu dokümanda, bir JavaScript web uygulamasından Google API'lerine erişmek için OAuth 2.0 yetkilendirmesinin nasıl uygulanacağı açıklanmaktadır. OAuth 2.0, kullanıcıların kullanıcı adlarını, şifrelerini ve diğer bilgilerini gizli tutarken belirli verileri bir uygulamayla paylaşmasına olanak tanır. Örneğin, bir uygulama, kullanıcılardan Google Drive'larında dosya depolama izni almak için OAuth 2.0'ı kullanabilir.

Bu OAuth 2.0 akışına örtük izin akışı denir. Yalnızca kullanıcı uygulamadayken API'lere erişen uygulamalar için tasarlanmıştır. Bu uygulamalar, gizli bilgileri depolayamaz.

Uygulamanız bu akışta, uygulamanızı ve uygulamanın gerektirdiği API erişimi türünü tanımlamak için sorgu parametrelerini kullanan bir Google URL'si açar. URL'yi geçerli tarayıcı penceresinde veya bir pop-up'ta açabilirsiniz. Kullanıcı, Google ile kimlik doğrulaması yapabilir ve istenen izinleri verebilir. Google, daha sonra kullanıcıyı tekrar uygulamanıza yönlendirir. Yönlendirme, uygulamanızın doğruladığı ve daha sonra API istekleri yapmak için kullandığı bir erişim jetonu içerir.

Google API'leri İstemci Kitaplığı ve Google Kimlik Hizmetleri

Google'a yetkili çağrılar yapmak amacıyla JavaScript için Google API'leri istemci kitaplığını kullanıyorsanız OAuth 2.0 akışını yönetmek için Google Kimlik Hizmetleri JavaScript kitaplığını kullanmanız gerekir. Lütfen Google kimlik hizmetleri jeton modelini inceleyin. Bu model, OAuth 2.0 örtük izin akışını temel alır.

Ön koşullar

Projeniz için API'leri etkinleştirin

Google API'lerini çağıran uygulamaların, bu API'leri API Consoleiçinde etkinleştirmesi gerekir.

Projeniz için bir API'yi etkinleştirmek üzere:

  1. Open the API Library Google API Consoleiçinde gösteriliyor.
  2. If prompted, select a project, or create a new one.
  3. API Library sütununda, ürün ailesine ve popülerliğe göre gruplandırılmış tüm API'ler listelenir. Etkinleştirmek istediğiniz API listede görünmüyorsa bulmak için aramayı kullanın veya ait olduğu ürün ailesinde Tümünü Görüntüle'yi tıklayın.
  4. Etkinleştirmek istediğiniz API'yi seçip Etkinleştir düğmesini tıklayın.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Yetkilendirme kimlik bilgileri oluştur

Google API'lerine erişmek için OAuth 2.0 kullanan tüm uygulamalar, uygulamayı Google'ın OAuth 2.0 sunucusuna tanımlayan yetkilendirme kimlik bilgilerine sahip olmalıdır. Aşağıdaki adımlarda projeniz için nasıl kimlik bilgisi oluşturacağınız açıklanmaktadır. Daha sonra uygulamalarınız söz konusu proje için etkinleştirdiğiniz API'lere erişmek için kimlik bilgilerini kullanabilir.

  1. Go to the Credentials page.
  2. Kimlik bilgisi oluştur > OAuth istemci kimliği seçeneğini tıklayın.
  3. Web uygulaması uygulaması türünü seçin.
  4. Formu doldurun. Yetkilendirilmiş Google API istekleri yapmak için JavaScript kullanan uygulamalar, yetkilendirilmiş JavaScript kaynaklarını belirtmelidir. Kaynaklar, uygulamanızın OAuth 2.0 sunucusuna istek gönderebileceği alan adlarını tanımlar. Bu kaynaklar Google'ın doğrulama kurallarına uygun olmalıdır.

Erişim kapsamlarını belirleme

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim istemesine olanak tanırken kullanıcıların uygulamanıza verdikleri erişim miktarını da kontrol edebilmesini sağlar. Dolayısıyla, istenen kapsamların sayısı ile kullanıcıdan izin alma olasılığı arasında ters bir ilişki olabilir.

OAuth 2.0 yetkilendirmesini uygulamaya başlamadan önce, uygulamanızın erişim için izin alması gereken kapsamları belirlemenizi öneririz.

OAuth 2.0 API Kapsamları belgesi, Google API'lerine erişmek için kullanabileceğiniz kapsamların tam listesini içerir.

OAuth 2.0 erişim jetonları edinme

Aşağıdaki adımlarda, uygulamanızın kullanıcı adına API isteği gerçekleştirme izni almak için Google'ın OAuth 2.0 sunucusuyla nasıl etkileşimde bulunduğu gösterilmektedir. Uygulamanızın, kullanıcı yetkilendirmesi gerektiren bir Google API isteğini yürütebilmesi için önce bu izni alması gerekir.

1. Adım: Google'ın OAuth 2.0 sunucusuna yönlendirme

Bir kullanıcının verilerine erişim izni istemek için kullanıcıyı Google'ın OAuth 2.0 sunucusuna yönlendirin.

OAuth 2.0 Uç Noktaları

Google'ın https://accounts.google.com/o/oauth2/v2/auth adresindeki OAuth 2.0 uç noktasından erişim istemek için bir URL oluşturun. Bu uç noktaya HTTPS üzerinden erişilebilir. Düz HTTP bağlantıları reddedilir.

Google yetkilendirme sunucusu, web sunucusu uygulamaları için aşağıdaki sorgu dizesi parametrelerini destekler:

Parametreler
client_id Zorunlu

Uygulamanızın istemci kimliği. Bu değeri API Console Credentials pageiçinde bulabilirsiniz.

redirect_uri Zorunlu

Kullanıcı, yetkilendirme akışını tamamladıktan sonra API sunucusunun kullanıcıyı nereye yönlendirdiğini belirler. Değer, istemcinizin API Console Credentials pageiçinde yapılandırdığınız OAuth 2.0 istemcisi için yetkilendirilmiş yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer, sağlanan client_id için yetkili yönlendirme URI'siyle eşleşmezse redirect_uri_mismatch hatası alırsınız.

http veya https şeması, büyük/küçük harf ve sondaki eğik çizginin ("/") tümünün eşleşmesi gerektiğini unutmayın.

response_type Zorunlu

JavaScript uygulamalarının parametre değerini token olarak ayarlaması gerekir. Bu değer Google Yetkilendirme Sunucusu'na, erişim jetonunu, kullanıcının yetkilendirme işlemini tamamladıktan sonra yönlendirildiği URI'nın parça tanımlayıcısında (#) bir name=value çifti olarak döndürmesi talimatını verir.

scope Zorunlu

Uygulamanızın kullanıcı adına erişebileceği kaynakları tanımlayan boşlukla sınırlandırılmış bir kapsam listesidir. Bu değerler, Google'ın kullanıcıya gösterdiği izin ekranını bilgilendirir.

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim istemesine olanak tanırken kullanıcıların uygulamanıza verdikleri erişim miktarını da kontrol edebilmesini sağlar. Bu nedenle, istenen kapsam sayısı ile kullanıcıdan izin alma olasılığı arasında ters bir ilişki vardır.

Uygulamanızın, mümkün olduğunda bağlam içinde yetkilendirme kapsamlarına erişim isteğinde bulunmasını öneririz. Artımlı yetkilendirme üzerinden kullanıcı verilerine bağlam içinde erişim isteğinde bulunarak kullanıcıların, uygulamanızın istediği erişime neden ihtiyaç duyduğunu daha kolay anlamasına yardımcı olursunuz.

state Önerilen

Uygulamanızın, yetkilendirme isteğiniz ve yetkilendirme sunucusunun yanıtı arasındaki durumu korumak için kullandığı tüm dize değerlerini belirtir. Kullanıcı, uygulamanızın erişim isteğine izin verdikten veya reddettikten sonra sunucu, redirect_uri öğesinin URL parçası tanımlayıcısında (#) name=value çifti olarak gönderdiğiniz tam değeri döndürür.

Bu parametreyi; kullanıcıyı uygulamanızda doğru kaynağa yönlendirmek, tek seferlik rastgele bir sayı göndermek ve siteler arası istek sahtekarlığını azaltmak gibi çeşitli amaçlar için kullanabilirsiniz. redirect_uri değeriniz tahmin edilebileceğinden, state değeri kullanmak, gelen bağlantının kimlik doğrulama isteğinden kaynaklandığına dair güveninizi artırabilir. Rastgele bir dize oluşturursanız veya bir çerezin ya da istemcinin durumunu yakalayan başka bir değerin karmasını kodlarsanız isteğin ve yanıtın aynı tarayıcıdan kaynaklandığından emin olmak için yanıtı doğrulayarak siteler arası istek sahtekarlığı gibi saldırılara karşı koruma sağlayabilirsiniz. state jetonunun nasıl oluşturulacağını ve onaylanacağını öğrenmek için OpenID Connect dokümanlarına göz atın.

include_granted_scopes İsteğe bağlı

Uygulamaların, bağlam içinde ek kapsamlara erişim istemek için artımlı yetkilendirme kullanmasını sağlar. Bu parametrenin değerini true olarak ayarlarsanız ve yetkilendirme isteği verilirse yeni erişim jetonu, kullanıcının daha önce uygulamaya erişim izni verdiği kapsamları da kapsar. Örnekler için artımlı yetkilendirme bölümüne bakın.

login_hint İsteğe bağlı

Uygulamanız hangi kullanıcının kimlik doğrulaması yapmaya çalıştığını bilirse bu parametreyi, Google Kimlik Doğrulama Sunucusu'na ipucu sağlamak için kullanabilir. Sunucu, bu ipucunu oturum açma formundaki e-posta alanını önceden doldurarak veya uygun çoklu giriş oturumunu seçerek giriş akışını basitleştirmek için kullanılır.

Parametre değerini, kullanıcının Google kimliğiyle eşdeğer olan bir e-posta adresi veya sub tanımlayıcısı olarak ayarlayın.

prompt İsteğe bağlı

Kullanıcıya sunmak için boşlukla sınırlandırılmış, büyük/küçük harfe duyarlı bir istem listesi. Bu parametreyi belirtmezseniz kullanıcıdan yalnızca projeniz ilk kez erişim isteğinde bulunduğunda istenir. Daha fazla bilgi için Yeniden izin isteme sayfasına göz atın.

Olası değerler:

none Herhangi bir kimlik doğrulama veya izin ekranı göstermeyin. Diğer değerlerle belirtilmemelidir.
consent Kullanıcıdan izin isteyin.
select_account Kullanıcıdan bir hesap seçmesini isteyin.

Google'ın yetkilendirme sunucusuna yönlendirme örneği

Aşağıda, okunabilirlik için satır sonları ve boşluklar içeren örnek bir URL gösterilmektedir.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

İstek URL'sini oluşturduktan sonra kullanıcıyı bu URL'ye yönlendirin.

JavaScript örnek kodu

Aşağıdaki JavaScript snippet'inde, JavaScript için Google API'leri İstemci Kitaplığı kullanılmadan JavaScript'te yetkilendirme akışının nasıl başlatılacağı gösterilmektedir. Bu OAuth 2.0 uç noktası, merkezler arası kaynak paylaşımını (CORS) desteklemediğinden snippet, isteği bu uç noktaya açan bir form oluşturur.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

2. Adım: Google kullanıcıdan izin ister

Bu adımda kullanıcı, uygulamanıza istenen erişim iznini verip vermeyeceğine karar verir. Bu aşamada Google, uygulamanızın adını ve kullanıcının yetkilendirme kimlik bilgileriyle erişim izni istediği Google API hizmetlerini ve verilecek erişim kapsamlarının özetini gösteren bir izin penceresi gösterir. Böylece kullanıcı, uygulamanızın istediği bir veya daha fazla kapsama erişim izni verebilir veya isteği reddedebilir.

Google'ın OAuth 2.0 sunucusundan herhangi bir erişim verilip verilmediğini belirten yanıtı beklediği için uygulamanızın bu aşamada herhangi bir işlem yapmasına gerek yoktur. Bu yanıt, aşağıdaki adımda açıklanmıştır.

Hatalar

Google'ın OAuth 2.0 yetkilendirme uç noktasına gönderilen istekler, beklenen kimlik doğrulama ve yetkilendirme akışları yerine kullanıcılara yönelik hata mesajları gösterebilir. Yaygın hata kodları ve önerilen çözümler aşağıda listelenmiştir.

admin_policy_enforced

Google Hesabı, Google Workspace yöneticisinin politikaları nedeniyle istenen bir veya daha fazla kapsamı yetkilendiremiyor. OAuth istemci kimliğinize açıkça erişim izni verilene kadar yöneticinin tüm kapsamlara ya da hassas ve kısıtlanmış kapsamlara erişimi nasıl kısıtlayabileceği hakkında daha fazla bilgi için Google Workspace verilerine hangi üçüncü taraf uygulamalar ve dahili uygulamaların erişebileceğini yönetme başlıklı Google Workspace Yöneticisi yardım makalesine göz atın.

disallowed_useragent

Yetkilendirme uç noktası, Google'ın OAuth 2.0 Politikaları ile izin verilmeyen yerleştirilmiş bir kullanıcı aracısının içinde gösterilir.

Android

Android geliştiricileri, android.webkit.WebView'te yetkilendirme isteklerini açarken bu hata mesajıyla karşılaşabilir. Geliştiriciler bunun yerine Android için Google ile Oturum Açma veya OpenID Vakfı'nın Android için AppAuth hizmeti gibi Android kitaplıklarını kullanmalıdır.

Bir Android uygulaması, yerleştirilmiş bir kullanıcı aracısında genel bir web bağlantısı açtığında ve bir kullanıcı sitenizden Google'ın OAuth 2.0 yetkilendirme uç noktasına gittiğinde web geliştiricileri bu hatayla karşılaşabilir. Geliştiriciler, işletim sisteminin varsayılan bağlantı işleyicisinde genel bağlantıların açılmasına izin vermelidir. Bu işleyici hem Android App Links hem de varsayılan tarayıcı uygulamasını içerir. Android Özel Sekmeler kitaplığı da desteklenen bir seçenektir.

iOS

iOS ve macOS geliştiricileri, WKWebView'te yetkilendirme isteklerini açarken bu hatayla karşılaşabilir. Geliştiriciler bunun yerine iOS için Google ile Oturum Açma veya OpenID Vakfı'nın iOS için AppAuth hizmeti gibi iOS kitaplıklarını kullanmalıdır.

Bir iOS veya macOS uygulaması, yerleştirilmiş bir kullanıcı aracısında genel bir web bağlantısı açtığında ve kullanıcı sitenizden Google'ın OAuth 2.0 yetkilendirme uç noktasına gittiğinde bu hatayla karşılaşabilir. Geliştiriciler, genel bağlantıların işletim sisteminin varsayılan bağlantı işleyicisinde açılmasına izin vermelidir. Bu işleyici, hem Evrensel Bağlantılar işleyicilerini hem de varsayılan tarayıcı uygulamasını içerir. SFSafariViewController kitaplığı da desteklenen bir seçenektir.

org_internal

İstekteki OAuth istemci kimliği, belirli bir Google Cloud kuruluşundaki Google Hesaplarına erişimi sınırlayan bir projenin parçasıdır. Bu yapılandırma seçeneği hakkında daha fazla bilgi için OAuth izin ekranınızı ayarlamayla ilgili yardım makalesinin Kullanıcı türü bölümüne bakın.

invalid_client

İsteğin yapıldığı kaynak bu istemci için yetkilendirilmedi. Şu sayfaya göz atın: origin_mismatch.

invalid_grant

Artımlı yetkilendirme kullanılırken jetonun süresi dolmuş veya jetonu geçersiz hale gelmiş olabilir. Yeni jetonlar almak için kullanıcının kimliğini tekrar doğrulayın ve kullanıcıdan izin isteyin. Bu hatayı görmeye devam ediyorsanız uygulamanızın doğru yapılandırıldığından ve isteğinizde doğru jetonları ve parametreleri kullandığınızdan emin olun. Aksi takdirde kullanıcı hesabı silinmiş veya devre dışı bırakılmış olabilir.

origin_mismatch

Yetkilendirme isteğini oluşturan JavaScript'in şeması, alan adı ve/veya bağlantı noktası, OAuth istemci kimliği için kayıtlı yetkilendirilmiş bir JavaScript kaynak URI'sı ile eşleşmeyebilir. Şuradaki yetkili JavaScript kaynaklarını inceleyin: Google API Console Credentials page.

redirect_uri_mismatch

Yetkilendirme isteğinde iletilen redirect_uri, OAuth istemci kimliğine ait yetkili yönlendirme URI'siyle eşleşmiyor. Google API Console Credentials pageiçindeki yetkili yönlendirme URI'lerini inceleyin.

Yetkilendirme isteğini oluşturan JavaScript'in şeması, alan adı ve/veya bağlantı noktası, OAuth istemci kimliği için kayıtlı yetkilendirilmiş bir JavaScript kaynak URI'sı ile eşleşmeyebilir. Google API Console Credentials pageiçindeki yetkilendirilmiş JavaScript kaynaklarını inceleyin.

redirect_uri parametresi, kullanımdan kaldırılan ve artık desteklenmeyen OAuth bant dışı (OOB) akışına işaret ediyor olabilir. Entegrasyonunuzu güncellemek için taşıma rehberini inceleyin.

invalid_request

Gönderdiğiniz istekle ilgili bir sorun var. Bunun birkaç nedeni olabilir:

  • İstek düzgün şekilde biçimlendirilmemiş
  • İstekte gerekli parametreler eksikti
  • İstek, Google'ın desteklemediği bir yetkilendirme yöntemi kullanıyor. OAuth entegrasyonunuzun önerilen entegrasyon yöntemini kullandığını doğrulayın

3. Adım: OAuth 2.0 sunucu yanıtını işleyin

OAuth 2.0 Uç Noktaları

OAuth 2.0 sunucusu, erişim jetonu isteğinizde belirtilen redirect_uri öğesine bir yanıt gönderir.

Kullanıcı isteği onaylarsa yanıt bir erişim jetonu içerir. Kullanıcı isteği onaylamazsa yanıt bir hata mesajı içerir. Erişim jetonu veya hata mesajı, aşağıda gösterildiği gibi yönlendirme URI'sinin karma parçasında döndürülür:

  • Erişim jetonu yanıtı:

    https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

    access_token parametresine ek olarak parça dizesi, her zaman Bearer olarak ayarlanan token_type parametresini ve jetonun kullanım ömrünü saniye cinsinden belirten expires_in parametresini de içerir. Erişim jetonu isteğinde state parametresi belirtilmişse yanıta bu parametrenin değeri de dahil edilir.

  • Hata yanıtı:
    https://oauth2.example.com/callback#error=access_denied

Örnek OAuth 2.0 sunucu yanıtı

Bu akışı, Google Drive'ınızdaki dosyaların meta verilerini görüntülemek için salt okuma erişimi isteyen aşağıdaki örnek URL'yi tıklayarak test edebilirsiniz:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

OAuth 2.0 akışını tamamladıktan sonra http://localhost/oauth2callback adresine yönlendirilirsiniz. Yerel makineniz söz konusu adreste bir dosya sunmazsa bu URL 404 NOT FOUND hatası verir. Bir sonraki adım, kullanıcı uygulamanıza tekrar yönlendirildiğinde URI'da döndürülen bilgiler hakkında daha fazla ayrıntı sağlar.

Google API'lerini çağırma

OAuth 2.0 Uç Noktaları

Uygulamanız bir erişim jetonu aldıktan sonra, API'nin gerektirdiği erişim kapsamları verilmişse bu jetonu belirli bir kullanıcı hesabı adına bir Google API'ye çağrı yapmak için kullanabilirsiniz. Bunu yapmak için access_token sorgu parametresi veya Authorization HTTP üst bilgisi Bearer değeri ekleyerek API'ye yapılan bir isteğe erişim jetonunu ekleyin. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üst bilgisi tercih edilir. Çoğu durumda (örneğin, Drive Files API'yi çağırırken) Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz.

OAuth 2.0 Playground'da tüm Google API'lerini deneyebilir ve kapsamlarını görüntüleyebilirsiniz.

HTTP GET örnekleri

Authorization: Bearer HTTP üst bilgisini kullanarak drive.files uç noktasına (Drive Files API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Burada, access_token sorgu dizesi parametresini kullanan kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı gösterilmektedir:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl örnekleri

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP başlığı seçeneğinin kullanıldığı bir örneği aşağıda bulabilirsiniz (tercih edilen):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternatif olarak sorgu dizesi parametresi seçeneğinden de yararlanabilirsiniz:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

JavaScript örnek kodu

Aşağıdaki kod snippet'i, Google API'lerine istek göndermek için CORS'un (kaynaklar arası kaynak paylaşımı) nasıl kullanılacağını göstermektedir. Bu örnekte, JavaScript için Google API'leri İstemci Kitaplığı kullanılmaz. Ancak istemci kitaplığını kullanmıyor olsanız bile ilgili kitaplıktaki dokümanlarda yer alan CORS destek kılavuzu bu istekleri daha iyi anlamanıza yardımcı olabilir.

Bu kod snippet'inde access_token değişkeni, yetkili kullanıcı adına API istekleri yapmak için aldığınız jetonu temsil eder. Eksiksiz örnek, bu jetonun tarayıcının yerel depolama alanında nasıl depolanacağını ve API isteği oluştururken nasıl alınacağını gösterir.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Tam örnek

OAuth 2.0 Uç Noktaları

Bu kod örneğinde, JavaScript için Google API'leri İstemci Kitaplığı kullanılmadan JavaScript'te OAuth 2.0 akışının nasıl tamamlanacağı gösterilmektedir. Kod, API isteğini denemek için bir düğme görüntüleyen HTML sayfası içindir. Düğmeyi tıklarsanız kod, sayfanın tarayıcınızın yerel depolama alanında bir API erişim jetonu depolayıp depolamadığını kontrol eder. Bu durumda API isteğini yürütür. Aksi takdirde OAuth 2.0 akışını başlatır.

OAuth 2.0 akışı için sayfa şu adımları izler:

  1. Kullanıcıyı Google'ın OAuth 2.0 sunucusuna yönlendirir. Bu sunucu, https://www.googleapis.com/auth/drive.metadata.readonly kapsamına erişim ister.
  2. İstenen bir veya daha fazla kapsama erişim izni verildikten (veya reddedildikten) sonra kullanıcı, erişim jetonunu parça tanımlayıcı dizesinden ayrıştıran orijinal sayfaya yönlendirilir.
  3. Sayfa, örnek API isteğini yapmak için erişim jetonunu kullanır.

    API isteği, yetkili kullanıcının Google Drive hesabıyla ilgili bilgileri almak için Drive API'nin about.get yöntemini çağırır.

  4. İstek başarıyla yürütülürse API yanıtı, tarayıcının hata ayıklama konsoluna kaydedilir.

Google Hesabınızın İzinler sayfasından uygulamaya erişimi iptal edebilirsiniz. Uygulama, Google API Dokümanları için OAuth 2.0 Demo olarak listelenir.

Bu kodu yerel olarak çalıştırmak için yetkilendirme kimlik bilgilerinize karşılık gelen YOUR_CLIENT_ID ve YOUR_REDIRECT_URI değişkenlerinin değerlerini ayarlamanız gerekir. YOUR_REDIRECT_URI değişkeni, sayfanın sunulduğu URL'ye ayarlanmalıdır. Değer, API Console Credentials pageiçinde yapılandırdığınız OAuth 2.0 istemcisi için yetkilendirilmiş yönlendirme URI'lerinden biriyle tam olarak eşleşmelidir. Bu değer yetkili bir URI ile eşleşmezse redirect_uri_mismatch hatası alırsınız. Projenizin bu istek için uygun API'yi de etkinleştirmiş olması gerekir.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

JavaScript kaynak doğrulama kuralları

Google, geliştiricilerin uygulamalarını güvende tutmalarına yardımcı olmak için JavaScript kaynaklarına aşağıdaki doğrulama kurallarını uygular. JavaScript kaynaklarınız bu kurallara uygun olmalıdır. Aşağıda belirtilen alan, ana makine ve şemanın tanımı için RFC 3986 bölüm 3'e bakın.

Doğrulama kuralları
Şema

JavaScript kaynakları düz HTTP yerine HTTPS şemasını kullanmalıdır. Localhost URI'ları (localhost IP adresi URI'leri dahil) bu kuraldan muaftır.

Düzenleyen

Ana makineler ham IP adresi olamaz. Yerel ana makine IP adresleri bu kuraldan muaftır.

Alan
  • Ana makine TLD'leri (Üst Düzey Alanlar) herkese açık son ek listesine ait olmalıdır.
  • Barındırıcı alan adları “googleusercontent.com” olamaz.
  • Uygulama, alan adının sahibi değilse JavaScript kaynakları, URL kısaltıcı alan adlarını (ör. goo.gl) içeremez.
  • Kullanıcı Bilgileri

    JavaScript kaynakları, kullanıcı bilgileri alt bileşenini içeremez.

    Yol

    JavaScript kaynakları, yol bileşenini içeremez.

    Sorgu

    JavaScript kaynakları sorgu bileşenini içeremez.

    Parça

    JavaScript kaynakları, parça bileşenini içeremez.

    Karakterler JavaScript kaynakları, aşağıdakiler de dahil olmak üzere belirli karakterleri içeremez:
    • Joker karakterler ('*')
    • Yazdırılamayan ASCII karakterleri
    • Geçersiz yüzde kodlamaları (yüzde işareti ve ardından iki onaltılık basamak içeren URL kodlama biçimine uymayan herhangi bir yüzde kodlaması)
    • Boş karakterler (kodlanmış bir NULL karakteri, ör. %00, %C0%80)

    Ek yetkilendirme

    OAuth 2.0 protokolünde, uygulamanız kapsamlarla tanımlanan kaynaklara erişim izni ister. Kaynaklar için ihtiyaç duyduğunuzda yetkilendirme istemek, en iyi kullanıcı deneyimi uygulaması olarak kabul edilir. Bu uygulamayı etkinleştirmek için Google'ın yetkilendirme sunucusu artımlı yetkilendirmeyi destekler. Bu özellik, gerektiğinde kapsamları istemenize olanak tanır. Kullanıcı yeni kapsam için izin verirse kullanıcının projeye verdiği tüm kapsamları içeren bir jetonla değiştirilebilecek bir yetkilendirme kodu döndürür.

    Örneğin, kullanıcıların müzik parçalarını deneyip mix'ler oluşturmasına olanak tanıyan bir uygulama, oturum açma sırasında çok az kaynağa ihtiyaç duyabilir ve oturum açan kişinin adından başka bir şeye ihtiyaç duyamayabilir. Ancak, tamamlanmış bir mix'i kaydetmek için kullanıcıların Google Drive'larına erişim gerekir. Çoğu kullanıcı, yalnızca uygulamanın gerçekten ihtiyaç duyduğu anda Google Drive'a erişmesi istenseydi bunu doğal bulurdu.

    Bu durumda, oturum açma sırasında uygulama, temel oturum açma işlemi gerçekleştirmek için openid ve profile kapsamlarını isteyebilir ve daha sonra bir karışımı kaydetmek için ilk istek sırasında https://www.googleapis.com/auth/drive.file kapsamını isteyebilir.

    Artımlı yetkilendirmeden alınan erişim jetonu için aşağıdaki kurallar geçerlidir:

    • Bu jeton, birleştirilmiş yeni yetkilendirmeye dahil edilen kapsamlardan herhangi birine karşılık gelen kaynaklara erişmek için kullanılabilir.
    • Bir erişim jetonu almak amacıyla birleştirilmiş yetkilendirme için yenileme jetonunu kullandığınızda, erişim jetonu birleşik yetkilendirmeyi temsil eder ve yanıta dahil edilen scope değerleri için kullanılabilir.
    • Birleşik yetkilendirme, farklı istemcilerden izinler istenmiş olsa bile kullanıcının API projesine verdiği tüm kapsamları içerir. Örneğin, bir kullanıcı bir uygulamanın masaüstü istemcisini kullanarak bir kapsama erişim izni verirse ve daha sonra bir mobil istemci aracılığıyla aynı uygulamaya başka bir kapsam daha verdiyse birleştirilmiş yetkilendirme her iki kapsamı da içerir.
    • Birleşik yetkilendirmeyi temsil eden bir jetonu iptal ederseniz ilişkilendirilmiş kullanıcı adına bu yetkilendirmenin tüm kapsamlarına erişim aynı anda iptal edilir.

    Aşağıdaki kod örnekleri, mevcut bir erişim jetonuna kapsam ekleme işlemini gösterir. Bu yaklaşım sayesinde uygulamanız birden fazla erişim jetonu yönetmek zorunda kalmaz.

    OAuth 2.0 Uç Noktaları

    Mevcut bir erişim jetonuna kapsam eklemek için Google'ın OAuth 2.0 sunucusuna gönderdiğiniz isteğinize include_granted_scopes parametresini dahil edin.

    Aşağıdaki kod snippet'inde bunun nasıl yapılacağı gösterilmektedir. Snippet, erişim jetonunuzun geçerli olduğu kapsamları tarayıcının yerel depolama alanında depoladığınızı varsayar. (Tam örnek kodu, tarayıcının yerel depolama alanında oauth2-test-params.scope özelliğini ayarlayarak erişim jetonunun geçerli olduğu kapsamların listesini saklar.)

    Snippet, erişim jetonunun geçerli olduğu kapsamları belirli bir sorgu için kullanmak istediğiniz kapsamla karşılaştırır. Erişim jetonu bu kapsamı karşılamıyorsa OAuth 2.0 akışı başlar. Buradaki oauth2SignIn işlevi, 2. adımda sağlanan (ve daha sonra eksiksiz örnekte sağlanan) işlevle aynıdır.

    var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    
    var current_scope_granted = false;
    if (params.hasOwnProperty('scope')) {
      var scopes = params['scope'].split(' ');
      for (var s = 0; s < scopes.length; s++) {
        if (SCOPE == scopes[s]) {
          current_scope_granted = true;
        }
      }
    }
    
    if (!current_scope_granted) {
      oauth2SignIn(); // This function is defined elsewhere in this document.
    } else {
      // Since you already have access, you can proceed with the API request.
    }

    Jetonu iptal etme

    Bazı durumlarda kullanıcı, bir uygulamaya verilen erişimi iptal etmek isteyebilir. Kullanıcı, Hesap Ayarları sayfasını ziyaret ederek erişimi iptal edebilir. Daha fazla bilgi için Hesabınıza erişimi olan üçüncü taraf site ve uygulamaların Site veya uygulama erişimini kaldırma başlıklı destek belgesini inceleyin.

    Ayrıca bir uygulama, kendisine verilen erişimi programlı olarak iptal edebilir. Kullanıcının abonelikten çıktığı, uygulamayı kaldırdığı veya uygulamanın gerektirdiği API kaynaklarının önemli ölçüde değiştiği durumlarda programatik iptal önemlidir. Başka bir deyişle, kaldırma süreci kapsamında, uygulamaya daha önce verilmiş olan izinlerin kaldırıldığından emin olmak için bir API isteği gönderilebilir.

    OAuth 2.0 Uç Noktaları

    Uygulamanız, bir jetonu programlı olarak iptal etmek için https://oauth2.googleapis.com/revoke adresine istek gönderir ve jetonu parametre olarak ekler:

    curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
            https://oauth2.googleapis.com/revoke?token={token}

    Bu jeton, erişim jetonu veya yenileme jetonu olabilir. Jeton bir erişim jetonuysa ve buna karşılık gelen bir yenileme jetonu varsa yenileme jetonu da iptal edilir.

    İptal başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata koşullarında hata koduyla birlikte 400 HTTP durum kodu döndürülür.

    Aşağıdaki JavaScript snippet'i, JavaScript için Google API'leri İstemci Kitaplığı kullanılmadan JavaScript'te bir jetonun nasıl iptal edileceğini gösterir. Jetonları iptal etmek için Google'ın OAuth 2.0 uç noktası, Kaynaklar Arası Kaynak Paylaşımı'nı (CORS) desteklemediğinden kod, isteği yayınlamak için XMLHttpRequest() yöntemini kullanmak yerine bir form oluşturur ve formu uç noktaya gönderir.

    function revokeAccess(accessToken) {
      // Google's OAuth 2.0 endpoint for revoking access tokens.
      var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';
    
      // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
      var form = document.createElement('form');
      form.setAttribute('method', 'post');
      form.setAttribute('action', revokeTokenEndpoint);
    
      // Add access token to the form so it is set as value of 'token' parameter.
      // This corresponds to the sample curl request, where the URL is:
      //      https://oauth2.googleapis.com/revoke?token={token}
      var tokenField = document.createElement('input');
      tokenField.setAttribute('type', 'hidden');
      tokenField.setAttribute('name', 'token');
      tokenField.setAttribute('value', accessToken);
      form.appendChild(tokenField);
    
      // Add form to page and submit it to actually revoke the token.
      document.body.appendChild(form);
      form.submit();
    }