Menggunakan model token

Library JavaScript google.accounts.oauth2 membantu Anda meminta izin pengguna dan mendapatkan token akses untuk bekerja dengan data pengguna. API ini didasarkan pada alur pemberian implisit OAuth 2.0 dan didesain 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 pemilih akun, login, dan izin berbasis web milik Google, serta server OAuth akan mengeluarkan dan menampilkan token akses ke aplikasi web Anda.

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

Sebaiknya Anda mengikuti pendekatan yang diuraikan di sini, bukan teknik yang dicakup oleh panduan OAuth 2.0 untuk Aplikasi Web Sisi Klien yang lebih 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 client ID aplikasi web Anda. Jika ingin, 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 akan meminta pengguna untuk:

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

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

Selanjutnya, Google akan menampilkan TokenResponse yang berisi token akses dan daftar cakupan yang telah diberi akses oleh pengguna, atau error, ke pengendali callback Anda.

Pengguna dapat menutup pemilih akun atau jendela login. Dalam hal ini, fungsi callback Anda tidak akan dipanggil.

Desain dan pengalaman pengguna untuk aplikasi Anda harus diterapkan hanya setelah peninjauan menyeluruh terhadap Kebijakan OAuth 2.0 Google. Kebijakan ini mencakup pengelolaan beberapa cakupan, waktu 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 berbagi resource individual yang diminta oleh aplikasi Anda, yang dikenal sebagai izin terperinci.

Selama proses ini, Google akan meminta izin pengguna, mencantumkan setiap cakupan yang diminta, pengguna memilih resource yang akan dibagikan dengan aplikasi Anda, dan terakhir, Google memanggil fungsi callback Anda untuk menampilkan token Akses dan cakupan yang disetujui pengguna. Aplikasi Anda kemudian akan menangani berbagai hasil yang mungkin dengan aman menggunakan izin terperinci.

Otorisasi inkremental

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

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

Kedua skenario ini disajikan untuk menggambarkan pertimbangan desain dan metodologi, tetapi tidak dimaksudkan sebagai rekomendasi yang komprehensif tentang cara memberikan izin ke aplikasi Anda. Aplikasi sebenarnya dapat menggunakan variasi atau kombinasi teknik ini.

Ajax

Tambahkan dukungan untuk otorisasi inkremental ke aplikasi Anda dengan membuat beberapa panggilan ke requestAccessToken() dan menggunakan parameter scope objek OverridableTokenClientConfig untuk meminta masing-masing cakupan 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
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

Tampilkan dokumen terbaru

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

Acara mendatang

Tampilkan info kalender

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

Tampilkan 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 hanya untuk meminta cakupan yang diperlukan untuk memuat halaman, mengurangi kompleksitas, dan tidak perlu melakukan beberapa panggilan untuk 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 memperoleh token akses dengan memanggil initTokenClient() dan requestAccessToken() pada waktu pemuatan. Dalam skenario ini, setiap halaman web digunakan untuk memisahkan fungsi dan resource pengguna dengan jelas menurut cakupan. Dalam situasi dunia nyata, halaman individu dapat meminta beberapa cakupan terkait.

Izin terperinci

Izin terperinci ditangani dengan cara yang sama dalam semua skenario; setelah requestAccessToken() memanggil fungsi callback 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
        ...
      }
    }
  },
});

Hibah yang sebelumnya diterima dari sesi atau permintaan sebelumnya juga akan disertakan dalam respons. Data izin pengguna dikelola per pengguna dan Client-ID, dan disimpan 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 dalam objek konfigurasi Klien Token.

Bekerja dengan token

Dalam model Token, token akses tidak disimpan oleh OS atau browser, sebagai gantinya token baru akan diperoleh terlebih dahulu pada waktu pemuatan halaman, atau dengan memicu panggilan ke requestAccessToken() melalui gestur pengguna seperti menekan tombol.

Menggunakan REST dan CORS dengan Google API

Token akses dapat digunakan untuk membuat permintaan yang diautentikasi ke Google API menggunakan REST dan CORS. Hal ini memungkinkan pengguna untuk login, memberikan izin, dan Google akan menerbitkan token akses dan situs Anda agar dapat 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 mudah berintegrasi dengan API yang lebih kompleks.

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

Masa berlaku token

Token desain memiliki masa berlaku yang singkat. Jika masa berlaku token akses berakhir sebelum akhir sesi pengguna, dapatkan token baru dengan memanggil requestAccessToken() dari peristiwa yang dipicu 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');