Menggunakan model token

Library JavaScript google.accounts.oauth2 membantu Anda meminta izin pengguna dan mendapatkan token akses untuk menggunakan data pengguna. Library ini didasarkan pada alur pemberian implisit OAuth 2.0 dan dirancang untuk memungkinkan Anda memanggil Google API secara langsung menggunakan REST dan CORS, atau menggunakan library klien Google API untuk JavaScript (juga dikenal sebagai gapi.client) untuk akses yang sederhana dan fleksibel ke API kami yang lebih kompleks.

Sebelum mengakses data pengguna yang dilindungi dari browser, pengguna di situs Anda akan memicu proses pemilih akun, login, dan izin berbasis web Google, dan terakhir server OAuth Google akan menerbitkan dan menampilkan token akses ke aplikasi web Anda.

Dalam model otorisasi berbasis token, Anda tidak perlu menyimpan token peremajaan per pengguna di server backend.

Sebaiknya ikuti pendekatan yang diuraikan di sini, bukan teknik yang tercakup dalam panduan OAuth 2.0 untuk Aplikasi Web Sisi Klien lama.

Penyiapan

Temukan atau buat client ID dengan mengikuti langkah-langkah yang dijelaskan dalam panduan Mendapatkan client ID Google API. Selanjutnya, tambahkan library klien ke halaman di situs Anda yang akan memanggil Google API. Terakhir, lakukan inisialisasi klien token. Biasanya, hal ini dilakukan dalam pengendali onload library klien.

Melakukan inisialisasi klien token

Panggil initTokenClient() untuk menginisialisasi klien token baru dengan ID klien aplikasi web Anda, secara opsional, Anda dapat menyertakan daftar satu atau beberapa cakupan yang perlu diakses pengguna:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

Memicu alur token OAuth 2.0

Gunakan metode requestAccessToken() untuk memicu alur UX token dan mendapatkan token akses. Google meminta pengguna untuk:

  • Pilih akunnya,
  • login ke Akun Google jika belum login,
  • memberikan izin agar aplikasi web Anda dapat mengakses setiap cakupan yang diminta.

Gestur pengguna memicu alur token: <button onclick="client.requestAccessToken();">Authorize me</button>

Google kemudian menampilkan TokenResponse yang berisi token akses dan daftar cakupan yang aksesnya telah diberikan oleh pengguna, atau error, ke pengendali callback Anda.

Pengguna dapat menutup pemilih akun atau jendela login. Jika demikian, fungsi callback Anda tidak akan dipanggil.

Desain dan pengalaman pengguna untuk aplikasi Anda hanya boleh diterapkan setelah peninjauan menyeluruh terhadap Kebijakan OAuth 2.0 Google. Kebijakan ini mencakup cara menggunakan beberapa cakupan, kapan dan cara menangani izin pengguna, dan lainnya.

Otorisasi inkremental adalah kebijakan dan metodologi desain aplikasi yang digunakan untuk meminta akses ke resource, menggunakan cakupan, hanya sesuai kebutuhan, bukan di awal dan sekaligus. Pengguna dapat menyetujui atau menolak pembagian setiap resource yang diminta oleh aplikasi Anda, yang dikenal sebagai izin terperinci.

Selama proses ini, Google meminta izin pengguna, mencantumkan setiap cakupan yang diminta satu per satu, pengguna memilih resource yang akan dibagikan ke aplikasi Anda, dan terakhir, Google memanggil fungsi callback Anda untuk menampilkan Token akses dan cakupan yang disetujui pengguna. Kemudian, aplikasi Anda akan menangani berbagai kemungkinan hasil dengan izin terperinci dengan aman.

Namun, ada pengecualian. Aplikasi Google Workspace Enterprise dengan delegasi otoritas di seluruh domain atau aplikasi yang ditandai sebagai Tepercaya, akan mengabaikan layar izin izin terperinci. Untuk aplikasi ini, pengguna tidak akan melihat layar izin izin terperinci. Sebagai gantinya, aplikasi Anda akan menerima semua cakupan yang diminta atau tidak sama sekali.

Untuk informasi yang lebih mendetail, lihat Cara menangani izin terperinci.

Otorisasi inkremental

Untuk aplikasi web, dua skenario tingkat tinggi berikut menunjukkan otorisasi inkremental menggunakan:

  • Aplikasi Ajax satu halaman, sering menggunakan XMLHttpRequest dengan akses dinamis ke resource.
  • Beberapa halaman web, resource dipisahkan dan dikelola berdasarkan per halaman.

Kedua skenario ini disajikan untuk mengilustrasikan pertimbangan dan metodologi desain, tetapi tidak dimaksudkan sebagai rekomendasi komprehensif tentang cara mem-build izin ke dalam aplikasi Anda. Aplikasi di dunia nyata dapat menggunakan variasi atau kombinasi teknik ini.

Ajax

Tambahkan dukungan untuk otorisasi inkremental ke aplikasi Anda dengan melakukan beberapa panggilan ke requestAccessToken() dan menggunakan parameter scope objek OverridableTokenClientConfig untuk meminta cakupan individual pada saat diperlukan dan hanya jika diperlukan. Dalam contoh ini, resource akan diminta dan terlihat hanya setelah gestur pengguna meluaskan bagian konten yang diciutkan.

Aplikasi Ajax
Lakukan inisialisasi klien token saat pemuatan halaman: 
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
Minta izin dan dapatkan token akses melalui gestur pengguna, klik `+` untuk membuka:

Dokumen untuk dibaca

Menampilkan dokumen terbaru

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );

Acara mendatang

Menampilkan info kalender

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );

Menampilkan foto

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );

Setiap panggilan ke requestAccessToken memicu momen izin pengguna, aplikasi Anda hanya akan memiliki akses ke resource yang diperlukan oleh bagian yang dipilih pengguna untuk diperluas, sehingga membatasi berbagi resource melalui pilihan pengguna.

Beberapa halaman web

Saat mendesain untuk otorisasi inkremental, beberapa halaman digunakan untuk meminta hanya cakupan yang diperlukan untuk memuat halaman, sehingga mengurangi kompleksitas dan kebutuhan untuk melakukan beberapa panggilan guna mendapatkan izin pengguna dan mengambil token akses.

Aplikasi multi-halaman
Halaman web Kode
Halaman 1. Dokumen untuk dibaca 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
Halaman 2. Acara mendatang 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
Halaman 3. Carousel foto 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();

Setiap halaman meminta cakupan yang diperlukan dan mendapatkan token akses dengan memanggil initTokenClient() dan requestAccessToken() pada waktu pemuatan. Dalam skenario ini, setiap halaman web digunakan untuk memisahkan fungsi dan resource pengguna secara jelas menurut cakupan. Dalam situasi dunia nyata, setiap halaman dapat meminta beberapa cakupan terkait.

Izin terperinci

Izin terperinci ditangani dengan cara yang sama di semua skenario; setelah requestAccessToken() memanggil fungsi callback Anda dan token akses ditampilkan, pastikan pengguna telah menyetujui cakupan yang diminta menggunakan hasGrantedAllScopes() atau hasGrantedAnyScope(). Contoh:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

Semua hibah yang diterima sebelumnya dari sesi atau permintaan sebelumnya juga akan disertakan dalam respons. Data izin pengguna dipertahankan per pengguna dan Client-ID, serta dipertahankan di beberapa panggilan ke initTokenClient() atau requestAccessToken(). Secara default, izin pengguna hanya diperlukan saat pertama kali pengguna mengunjungi situs Anda dan meminta cakupan baru, tetapi dapat diminta pada setiap pemuatan halaman menggunakan prompt=consent di objek konfigurasi Klien Token.

Menggunakan token

Dalam model Token, token akses tidak disimpan oleh OS atau browser, tetapi token baru pertama kali diperoleh pada waktu pemuatan halaman, atau kemudian dengan memicu panggilan ke requestAccessToken() melalui gestur pengguna seperti penekanan tombol.

Menggunakan REST dan CORS dengan Google API

Token akses dapat digunakan untuk membuat permintaan terautentikasi ke Google API menggunakan REST dan CORS. Hal ini memungkinkan pengguna untuk login, memberikan izin, Google untuk menerbitkan token akses, dan situs Anda untuk menggunakan data pengguna.

Dalam contoh ini, lihat acara kalender mendatang pengguna yang login menggunakan token akses yang ditampilkan oleh tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

Lihat Cara menggunakan CORS untuk mengakses Google API untuk mengetahui informasi selengkapnya.

Bagian berikutnya membahas cara mengintegrasikan dengan API yang lebih kompleks dengan mudah.

Menggunakan library JavaScript Google API

Klien token berfungsi dengan Library Klien Google API untuk JavaScript. Lihat cuplikan kode di bawah.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

Akhir masa berlaku token

Secara desain, token akses memiliki masa berlaku yang singkat. Jika masa berlaku token akses berakhir sebelum akhir sesi pengguna, dapatkan token baru dengan memanggil requestAccessToken() dari peristiwa yang didorong pengguna seperti penekanan tombol.

Panggil metode google.accounts.oauth2.revoke untuk menghapus izin pengguna dan akses ke resource untuk semua cakupan yang diberikan ke aplikasi Anda. Token akses yang valid diperlukan untuk mencabut izin ini:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });