OAuth 2.0 untuk Aplikasi Web Sisi Klien

Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses Google API dari aplikasi web JavaScript. OAuth 2.0 memungkinkan pengguna untuk berbagi data tertentu dengan aplikasi sambil menjaga nama pengguna, kata sandi, dan informasi lainnya tetap pribadi. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna untuk menyimpan file di Google Drive mereka.

2.0 Aliran OAuth ini disebut aliran hibah implisit. Ini dirancang untuk aplikasi yang mengakses API hanya saat pengguna hadir di aplikasi. Aplikasi ini tidak dapat menyimpan informasi rahasia.

Dalam alur ini, aplikasi Anda membuka URL Google yang menggunakan parameter kueri untuk mengidentifikasi aplikasi Anda dan jenis akses API yang diperlukan aplikasi. Anda dapat membuka URL di jendela browser saat ini atau munculan. Pengguna dapat mengautentikasi dengan Google dan memberikan izin yang diminta. Google kemudian mengarahkan pengguna kembali ke aplikasi Anda. Pengalihan menyertakan token akses, yang diverifikasi aplikasi Anda dan kemudian digunakan untuk membuat permintaan API.

Prasyarat

Aktifkan API untuk proyek Anda

Setiap aplikasi yang memanggil Google API perlu mengaktifkan mereka API di API Console.

Untuk mengaktifkan API untuk proyek Anda:

  1. Open the API Library di Google API Console.
  2. If prompted, select a project, or create a new one.
  3. The API Library daftar semua API yang tersedia, dikelompokkan berdasarkan produk keluarga dan popularitas. Jika API Anda ingin mengaktifkan tidak terlihat dalam daftar, penggunaan pencarian untuk menemukannya, atau klik Lihat Semua dalam keluarga produk itu milik.
  4. Pilih API Anda ingin mengaktifkan, kemudian klik tombol Enable.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Buat kredensial otorisasi

Aplikasi apa pun yang menggunakan OAuth 2.0 untuk mengakses Google API harus memiliki kredensial otorisasi yang mengidentifikasi aplikasi ke server OAuth 2.0 Google. Langkah-langkah berikut menjelaskan cara membuat kredensial untuk proyek Anda. Aplikasi Anda kemudian dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk proyek tersebut.

  1. Go to the Credentials page.
  2. Klik Buat kredensial> OAuth ID klien.
  3. Pilih jenis aplikasi aplikasi Web.
  4. Lengkapi formulir. Aplikasi yang menggunakan JavaScript untuk membuat berwenang asal JavaScript Google permintaan API harus sebutkan berwenang. Asal mengidentifikasi domain tempat aplikasi Anda dapat mengirim permintaan ke server OAuth 2.0. Asal-usul ini harus mematuhi aturan validasi Google .

Identifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan persetujuan pengguna.

Sebelum Anda mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan yang memerlukan izin untuk diakses oleh aplikasi Anda.

The OAuth 2.0 Cakupan API dokumen berisi daftar lengkap lingkup yang mungkin Anda gunakan untuk mengakses Google API.

Mendapatkan token akses OAuth 2.0

Langkah-langkah berikut menunjukkan bagaimana aplikasi Anda berinteraksi dengan server OAuth 2.0 Google untuk mendapatkan persetujuan pengguna untuk melakukan permintaan API atas nama pengguna. Aplikasi Anda harus memiliki persetujuan tersebut sebelum dapat menjalankan permintaan Google API yang memerlukan otorisasi pengguna.

Langkah 1: Konfigurasikan objek klien

Jika Anda menggunakan klien perpustakaan Google API untuk JavaScript untuk menangani aliran OAuth 2.0, langkah pertama Anda adalah untuk mengkonfigurasi gapi.auth2 dan gapi.client objek. Objek ini memungkinkan aplikasi Anda untuk mendapatkan otorisasi pengguna dan membuat permintaan API yang diotorisasi.

Objek klien mengidentifikasi cakupan yang diminta izin untuk diakses oleh aplikasi Anda. Nilai-nilai ini menginformasikan layar persetujuan yang ditampilkan Google kepada pengguna.

Pustaka Klien JS

Pustaka klien JavaScript menyederhanakan banyak aspek dari proses otorisasi:

  1. Ini membuat URL pengalihan untuk server otorisasi Google dan menyediakan metode untuk mengarahkan pengguna ke URL itu.
  2. Ini menangani pengalihan dari server itu kembali ke aplikasi Anda.
  3. Ini memvalidasi token akses yang dikembalikan oleh server otorisasi.
  4. Ini menyimpan token akses yang dikirim oleh server otorisasi ke aplikasi Anda dan mengambilnya ketika aplikasi Anda selanjutnya membuat panggilan API yang diotorisasi.

Potongan kode di bawah ini adalah kutipan dari contoh lengkap ditampilkan nanti dalam dokumen ini. Kode ini menginisialisasi gapi.client objek, yang aplikasi Anda kemudian akan digunakan untuk membuat panggilan API. Ketika objek yang dibuat, gapi.auth2 objek, yang menggunakan aplikasi Anda untuk memeriksa dan memantau status otorisasi pengguna, juga diinisialisasi.

Panggilan untuk gapi.client.init menentukan bidang-bidang berikut:

  • The apiKey dan clientId nilai-nilai menentukan kredensial otorisasi aplikasi Anda. Sebagaimana dibahas dalam kredensial otorisasi menciptakan bagian, nilai-nilai ini dapat diperoleh di API Console. Perhatikan bahwa clientId diperlukan jika aplikasi Anda membuat permintaan API yang berwenang. Aplikasi yang hanya membuat permintaan yang tidak sah dapat saja menentukan kunci API.
  • The scope bidang menetapkan daftar dipisahkan oleh spasi akses scopes bersesuaian bahwa dengan sumber daya bahwa aplikasi Anda bisa mengakses atas nama pengguna. Nilai-nilai ini menginformasikan layar persetujuan yang ditampilkan Google kepada pengguna.

    Kami menyarankan aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks bila memungkinkan. Dengan meminta akses ke data pengguna dalam konteks, melalui otorisasi tambahan , Anda membantu pengguna untuk lebih mudah memahami mengapa aplikasi Anda membutuhkan akses itu meminta.

  • The discoveryDocs lapangan mengidentifikasi daftar dokumen API Penemuan yang menggunakan aplikasi Anda. Dokumen Discovery menjelaskan permukaan API, termasuk skema sumber dayanya, dan pustaka klien JavaScript menggunakan informasi tersebut untuk menghasilkan metode yang dapat digunakan aplikasi. Dalam contoh ini, kode mengambil dokumen penemuan untuk versi 3 Google Drive API.

Setelah gapi.client.init Rampungkan panggilan, kode set GoogleAuth variabel untuk mengidentifikasi objek Google Auth. Terakhir, kode menyetel pemroses yang memanggil fungsi saat status masuk pengguna berubah. (Fungsi itu tidak ditentukan dalam cuplikan.)

var GoogleAuth; // Google Auth object.
function initClient() {
  gapi.client.init({
      'apiKey': 'YOUR_API_KEY',
      'clientId': 'YOUR_CLIENT_ID',
      'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly',
      'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest']
  }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);
  });
}

Titik Akhir OAuth 2.0

Jika Anda mengakses endpoint OAuth 2.0 secara langsung, Anda dapat melanjutkan ke langkah berikutnya.

Langkah 2: Arahkan ulang ke server OAuth 2.0 Google

Untuk meminta izin mengakses data pengguna, alihkan pengguna ke server OAuth 2.0 Google.

Pustaka Klien JS

Memanggil GoogleAuth.signIn() metode untuk mengarahkan pengguna ke server otorisasi Google.

GoogleAuth.signIn();

Dalam prakteknya, aplikasi Anda mungkin menetapkan nilai Boolean untuk menentukan apakah akan memanggil signIn() metode sebelum mencoba untuk melakukan panggilan API.

Cuplikan kode di bawah ini menunjukkan bagaimana Anda akan memulai alur otorisasi pengguna. Perhatikan poin-poin berikut tentang cuplikan:

  • The GoogleAuth objek direferensikan dalam kode adalah sama dengan variabel global didefinisikan dalam potongan kode di langkah 1 .

  • The updateSigninStatus fungsi adalah pendengar yang mendengarkan untuk perubahan status otorisasi pengguna. Perannya sebagai pendengar juga didefinisikan dalam potongan kode pada langkah 1:
    GoogleAuth.isSignedIn.listen(updateSigninStatus);
  • Cuplikan mendefinisikan dua variabel global tambahan:

    • isAuthorized adalah variabel Boolean yang menunjukkan apakah pengguna sudah masuk. Nilai ini dapat diatur ketika beban aplikasi dan diperbarui jika pengguna masuk atau keluar dari aplikasi.

      Dalam potongan ini, para sendAuthorizedApiRequest pemeriksaan fungsi nilai variabel untuk menentukan apakah aplikasi harus mencoba permintaan API yang membutuhkan otorisasi atau pengguna prompt untuk mengotorisasi aplikasi.

    • currentApiRequest adalah obyek yang menyimpan rincian tentang permintaan API terakhir bahwa pengguna dicoba. Nilai objek diatur ketika aplikasi panggilan sendAuthorizedApiRequest fungsi.

      Jika pengguna telah mengotorisasi aplikasi, permintaan akan segera dieksekusi. Jika tidak, fungsi pengalihan pengguna untuk masuk. Setelah pengguna masuk, yang updateSignInStatus fungsi panggilan sendAuthorizedApiRequest , melewati dalam permintaan yang sama yang berusaha sebelum aliran otorisasi mulai.

var isAuthorized;
var currentApiRequest;

/**
 * Store the request details. Then check to determine whether the user
 * has authorized the application.
 *   - If the user has granted access, make the API request.
 *   - If the user has not granted access, initiate the sign-in flow.
 */
function sendAuthorizedApiRequest(requestDetails) {
  currentApiRequest = requestDetails;
  if (isAuthorized) {
    // Make API request
    // gapi.client.request(requestDetails)

    // Reset currentApiRequest variable.
    currentApiRequest = {};
  } else {
    GoogleAuth.signIn();
  }
}

/**
 * Listener called when user completes auth flow. If the currentApiRequest
 * variable is set, then the user was prompted to authorize the application
 * before the request executed. In that case, proceed with that API request.
 */
function updateSigninStatus(isSignedIn) {
  if (isSignedIn) {
    isAuthorized = true;
    if (currentApiRequest) {
      sendAuthorizedApiRequest(currentApiRequest);
    }
  } else {
    isAuthorized = false;
  }
}

Titik Akhir OAuth 2.0

Menghasilkan URL untuk mengakses permintaan dari OAuth 2.0 endpoint Google di https://accounts.google.com/o/oauth2/v2/auth . Titik akhir ini dapat diakses melalui HTTPS; koneksi HTTP biasa ditolak.

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

Parameter
client_id Yg dibutuhkan

ID klien untuk aplikasi Anda. Anda dapat menemukan nilai ini di API ConsoleCredentials page.

redirect_uri Yg dibutuhkan

Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI redirect berwenang untuk OAuth 2.0 klien, yang Anda dikonfigurasi dalam klien Anda API ConsoleCredentials page. Jika nilai ini tidak cocok dengan redirect URI yang berwenang untuk disediakan client_id Anda akan mendapatkan redirect_uri_mismatch error.

Perhatikan bahwa http atau https skema, kasus, dan trailing slash ( ' / ') semua harus pertandingan.

response_type Yg dibutuhkan

Aplikasi JavaScript perlu mengatur nilai parameter untuk token . Nilai ini menginstruksikan Otorisasi Server Google untuk mengembalikan Access Token sebagai name=value pasangan di identifier fragmen dari URI ( # ) yang pengguna diarahkan setelah menyelesaikan proses otorisasi.

scope Yg dibutuhkan

Daftar cakupan yang dibatasi spasi yang mengidentifikasi sumber daya yang dapat diakses aplikasi Anda atas nama pengguna. Nilai-nilai ini menginformasikan layar persetujuan yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan persetujuan pengguna.

Kami menyarankan aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks bila memungkinkan. Dengan meminta akses ke data pengguna dalam konteks, melalui otorisasi tambahan , Anda membantu pengguna untuk lebih mudah memahami mengapa aplikasi Anda membutuhkan akses itu meminta.

state Direkomendasikan

Menentukan nilai string apa pun yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi. Server mengembalikan nilai yang tepat yang Anda kirim sebagai name=value pasangan di identifier URL fragmen ( # ) dari redirect_uri setelah persetujuan pengguna atau menolak permintaan akses aplikasi Anda.

Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke sumber daya yang benar di aplikasi Anda, mengirim nonces, dan mengurangi pemalsuan permintaan lintas situs. Karena Anda redirect_uri bisa ditebak, menggunakan state nilai dapat meningkatkan jaminan Anda bahwa koneksi masuk adalah hasil dari permintaan otentikasi. Jika Anda membuat string acak atau menyandikan hash cookie atau nilai lain yang menangkap status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, memberikan perlindungan terhadap serangan seperti lintas situs meminta pemalsuan. Lihat OpenID Connect dokumentasi untuk contoh bagaimana untuk membuat dan mengkonfirmasi state tanda.

include_granted_scopes Opsional

Memungkinkan aplikasi menggunakan otorisasi tambahan untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai ini parameter untuk true dan permintaan otorisasi dikabulkan, maka token akses baru juga akan mencakup lingkup yang pengguna sebelumnya yang diberikan akses aplikasi. Lihat otorisasi tambahan bagian untuk contoh.

login_hint Opsional

Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Google Authentication. Server menggunakan petunjuk untuk menyederhanakan alur login dengan mengisi kolom email di formulir login atau dengan memilih sesi multi-login yang sesuai.

Mengatur nilai parameter ke alamat email atau sub identifier, yang setara dengan Google ID pengguna.

prompt Opsional

Daftar permintaan yang dibatasi spasi dan peka huruf besar-kecil untuk menampilkan pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan diminta saat pertama kali proyek Anda meminta akses. Lihat Mendorong ulang consent untuk informasi lebih lanjut.

Nilai yang mungkin adalah:

none Jangan tampilkan layar otentikasi atau persetujuan apa pun. Tidak boleh ditentukan dengan nilai lain.
consent Minta persetujuan pengguna.
select_account Minta pengguna untuk memilih akun.

Contoh pengalihan ke server otorisasi Google

Contoh URL ditampilkan di bawah, dengan jeda baris dan spasi agar mudah dibaca.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Setelah Anda membuat URL permintaan, arahkan ulang pengguna ke sana.

Kode sampel JavaScript

Cuplikan JavaScript berikut menunjukkan cara memulai alur otorisasi dalam JavaScript tanpa menggunakan Pustaka Klien Google API untuk JavaScript. Karena titik akhir OAuth 2.0 ini tidak mendukung Cross-Origin Resource Sharing (CORS), cuplikan membuat formulir yang membuka permintaan ke titik akhir 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/drive.metadata.readonly',
                '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();
}

Langkah 3: Google meminta persetujuan pengguna

Pada langkah ini, pengguna memutuskan apakah akan memberikan aplikasi Anda akses yang diminta. Pada tahap ini, Google menampilkan jendela persetujuan yang menunjukkan nama aplikasi Anda dan layanan Google API yang meminta izin untuk diakses dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Pengguna kemudian dapat menyetujui untuk memberikan akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan tersebut.

Aplikasi Anda tidak perlu melakukan apa pun pada tahap ini karena menunggu respons dari server OAuth 2.0 Google yang menunjukkan apakah ada akses yang diberikan. Respon tersebut dijelaskan pada langkah berikut.

kesalahan

Permintaan ke titik akhir otorisasi OAuth 2.0 Google dapat menampilkan pesan kesalahan yang dihadapi pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode kesalahan umum dan resolusi yang disarankan tercantum di bawah ini.

admin_policy_enforced

Akun Google tidak dapat mengotorisasi satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace mereka. Lihat Google Workspace Admin artikel bantuan Control yang pihak ketiga & aplikasi internal mengakses data Google Workspace untuk informasi lebih lanjut tentang bagaimana administrator dapat membatasi akses ke semua lingkup atau cakupan sensitif dan dibatasi sampai akses secara eksplisit diberikan kepada ID OAuth klien Anda.

disallowed_useragent

Otorisasi endpoint ditampilkan dalam sebuah tertanam user-agent dianulir oleh Google OAuth 2.0 Kebijakan .

Android

Pengembang Android mungkin menemukan pesan kesalahan ini saat membuka permintaan otorisasi diandroid.webkit.WebView . Pengembang malah harus menggunakan perpustakaan Android seperti Google Sign-In untuk Android atau OpenID Foundation AppAuth untuk Android .

Pengembang web mungkin mengalami kesalahan ini saat aplikasi Android membuka tautan web umum di agen pengguna yang disematkan dan pengguna menavigasi ke titik akhir otorisasi OAuth 2.0 Google dari situs Anda. Pengembang harus memungkinkan link umum untuk membuka di link standar handler dari sistem operasi, yang meliputi Android App Links penangan atau aplikasi browser default. The Android Kustom Tab perpustakaan juga merupakan pilihan yang didukung.

iOS

iOS dan MacOS pengembang mungkin mengalami kesalahan ini saat membuka permintaan otorisasi diWKWebView . Pengembang malah harus menggunakan iOS perpustakaan seperti Google Sign-In untuk iOS atau OpenID Foundation AppAuth untuk iOS .

Pengembang web mungkin mengalami kesalahan ini saat aplikasi iOS atau macOS membuka tautan web umum di agen pengguna yang disematkan dan pengguna menavigasi ke titik akhir otorisasi OAuth 2.0 Google dari situs Anda. Pengembang harus memungkinkan link umum untuk membuka di link standar handler dari sistem operasi, yang meliputi Universal Link penangan atau aplikasi browser default. TheSFSafariViewController perpustakaan juga merupakan pilihan yang didukung.

org_internal

ID klien OAuth dalam permintaan adalah bagian dari proyek membatasi akses ke Google Account di tertentu Cloud Organisasi Google . Untuk informasi lebih lanjut tentang opsi konfigurasi ini melihat jenis Pengguna bagian dalam Menyiapkan persetujuan OAuth layar bantuan artikel Anda.

origin_mismatch

Skema, domain, dan/atau port JavaScript yang berasal dari permintaan otorisasi mungkin tidak cocok dengan URI asal JavaScript resmi yang terdaftar untuk ID klien OAuth. Ulasan berwenang asal JavaScript di Google API ConsoleCredentials page.

redirect_uri_mismatch

The redirect_uri lulus dalam permintaan otorisasi tidak cocok dengan redirect berwenang URI untuk ID klien OAuth. Ulasan berwenang URI redirect di Google API Console Credentials page.

Skema, domain, dan/atau port JavaScript yang berasal dari permintaan otorisasi mungkin tidak cocok dengan URI asal JavaScript resmi yang terdaftar untuk ID klien OAuth. Ulasan berwenang asal JavaScript di Google API Console Credentials page.

Langkah 4: Tangani respons server OAuth 2.0

Pustaka Klien JS

Pustaka klien JavaScript menangani respons dari server otorisasi Google. Jika Anda menyetel listener untuk memantau perubahan dalam status masuk pengguna saat ini, fungsi tersebut akan dipanggil saat pengguna memberikan akses yang diminta ke aplikasi.

Titik Akhir OAuth 2.0

OAuth 2.0 server mengirimkan respon terhadap redirect_uri ditentukan dalam akses token permintaan Anda.

Jika pengguna menyetujui permintaan, maka responsnya berisi token akses. Jika pengguna tidak menyetujui permintaan, respons berisi pesan kesalahan. Token akses atau pesan kesalahan dikembalikan pada fragmen hash dari 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 access_token parameter, fragmen string yang juga berisi token_type parameter, yang selalu diatur ke Bearer , dan expires_in parameter, yang menentukan masa token, dalam hitungan detik. Jika state parameter yang ditentukan dalam token akses permintaan, nilainya juga termasuk dalam respon.

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

Contoh respons server OAuth 2.0

Anda dapat menguji alur ini dengan mengeklik 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//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Setelah menyelesaikan OAuth 2.0 aliran, Anda akan diarahkan ke http://localhost/oauth2callback . URL yang akan menghasilkan 404 NOT FOUND kesalahan kecuali mesin lokal anda terjadi untuk melayani file di alamat itu. Langkah berikutnya memberikan detail lebih lanjut tentang informasi yang dikembalikan dalam URI saat pengguna diarahkan kembali ke aplikasi Anda.

Memanggil Google API

Pustaka Klien JS

Setelah aplikasi Anda mendapatkan token akses, Anda dapat menggunakan pustaka klien JavaScript untuk membuat permintaan API atas nama pengguna. Pustaka klien mengelola token akses untuk Anda, dan Anda tidak perlu melakukan sesuatu yang khusus untuk mengirimkannya dalam permintaan.

Pustaka klien mendukung dua cara untuk memanggil metode API. Jika Anda telah memuat dokumen penemuan, API akan menentukan fungsi khusus metode untuk Anda. Anda juga dapat menggunakan gapi.client.request fungsi untuk memanggil metode API. Berikut dua potongan menunjukkan pilihan ini untuk Drive API about.get metode.

// Example 1: Use method-specific function
var request = gapi.client.drive.about.get({'fields': 'user'});

// Execute the API request.
request.execute(function(response) {
  console.log(response);
});


// Example 2: Use gapi.client.request(args) function
var request = gapi.client.request({
  'method': 'GET',
  'path': '/drive/v3/about',
  'params': {'fields': 'user'}
});
// Execute the API request.
request.execute(function(response) {
  console.log(response);
});

Titik Akhir 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 melakukan hal ini, termasuk akses token permintaan untuk API dengan termasuk salah seorang access_token parameter permintaan atau Authorization header HTTP Bearer nilai. Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam kebanyakan kasus, Anda dapat menggunakan perpustakaan klien untuk mengatur panggilan Anda ke Google API (misalnya, ketika memanggil API drive Files ).

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

Contoh HTTP GET

Panggilan untuk drive.files endpoint (API drive Files) dengan menggunakan Authorization: Bearer HTTP header yang mungkin terlihat seperti berikut ini. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl contoh

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Atau, sebagai alternatif, opsi parameter string kueri:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Kode sampel JavaScript

Cuplikan kode di bawah ini menunjukkan cara menggunakan CORS (Cross-origin resource sharing) untuk mengirim permintaan ke Google API. Contoh ini tidak menggunakan Pustaka Klien Google API untuk JavaScript. Namun, bahkan jika Anda tidak menggunakan perpustakaan klien, CORS mendukung panduan dalam dokumentasi bahwa perpustakaan kemungkinan akan membantu Anda untuk lebih memahami permintaan ini.

Dalam potongan kode ini, access_token variabel merupakan tanda Anda telah mendapatkan untuk membuat permintaan API atas nama pengguna yang berwenang ini. The contoh lengkap menunjukkan bagaimana untuk menyimpan token di penyimpanan lokal browser dan mengambilnya ketika membuat permintaan API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

Contoh lengkap

Pustaka Klien JS

Contoh kode demo

Bagian ini berisi demo kerja contoh kode yang berikut untuk menunjukkan bagaimana kode berperilaku dalam aplikasi yang sebenarnya. Setelah Anda mengotorisasi aplikasi, maka akan tercantum di antara aplikasi yang terhubung ke Akun Google Anda . Aplikasi ini bernama OAuth 2.0 Demo untuk Google API Docs. Demikian pula, jika Anda mencabut akses dan menyegarkan halaman itu, aplikasi itu tidak akan lagi terdaftar.

Perhatikan bahwa aplikasi ini meminta akses ke https://www.googleapis.com/auth/drive.metadata.readonly lingkup. Akses diminta hanya untuk mendemonstrasikan cara memulai alur OAuth 2.0 dalam aplikasi JavaScript. Aplikasi ini tidak membuat permintaan API apa pun.

Kode sampel JavaScript

Seperti yang ditunjukkan di atas, contoh kode ini adalah untuk laman (aplikasi) yang memuat Pustaka Klien Google API untuk JavaScript dan memulai alur OAuth 2.0. Halaman tersebut menampilkan:

  • Satu tombol yang memungkinkan pengguna masuk ke aplikasi. Jika pengguna belum pernah mengotorisasi aplikasi, maka aplikasi akan meluncurkan alur OAuth 2.0.
  • Dua tombol yang memungkinkan pengguna untuk keluar dari aplikasi atau mencabut akses yang sebelumnya diberikan ke aplikasi. Jika Anda keluar dari aplikasi, Anda belum mencabut akses yang diberikan ke aplikasi tersebut. Anda harus masuk lagi sebelum aplikasi dapat membuat permintaan resmi lainnya atas nama Anda, tetapi Anda tidak perlu memberikan akses lagi saat berikutnya Anda menggunakan aplikasi. Namun, jika Anda mencabut akses, Anda perlu memberikan akses lagi.

Anda juga dapat mencabut akses ke aplikasi melalui Izin halaman untuk Akun Google Anda. Aplikasi ini terdaftar sebagai OAuth 2.0 Demo untuk Google API Docs.

<script>
  var GoogleAuth;
  var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
  function handleClientLoad() {
    // Load the API's client and auth2 modules.
    // Call the initClient function after the modules load.
    gapi.load('client:auth2', initClient);
  }

  function initClient() {
    // In practice, your app can retrieve one or more discovery documents.
    var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest';

    // Initialize the gapi.client object, which app uses to make API requests.
    // Get API key and client ID from API Console.
    // 'scope' field specifies space-delimited list of access scopes.
    gapi.client.init({
        'apiKey': 'YOUR_API_KEY',
        'clientId': 'YOUR_CLIENT_ID',
        'discoveryDocs': [discoveryUrl],
        'scope': SCOPE
    }).then(function () {
      GoogleAuth = gapi.auth2.getAuthInstance();

      // Listen for sign-in state changes.
      GoogleAuth.isSignedIn.listen(updateSigninStatus);

      // Handle initial sign-in state. (Determine if user is already signed in.)
      var user = GoogleAuth.currentUser.get();
      setSigninStatus();

      // Call handleAuthClick function when user clicks on
      //      "Sign In/Authorize" button.
      $('#sign-in-or-out-button').click(function() {
        handleAuthClick();
      });
      $('#revoke-access-button').click(function() {
        revokeAccess();
      });
    });
  }

  function handleAuthClick() {
    if (GoogleAuth.isSignedIn.get()) {
      // User is authorized and has clicked "Sign out" button.
      GoogleAuth.signOut();
    } else {
      // User is not signed in. Start Google auth flow.
      GoogleAuth.signIn();
    }
  }

  function revokeAccess() {
    GoogleAuth.disconnect();
  }

  function setSigninStatus() {
    var user = GoogleAuth.currentUser.get();
    var isAuthorized = user.hasGrantedScopes(SCOPE);
    if (isAuthorized) {
      $('#sign-in-or-out-button').html('Sign out');
      $('#revoke-access-button').css('display', 'inline-block');
      $('#auth-status').html('You are currently signed in and have granted ' +
          'access to this app.');
    } else {
      $('#sign-in-or-out-button').html('Sign In/Authorize');
      $('#revoke-access-button').css('display', 'none');
      $('#auth-status').html('You have not authorized this app or you are ' +
          'signed out.');
    }
  }

  function updateSigninStatus() {
    setSigninStatus();
  }
</script>

<button id="sign-in-or-out-button"
        style="margin-left: 25px">Sign In/Authorize</button>
<button id="revoke-access-button"
        style="display: none; margin-left: 25px">Revoke access</button>

<div id="auth-status" style="display: inline; padding-left: 25px"></div><hr>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script async defer src="https://apis.google.com/js/api.js"
        onload="this.onload=function(){};handleClientLoad()"
        onreadystatechange="if (this.readyState === 'complete') this.onload()">
</script>

Titik Akhir OAuth 2.0

Contoh kode ini menunjukkan cara menyelesaikan alur OAuth 2.0 dalam JavaScript tanpa menggunakan Pustaka Klien Google API untuk JavaScript. Kode ini untuk halaman HTML yang menampilkan tombol untuk mencoba permintaan API. Jika Anda mengklik tombol, kode akan memeriksa untuk melihat apakah halaman telah menyimpan token akses API di penyimpanan lokal browser Anda. Jika demikian, itu mengeksekusi permintaan API. Jika tidak, ini akan memulai aliran OAuth 2.0.

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

  1. Ini mengarahkan pengguna ke Google OAuth 2.0 server, yang meminta akses ke https://www.googleapis.com/auth/drive.metadata.readonly lingkup.
  2. Setelah memberikan (atau menolak) akses ke satu atau lebih cakupan yang diminta, pengguna diarahkan ke halaman asli, yang mem-parsing token akses dari string pengenal fragmen.
  3. Halaman menggunakan token akses untuk membuat permintaan sampel API.

    Permintaan API panggilan Drive API about.get metode untuk mengambil informasi tentang akun Google Drive pengguna yang berwenang ini.

  4. Jika permintaan berhasil dijalankan, respons API dicatat di konsol debug browser.

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

Untuk menjalankan kode ini secara lokal, Anda perlu nilai-nilai yang ditetapkan untuk YOUR_CLIENT_ID dan YOUR_REDIRECT_URI variabel yang sesuai dengan Anda kredensial otorisasi . The YOUR_REDIRECT_URI variabel harus ditetapkan ke URL yang sama di mana halaman yang disajikan. Nilai harus sama persis dengan salah satu URI redirect berwenang untuk OAuth 2.0 klien, yang Anda dikonfigurasi dalam API Console Credentials page. Jika nilai ini tidak cocok dengan URI resmi, Anda akan mendapatkan redirect_uri_mismatch error. Proyek Anda juga harus telah diaktifkan API yang tepat untuk permintaan ini.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';
  var fragmentString = location.hash.substring(1);

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0) {
    localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
    if (params['state'] && params['state'] == 'try_sample_request') {
      trySampleRequest();
    }
  }

  // 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/drive/v3/about?fields=user&' +
          '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() {
    // 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/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  '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>

Aturan validasi asal JavaScript

Google menerapkan aturan validasi berikut ke asal JavaScript untuk membantu pengembang menjaga keamanan aplikasi mereka. Asal JavaScript Anda harus mematuhi aturan ini. Lihat RFC 3986 bagian 3 untuk definisi domain, host dan skema, disebutkan di bawah ini.

Aturan validasi
Skema

Asal JavaScript harus menggunakan skema HTTPS, bukan HTTP biasa. URI localhost (termasuk URI alamat IP localhost) dikecualikan dari aturan ini.

Tuan rumah

Host tidak boleh berupa alamat IP mentah. Alamat IP localhost dikecualikan dari aturan ini.

Domain
  • Tuan rumah TLDs ( Top Level Domain ) harus berasal dari daftar akhiran publik .
  • Domain host tidak bisa “googleusercontent.com” .
  • Asal JavaScript tidak dapat berisi URL shortener domain (misalnya goo.gl ) kecuali aplikasi memiliki domain.
  • Info Pengguna

    Asal JavaScript tidak boleh berisi subkomponen info pengguna.

    Jalur

    Asal JavaScript tidak boleh berisi komponen jalur.

    Pertanyaan

    Asal JavaScript tidak boleh berisi komponen kueri.

    Pecahan

    Asal JavaScript tidak boleh berisi komponen fragmen.

    karakter Asal JavaScript tidak boleh berisi karakter tertentu termasuk:
    • Karakter wildcard ( '*' )
    • Karakter ASCII yang tidak dapat dicetak
    • Penyandian persen tidak valid (pengkodean persen apa pun yang tidak mengikuti bentuk penyandian URL dari tanda persen diikuti oleh dua digit heksadesimal)
    • Karakter Null (karakter NULL encoded, misalnya, %00 , %C0%80 )

    Otorisasi tambahan

    Dalam protokol OAuth 2.0, aplikasi Anda meminta otorisasi untuk mengakses sumber daya, yang diidentifikasi berdasarkan cakupan. Ini dianggap sebagai praktik pengalaman pengguna terbaik untuk meminta otorisasi untuk sumber daya pada saat Anda membutuhkannya. Untuk mengaktifkan praktik itu, server otorisasi Google mendukung otorisasi tambahan. Fitur ini memungkinkan Anda meminta cakupan sesuai kebutuhan dan, jika pengguna memberikan izin untuk cakupan baru, mengembalikan kode otorisasi yang dapat ditukar dengan token yang berisi semua cakupan yang telah diberikan pengguna kepada proyek.

    Misalnya, aplikasi yang memungkinkan orang mengambil sampel trek musik dan membuat campuran mungkin memerlukan sedikit sumber daya pada waktu masuk, mungkin tidak lebih dari nama orang yang masuk. Namun, menyimpan campuran yang sudah selesai memerlukan akses ke Google Drive mereka. . Kebanyakan orang akan merasa wajar jika mereka hanya dimintai akses ke Google Drive mereka pada saat aplikasi benar-benar membutuhkannya.

    Dalam hal ini, tanda-waktu aplikasi mungkin meminta openid dan profile lingkup untuk melakukan dasar masuk, dan kemudian meminta https://www.googleapis.com/auth/drive.file lingkup pada saat permintaan pertama untuk menyimpan campuran.

    Aturan berikut berlaku untuk token akses yang diperoleh dari otorisasi tambahan:

    • Token dapat digunakan untuk mengakses sumber daya yang sesuai dengan cakupan mana pun yang digulirkan ke dalam otorisasi gabungan yang baru.
    • Bila Anda menggunakan refresh tanda untuk otorisasi gabungan untuk mendapatkan token akses, token akses mewakili otorisasi gabungan dan dapat digunakan untuk salah satu scope nilai-nilai termasuk dalam respon.
    • Otorisasi gabungan mencakup semua cakupan yang diberikan pengguna ke proyek API meskipun hibah diminta dari klien yang berbeda. Misalnya, jika pengguna memberikan akses ke satu cakupan menggunakan klien desktop aplikasi dan kemudian memberikan cakupan lain ke aplikasi yang sama melalui klien seluler, otorisasi gabungan akan mencakup kedua cakupan.
    • Jika Anda mencabut token yang mewakili otorisasi gabungan, akses ke semua cakupan otorisasi tersebut atas nama pengguna terkait akan dicabut secara bersamaan.

    Contoh kode di bawah ini menunjukkan cara menambahkan cakupan ke token akses yang ada. Pendekatan ini memungkinkan aplikasi Anda untuk menghindari keharusan mengelola beberapa token akses.

    Pustaka Klien JS

    Untuk menambahkan cakupan untuk token akses yang ada, sebut GoogleUser.grant(options) metode. The options keberatan mengidentifikasi lingkup tambahan yang Anda ingin memberikan akses.

    // Space-separated list of additional scope(s) you are requesting access to.
    // This code adds read-only access to the user's calendars via the Calendar API.
    var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly';
    
    // Retrieve the GoogleUser object for the current user.
    var GoogleUser = GoogleAuth.currentUser.get();
    GoogleUser.grant({'scope': NEW_SCOPES});

    Titik Akhir OAuth 2.0

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

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

    Cuplikan membandingkan cakupan yang token aksesnya 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, oauth2SignIn fungsi adalah sama dengan yang diberikan pada langkah 2 (dan yang disediakan kemudian dalam contoh lengkap ).

    var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
    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.
    }

    Mencabut token

    Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Seorang pengguna dapat mencabut akses dengan mengunjungi Account Settings . Lihat situs Hapus atau aplikasi bagian akses dari situs pihak ketiga & aplikasi dengan akses ke akun Anda dokumen dukungan untuk informasi lebih lanjut.

    Aplikasi juga dapat mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram penting dalam kasus di mana pengguna berhenti berlangganan, menghapus aplikasi, atau sumber daya API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan dapat menyertakan permintaan API untuk memastikan izin yang sebelumnya diberikan ke aplikasi dihapus.

    Pustaka Klien JS

    Pemrograman mencabut token, panggilan GoogleAuth.disconnect() :

    GoogleAuth.disconnect();

    Titik Akhir OAuth 2.0

    Pemrograman mencabut token, aplikasi Anda membuat permintaan untuk https://oauth2.googleapis.com/revoke dan termasuk token sebagai parameter:

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

    The token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token will also be revoked.

    If the revocation is successfully processed, then the HTTP status code of the response is 200 . For error conditions, an HTTP status code 400 is returned along with an error code.

    The following JavaScript snippet shows how to revoke a token in JavaScript without using the Google APIs Client Library for JavaScript. Since the Google's OAuth 2.0 endpoint for revoking tokens does not support Cross-origin Resource Sharing (CORS), the code creates a form and submits the form to the endpoint rather than using the XMLHttpRequest() method to post the request.

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