JavaScript Web Uygulamaları için OAuth 2.0'ı Kullanma

OAuth 2.0 uç noktaları

Google'ın OAuth 2.0 uç noktasından (https://accounts.google.com/o/oauth2/v2/auth) erişim isteğinde bulunmak için bir URL oluşturun. Bu uç noktaya HTTPS üzerinden erişilebilir; sıradan HTTP bağlantıları reddedilir.

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

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

Aşağıdaki örnek URL, kullanıcının YouTube hesabını görüntülemeye izin veren bir kapsama çevrimdışı erişim (access_type=offline) isteğinde bulunur. Yeni erişim jetonunun, kullanıcının daha önce uygulamaya erişim izni verdiği tüm kapsamları kapsadığından emin olmak için artımlı yetkilendirme kullanılır. URL, zorunlu redirect_uri, response_type ve client_id parametrelerinin yanı sıra state parametresi için de değerler belirler. URL, okunabilirlik için satır sonları ve boşluklar içeriyor.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 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 istemci kitaplığı kullanılmadan JavaScript'de 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/youtube.force-ssl',
                '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();
}

OAuth 2.0 uç noktaları

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

Kullanıcı isteği onaylarsa yanıtta bir erişim jetonu bulunur. Kullanıcı isteği onaylamıyorsa yanıtta bir hata mesajı yer alır. Erişim jetonu veya hata mesajı, aşağıdaki gibi yönlendirme URI'sinin karma oluşturma 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

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

• Hata yanıtı:

  https://oauth2.example.com/callback#error=access_denied

Örnek OAuth 2.0 sunucu yanıtı

Aşağıdaki örnek URL'yi tıklayarak bu akışı test edebilirsiniz. Bu URL, Google Drive'ınızdaki dosyaların meta verilerini görüntülemek için salt okunur erişim ve Google Takvim etkinliklerinizi görüntülemek için salt okunur erişim ister:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

OAuth 2.0 akışını tamamladıktan sonra http://localhost/oauth2callback adresine yönlendirilirsiniz. Yerel makineniz bu adreste bir dosya sunmadığı sürece bu URL, 404 NOT FOUND hatası verir. Sonraki adımda, kullanıcı uygulamanıza geri yönlendirildiğinde URI'de döndürülen bilgiler hakkında daha fazla bilgi verilmektedir.

OAuth 2.0 uç noktaları

Kullanıcının uygulamanıza belirli bir kapsama erişim izni verip vermediğini kontrol etmek için erişim jetonu yanıtındaki scope alanını inceleyin. access_token tarafından verilen erişim kapsamları, boşlukla ayrılmış, büyük/küçük harf duyarlı dizelerin listesi olarak ifade edilir.

Örneğin, aşağıdaki örnek erişim jetonu yanıtı, kullanıcının uygulamanıza YouTube videolarını, derecelendirmelerini, yorumlarını ve altyazılarını görme, düzenleme ve kalıcı olarak silme izni verdiğini gösterir:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

OAuth 2.0 uç noktaları

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

YouTube Data API'nin yalnızca plak şirketleri ve film stüdyoları gibi birden fazla YouTube kanalına sahip ve bu kanalları yöneten YouTube içerik sahipleri için hizmet hesaplarını desteklediğini unutmayın.

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

HTTP GET örnekleri

Authorization: Bearer HTTP başlığı kullanılarak youtube.channels uç noktasına (YouTube Data API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Kimliği doğrulanmış kullanıcı için access_token sorgu dizesi parametresini kullanan aynı API'ye yapılan bir çağrı aşağıda verilmiştir:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl örnek

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üst bilgisi seçeneğini kullanan bir örneği aşağıda bulabilirsiniz (tercih edilir):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Alternatif olarak sorgu dizesi parametresi seçeneğini de kullanabilirsiniz:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

JavaScript örnek kodu

Aşağıdaki kod snippet'inde, bir Google API'ye istek göndermek için CORS'un (Kaynaklar arası kaynak paylaşımı) nasıl kullanılacağı gösterilmektedir. Bu örnekte JavaScript için Google API'leri istemci kitaplığı kullanılmamaktadır. Ancak istemci kitaplığını kullanmıyor olsanız bile söz konusu kitaplığın dokümanlarında yer alan CORS desteği 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 göndermek için edindiğiniz jetonu temsil eder. Tam örnekte, bu jetonun tarayıcı yerel depolama alanında nasıl depolanacağı ve API isteği yapılırken nasıl alınacağı gösterilmektedir.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

OAuth 2.0 uç noktaları

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

OAuth 2.0 akışında sayfa şu adımları izler:

1. Kullanıcıyı, https://www.googleapis.com/auth/youtube.force-ssl kapsamına erişim isteyen Google'ın OAuth 2.0 sunucusuna yönlendirir.
2. İstekte bulunulan bir veya daha fazla kapsama erişim izni verildikten (veya reddedildikten) sonra kullanıcı, parça tanımlayıcısı dizesinden erişim jetonunu ayrıştıran orijinal sayfaya yönlendirilir.
3. Sayfa, kullanıcının uygulamaya hangi kapsamlarda erişim izni verdiğini kontrol eder.

4. Kullanıcı istenen kapsamlara erişim izni verdiyse sayfa, örnek API isteğini yapmak için erişim jetonunu kullanır.

   Bu API isteği, yetkili kullanıcının YouTube kanalı hakkında veri almak için YouTube Data API'nin channels.list yöntemini çağırır.

5. İ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 YOUR_CLIENT_ID ve YOUR_REDIRECT_URI değişkenleri için yetkilendirme kimlik bilgilerinize karşılık gelen değerleri ayarlamanız gerekir. YOUR_REDIRECT_URI değişkeni, sayfanın yayınlandığı URL ile aynı URL'ye ayarlanmalıdır. Değer, API Console Credentials page'te yapılandırdığınız OAuth 2.0 istemcisi için yetkili 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. Projenizde bu istek için uygun API'nin de etkinleştirilmiş olması gerekir.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

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

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // 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/youtube/v3/channels?part=snippet&mine=true&' +
          '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() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // 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/youtube.force-ssl',
                  'state': state,
                  '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>

OAuth 2.0 uç noktaları

Bu örnekte, arayan uygulama, kullanıcının uygulamaya daha önce verdiği diğer erişim izinlerine ek olarak kullanıcının YouTube Analytics verilerini almak için erişim isteğinde bulunur.

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

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

Kod snippet'i, 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ı kapsamıyorsa OAuth 2.0 akışı başlar. Buradaki oauth2SignIn işlevi, 2. adımda sağlanan işlevle (ve tam örnekte daha sonra sağlanan işlevle) aynıdır.

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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.
}

OAuth 2.0 uç noktaları

Bir jetonu programatik olarak iptal etmek için uygulamanız https://oauth2.googleapis.com/revoke adresine bir 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}

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 işlemi başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata durumlarında, hata koduyla birlikte bir HTTP durum kodu 400 döndürülür.

Aşağıdaki JavaScript snippet'inde, JavaScript için Google API'leri istemci kitaplığı kullanılmadan JavaScript'te bir jetonun nasıl iptal edileceği gösterilmektedir. Google'ın jetonları iptal etmek için kullandığı OAuth 2.0 uç noktası kaynakta çapraz kaynak paylaşımını (CORS) desteklemediğinden kod, isteği yayınlamak için XMLHttpRequest() yöntemini kullanmak yerine bir form oluşturup 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();
}