Menggunakan OAuth 2.0 untuk aplikasi web sisi klien

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 web aplikasi server:

Contoh pengalihan ke server otorisasi Google

Contoh URL ditampilkan di bawah, dengan jeda baris dan spasi agar lebih mudah dibaca. Permintaan URL akses ke cakupan yang mengizinkan akses untuk mengambil data YouTube pengguna. Model ini menggunakan model otorisasi (include_granted_scopes=true) untuk memastikan bahwa token akses baru mencakup cakupan apa pun yang sebelumnya telah diberikan akses aplikasi oleh pengguna. Beberapa lainnya parameter juga ditetapkan dalam contoh.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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 dalam JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Karena OAuth ini 2.0 tidak mendukung Cross-Origin Resource Sharing (CORS), cuplikannya 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.

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

• 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 diatur ke Bearer, dan parameter expires_in, yang menentukan masa berlaku token, dalam hitungan detik. Jika parameter state telah 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:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 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 komputer lokal Anda menyajikan file di alamat tersebut. Langkah berikutnya memberikan detail lebih lanjut tentang informasi yang ditampilkan dalam URI saat pengguna dialihkan kembali ke aplikasi Anda.

Endpoint OAuth 2.0

Setelah aplikasi Anda mendapatkan token akses, Anda bisa menggunakan token tersebut untuk melakukan panggilan ke API atas nama objek jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam sebagian besar Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil YouTube Live Streaming API).

Perhatikan bahwa YouTube Live Streaming API tidak mendukung alur akun layanan. Karena ada bukanlah cara untuk menautkan Akun Layanan ke akun YouTube, berupaya mengotorisasi permintaan dengan alur akan menghasilkan error NoLinkedYouTubeAccount.

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

Contoh GET HTTP

Panggilan ke liveBroadcasts.list endpoint (YouTube Live Streaming API) menggunakan HTTP Authorization: Bearer {i>header<i} akan terlihat seperti berikut. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&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/liveBroadcasts?part=id%2Csnippet&mine=true

Atau, sebagai alternatif, opsi parameter string kueri:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Kode contoh JavaScript

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

Dalam cuplikan kode ini, variabel access_token mewakili token yang Anda miliki untuk membuat permintaan API atas nama pengguna yang diotorisasi. Informasi lengkap contoh 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/liveBroadcasts?part=id,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 tersebut ditujukan untuk halaman HTML yang menampilkan tombol untuk mencoba permintaan API. Jika Anda mengeklik tombol itu, kode tersebut akan memeriksa untuk melihat apakah laman telah menyimpan Token akses API di penyimpanan lokal browser Anda. Jika demikian, permintaan API akan dijalankan. Jika tidak, proses ini akan memulai alur OAuth 2.0.

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

1. Ini mengarahkan pengguna ke server OAuth 2.0 Google, yang meminta akses ke https://www.googleapis.com/auth/youtube.force-ssl cakupan.
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 menggunakan token akses untuk membuat permintaan API contoh.

   Permintaan API ini memanggil liveBroadcasts.list YouTube Data API untuk mengambil daftar siaran video untuk saluran YouTube pengguna yang diotorisasi.

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

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

Untuk menjalankan kode ini secara lokal, Anda perlu menetapkan nilai untuk YOUR_CLIENT_ID dan YOUR_REDIRECT_URI variabel yang sesuai dengan kredensial otorisasi. Variabel YOUR_REDIRECT_URI harus ditetapkan ke URL yang sama dengan tempat halaman ditayangkan. Nilai harus sama persis dengan salah satu URI pengalihan yang diotorisasi untuk klien OAuth 2.0, yang telah Anda konfigurasi di API Console Credentials pageJika nilai ini tidak cocok dengan URI yang diberi otorisasi, Anda akan mendapatkan redirect_uri_mismatch {i>error<i}. Proyek Anda juga harus memiliki 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/liveBroadcasts?part=id,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 pemanggil meminta akses untuk mengambil data YouTube pengguna, selain akses lain apa pun yang yang telah diberikan ke aplikasi.

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

Cuplikan kode berikut menunjukkan cara melakukannya. Cuplikan tersebut mengasumsikan bahwa Anda telah menyimpan cakupan di mana token akses Anda valid dalam penyimpanan lokal browser. ( kode contoh lengkap menyimpan daftar cakupan tempat token akses valid dengan menyetel properti oauth2-test-params.scope di parameter storage.)

Cuplikan ini membandingkan cakupan tempat token akses valid 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 diberikan nanti dalam langkah selesai contoh).

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 pembaruan yang sesuai, token pembaruan juga akan dicabut.

Jika pencabutan berhasil diproses, kode status HTTP respons tersebut 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 jika 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();
}