Menggunakan OAuth 2.0 untuk Aplikasi Web JavaScript

Endpoint OAuth 2.0

Buat URL untuk meminta akses dari endpoint OAuth 2.0 Google di https://accounts.google.com/o/oauth2/v2/auth. Endpoint ini dapat diakses melalui HTTPS; koneksi HTTP biasa ditolak.

Server otorisasi Google mendukung parameter string kueri berikut untuk aplikasi server web:

Contoh pengalihan ke server otorisasi Google

Contoh URL di bawah meminta akses offline (access_type=offline) ke cakupan yang mengizinkan akses untuk melihat akun YouTube pengguna. API ini menggunakan otorisasi inkremental untuk memastikan bahwa token akses baru mencakup cakupan apa pun yang sebelumnya diberikan oleh pengguna untuk akses aplikasi. URL juga menetapkan nilai untuk parameter redirect_uri, response_type, dan client_id yang diperlukan serta untuk parameter state. URL berisi baris baru dan spasi agar lebih mudah dibaca.

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

Setelah Anda membuat URL permintaan, alihkan pengguna ke URL tersebut.

Kode contoh JavaScript

Cuplikan JavaScript berikut menunjukkan cara memulai alur otorisasi di JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Karena endpoint OAuth 2.0 ini tidak mendukung Cross-Origin Resource Sharing (CORS), cuplikan akan membuat formulir yang membuka permintaan ke endpoint tersebut.

/*
 * 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();
}

Endpoint OAuth 2.0

Server OAuth 2.0 mengirimkan respons ke redirect_uri yang ditentukan dalam permintaan token akses Anda.

Jika pengguna menyetujui permintaan, respons akan berisi token akses. Jika permintaan tersebut tidak disetujui, respons akan berisi pesan error. Token akses atau pesan error ditampilkan pada fragmen hash URI alihan, seperti yang ditunjukkan di bawah:

• Respons token akses:

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

  Selain parameter access_token, string fragmen juga berisi parameter token_type, yang selalu ditetapkan ke Bearer, dan parameter expires_in, yang menentukan masa aktif token, dalam detik. Jika parameter state ditentukan dalam permintaan token akses, nilainya juga akan disertakan dalam respons.

• Respons error:

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

Contoh respons server OAuth 2.0

Anda dapat menguji alur ini dengan mengklik URL contoh berikut, yang meminta akses hanya baca untuk melihat metadata berbagai file di Google Drive:

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

Setelah menyelesaikan alur OAuth 2.0, Anda akan dialihkan ke http://localhost/oauth2callback. URL tersebut akan menghasilkan error 404 NOT FOUND kecuali jika mesin lokal Anda kebetulan menayangkan file di alamat tersebut. Langkah berikutnya memberikan detail selengkapnya tentang informasi yang ditampilkan di URI ketika pengguna dialihkan kembali ke aplikasi Anda.

Endpoint OAuth 2.0

Setelah aplikasi Anda mendapatkan token akses, Anda dapat menggunakan token tersebut untuk melakukan panggilan ke Google API atas nama akun pengguna tertentu jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan parameter kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih disarankan karena string kueri cenderung terlihat di log server. Pada umumnya, Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil YouTube Data API).

Perhatikan bahwa YouTube Data API hanya mendukung akun layanan untuk pemilik konten YouTube yang memiliki dan mengelola beberapa channel YouTube, seperti label rekaman dan studio film.

Anda dapat mencoba semua Google API dan melihat cakupannya di OAuth 2.0 Playground.

Contoh GET HTTP

Panggilan ke endpoint youtube.channels (YouTube Data API) menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda perlu menetapkan token akses Anda sendiri:

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

Berikut adalah panggilan ke API yang sama untuk pengguna yang diautentikasi menggunakan parameter string kueri access_token:

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

Contoh curl

Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut adalah contoh yang menggunakan opsi header HTTP (lebih disukai):

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

Atau, sebagai alternatif, opsi parameter string kueri:

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

Kode contoh JavaScript

Cuplikan kode di bawah menunjukkan cara menggunakan CORS (Cross-origin resource sharing) untuk mengirim permintaan ke Google API. Contoh ini tidak menggunakan Library Klien Google API untuk JavaScript. Namun, meskipun Anda tidak menggunakan library klien, panduan dukungan CORS dalam dokumentasi library tersebut mungkin akan membantu Anda memahami permintaan ini dengan lebih baik.

Dalam cuplikan kode ini, variabel access_token mewakili token yang telah Anda peroleh untuk membuat permintaan API atas nama pengguna yang diotorisasi. Contoh lengkap menunjukkan cara menyimpan token tersebut di penyimpanan lokal browser dan mengambilnya saat membuat permintaan API.

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);

Endpoint OAuth 2.0

Contoh kode ini menunjukkan cara menyelesaikan alur OAuth 2.0 di JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Kode ini ditujukan untuk halaman HTML yang menampilkan tombol untuk mencoba permintaan API. Jika Anda mengklik tombol, kode akan memeriksa apakah halaman telah menyimpan token akses API di penyimpanan lokal browser Anda. Jika demikian, permintaan API akan dijalankan. Jika tidak, alur OAuth 2.0 akan dimulai.

Untuk alur OAuth 2.0, halaman tersebut akan mengikuti langkah-langkah berikut:

1. Tindakan ini akan mengarahkan pengguna ke server OAuth 2.0 Google, yang meminta akses ke cakupan https://www.googleapis.com/auth/youtube.force-ssl.
2. Setelah memberikan (atau menolak) akses ke satu atau beberapa cakupan yang diminta, pengguna akan dialihkan ke halaman asli, yang akan mengurai token akses dari string ID fragmen.

3. Halaman ini menggunakan token akses untuk membuat permintaan API contoh.

   Permintaan API ini memanggil metode channels.list YouTube Data API untuk mengambil data tentang channel YouTube pengguna yang diotorisasi.

4. Jika permintaan berhasil dijalankan, respons API akan dicatat dalam konsol proses debug browser.

Anda dapat mencabut akses ke aplikasi melalui halaman Izin untuk Akun Google Anda. Aplikasi akan tercantum sebagai Demo OAuth 2.0 untuk Dokumen Google API.

Untuk menjalankan kode ini secara lokal, Anda harus menetapkan nilai untuk variabel YOUR_CLIENT_ID dan YOUR_REDIRECT_URI yang sesuai dengan kredensial otorisasi Anda. Variabel YOUR_REDIRECT_URI harus ditetapkan ke URL yang sama tempat halaman ditayangkan. Nilai ini harus sama persis dengan salah satu URI alihan yang diotorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di API Console Credentials page. Jika nilai ini tidak cocok dengan URI yang diberi otorisasi, Anda akan mendapatkan error redirect_uri_mismatch. Project Anda juga harus mengaktifkan API yang sesuai untuk permintaan ini.

<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>

Endpoint OAuth 2.0

Dalam contoh ini, aplikasi panggilan meminta akses untuk mengambil data YouTube Analytics pengguna selain akses lain yang telah diberikan pengguna ke aplikasi.

Untuk menambahkan cakupan ke token akses yang ada, sertakan parameter include_granted_scopes dalam permintaan Anda ke server OAuth 2.0 Google.

Cuplikan kode berikut menunjukkan cara melakukannya. Cuplikan mengasumsikan bahwa Anda telah menyimpan cakupan yang valid untuk token akses Anda di penyimpanan lokal browser. (Kode contoh lengkap menyimpan daftar cakupan tempat token aksesnya valid dengan menyetel properti oauth2-test-params.scope di penyimpanan lokal browser.)

Cuplikan membandingkan cakupan yang valid untuk token akses dengan cakupan yang ingin Anda gunakan untuk kueri tertentu. Jika token akses tidak mencakup cakupan tersebut, alur OAuth 2.0 akan dimulai. Di sini, fungsi oauth2SignIn sama dengan fungsi yang disediakan pada langkah 2 (dan akan diberikan nanti dalam contoh lengkap).

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.
}

Endpoint OAuth 2.0

Untuk mencabut token secara terprogram, aplikasi Anda membuat permintaan ke https://oauth2.googleapis.com/revoke dan menyertakan token tersebut sebagai parameter:

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

Token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

Jika pencabutan berhasil diproses, kode status HTTP responsnya adalah 200. Untuk kondisi error, kode status HTTP 400 ditampilkan bersama dengan kode error.

Cuplikan JavaScript berikut menunjukkan cara mencabut token di JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Karena endpoint OAuth 2.0 Google untuk mencabut token tidak mendukung Cross-origin Resource Sharing (CORS), kode akan membuat formulir dan mengirimkan formulir ke endpoint, bukan menggunakan metode XMLHttpRequest() untuk memposting permintaan.

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();
}