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 akan 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. Library ini menggunakan otorisasi inkremental untuk memastikan bahwa token akses baru mencakup cakupan apa pun yang sebelumnya diberikan akses aplikasi oleh pengguna. 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 ini 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 pengguna tidak menyetujui permintaan tersebut, respons akan berisi pesan error. Token akses atau pesan error ditampilkan pada fragmen hash URI pengalihan, seperti yang ditunjukkan dalam contoh berikut:

• 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 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 contoh URL berikut, yang meminta akses hanya baca untuk melihat metadata file di Google Drive Anda dan akses hanya baca untuk melihat acara Google Kalender Anda:

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, browser akan mengalihkan Anda ke OAuth 2.0 Playground, alat untuk menguji alur OAuth. Anda akan melihat bahwa OAuth 2.0 Playground telah otomatis mengambil kode otorisasi.

Endpoint OAuth 2.0

Untuk memeriksa apakah pengguna telah memberi aplikasi Anda akses ke cakupan tertentu, periksa kolom scope dalam respons token akses. Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang dipisahkan spasi dan peka huruf besar/kecil.

Misalnya, contoh respons token akses berikut menunjukkan bahwa pengguna telah memberikan izin kepada aplikasi Anda untuk melihat, mengedit, dan menghapus secara permanen video YouTube, rating, komentar, dan teks pengguna:

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

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

Panggilan ke endpoint youtube.channels (YouTube Data API) menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda harus menentukan 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, 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 kemungkinan akan membantu Anda lebih memahami permintaan ini.

Dalam cuplikan kode ini, variabel access_token mewakili token yang telah Anda peroleh untuk membuat permintaan API atas nama pengguna yang diberi otorisasi. 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 ya, permintaan API akan dijalankan. Jika tidak, alur OAuth 2.0 akan dimulai.

Untuk alur OAuth 2.0, halaman ini mengikuti langkah-langkah berikut:

1. Tindakan ini 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 mengurai token akses dari string ID fragmen.
3. Halaman ini memeriksa cakupan mana yang telah diberikan akses oleh pengguna ke aplikasi.

4. Jika pengguna telah memberikan akses ke cakupan yang diminta, halaman akan menggunakan token akses untuk membuat contoh permintaan API.

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

5. 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 ini tercantum sebagai nama aplikasi yang diberikan di halaman branding dalam layar izin OAuth selama pembuatan client ID.

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 dengan tempat halaman ditayangkan. Nilai harus sama persis dengan salah satu URI pengalihan yang diizinkan untuk klien OAuth 2.0, yang Anda konfigurasi di halaman Klien Konsol Cloud. Jika nilai ini tidak cocok dengan URI yang diizinkan, 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 yang memanggil 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 ini mengasumsikan bahwa Anda telah menyimpan cakupan yang valid untuk token akses Anda di penyimpanan lokal browser. (Kode contoh lengkap menyimpan daftar cakupan yang token aksesnya valid dengan menetapkan properti oauth2-test-params.scope di penyimpanan lokal browser.)

Cuplikan ini 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 yang disediakan di langkah 2 (dan yang disediakan 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 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 tersebut 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();
}