Menggunakan OAuth 2.0 untuk Aplikasi Server Web

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Dokumen ini menjelaskan cara aplikasi server web menggunakan Library Klien Google API atau endpoint Google OAuth 2.0 untuk menerapkan otorisasi OAuth 2.0 guna mengakses Google API.

OAuth 2.0 memungkinkan pengguna berbagi data tertentu dengan aplikasi sambil menjaga nama pengguna, sandi, dan informasi lainnya tetap pribadi. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna guna menyimpan file di Google Drive.

Alur OAuth 2.0 ini khusus untuk otorisasi pengguna. Layanan ini didesain untuk aplikasi yang dapat menyimpan informasi rahasia dan mempertahankan status. Aplikasi server web yang diotorisasi dengan benar dapat mengakses API saat pengguna berinteraksi dengan aplikasi atau setelah pengguna keluar dari aplikasi.

Aplikasi server web sering kali juga menggunakan akun layanan untuk mengizinkan permintaan API, terutama saat memanggil Cloud API untuk mengakses data berbasis project, bukan data khusus pengguna. Aplikasi server web dapat menggunakan akun layanan bersama dengan otorisasi pengguna.

Library klien

Contoh khusus bahasa pada halaman ini menggunakan Library Klien Google API untuk menerapkan otorisasi OAuth 2.0. Untuk menjalankan contoh kode, Anda harus menginstal library klien untuk bahasa Anda terlebih dahulu.

Saat Anda menggunakan Library Klien Google API untuk menangani alur OAuth 2.0 aplikasi Anda, library klien akan melakukan banyak tindakan yang seharusnya dapat ditangani sendiri oleh aplikasi. Misalnya, hal ini menentukan kapan aplikasi dapat menggunakan atau memuat ulang token akses yang tersimpan, serta kapan aplikasi harus mendapatkan kembali izin. Library klien juga membuat URL alihan yang benar dan membantu menerapkan pengendali pengalihan yang menukar kode otorisasi untuk token akses.

Library Klien Google API untuk aplikasi sisi server tersedia untuk bahasa berikut:

Prasyarat

Mengaktifkan API untuk project Anda

Aplikasi apa pun yang memanggil Google API harus mengaktifkan API tersebut di API Console.

Untuk mengaktifkan API untuk project Anda:

  1. Open the API Library di Google API Console.
  2. If prompted, select a project, or create a new one.
  3. API Library mencantumkan semua API yang tersedia, yang dikelompokkan berdasarkan kelompok produk dan popularitas. Jika API yang ingin Anda aktifkan tidak terlihat dalam daftar, gunakan penelusuran untuk mencarinya, atau klik Lihat Semua dalam kategori produknya.
  4. Pilih API yang ingin Anda aktifkan, lalu klik tombol Aktifkan.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Membuat kredensial otorisasi

Setiap aplikasi 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 project Anda. Selanjutnya, aplikasi Anda dapat menggunakan kredensial tersebut untuk mengakses API yang telah Anda aktifkan untuk project tersebut.

  1. Go to the Credentials page.
  2. Klik Create credentials > OAuth client ID.
  3. Pilih jenis aplikasi Aplikasi web.
  4. Isi formulir lalu klik Create. Aplikasi yang menggunakan bahasa dan framework seperti PHP, Java, Python, Ruby, dan .NET harus menentukan URI pengalihan yang diizinkan. URI pengalihan adalah endpoint yang dapat dikirimi respons oleh server OAuth 2.0. Endpoint ini harus mematuhi aturan validasi Google.

    Untuk pengujian, Anda dapat menentukan URI yang merujuk ke mesin lokal, seperti http://localhost:8080. Dengan mempertimbangkan hal tersebut, harap diperhatikan bahwa semua contoh dalam dokumen ini menggunakan http://localhost:8080 sebagai URI pengalihan.

    Sebaiknya desain endpoint autentikasi aplikasi Anda agar aplikasi tidak menampilkan kode otorisasi ke resource lain pada halaman.

Setelah membuat kredensial, download file client_secret.json dari API Console. Simpan file dengan aman di lokasi yang hanya dapat diakses oleh aplikasi Anda.

Mengidentifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Oleh karena itu, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.

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

Sebaiknya aplikasi Anda juga meminta akses ke cakupan otorisasi melalui proses otorisasi inkremental, yang memungkinkan aplikasi Anda meminta akses ke data pengguna dalam konteks. Praktik terbaik ini membantu pengguna lebih mudah memahami mengapa aplikasi Anda memerlukan akses yang diminta.

Dokumen Cakupan API OAuth 2.0 berisi daftar lengkap cakupan yang mungkin Anda gunakan untuk mengakses Google API.

Persyaratan khusus bahasa

Untuk menjalankan contoh kode dalam dokumen ini, Anda memerlukan akun Google, akses ke Internet, dan browser web. Jika Anda menggunakan salah satu library klien API, lihat juga persyaratan spesifik per bahasa di bawah.

PHP

Untuk menjalankan contoh kode PHP dalam dokumen ini, Anda memerlukan:

  • PHP 5.6 atau yang lebih tinggi dengan antarmuka command line (CLI) dan ekstensi JSON yang diinstal.
  • Alat pengelolaan dependensi Composer.

  • Library Klien Google API untuk PHP:

    composer require google/apiclient:^2.10

Python

Untuk menjalankan contoh kode Python di dokumen ini, Anda memerlukan:

  • Python 2.6 atau yang lebih baru
  • Alat pengelolaan paket pip.
  • Library Klien Google API untuk Python: 
    pip install --upgrade google-api-python-client
  • google-auth, google-auth-oauthlib, dan google-auth-httplib2 untuk otorisasi pengguna. 
    pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
  • Framework aplikasi web Flask Python. 
    pip install --upgrade flask
  • Library HTTP requests. 
    pip install --upgrade requests

Ruby

Untuk menjalankan contoh kode Ruby di dokumen ini, Anda akan memerlukan:

  • Ruby 2.2.2 atau yang lebih baru

  • Library Klien Google API untuk Ruby:

    gem install google-api-client

  • Framework aplikasi web Sinatra Ruby.

    gem install sinatra

Node.js

Untuk menjalankan contoh kode Node.js dalam dokumen ini, Anda perlu:

  • LTS pemeliharaan, LTS aktif, atau rilis Node.js saat ini.

  • Klien Node.js Google API:

    npm install googleapis

HTTP/REST

Anda tidak perlu menginstal library apa pun untuk dapat memanggil endpoint OAuth 2.0 secara langsung.

Mendapatkan token akses OAuth 2.0

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

Daftar di bawah ini meringkas langkah-langkah ini dengan cepat:

  1. Aplikasi Anda mengidentifikasi izin yang diperlukan.
  2. Aplikasi Anda mengalihkan pengguna ke Google beserta daftar izin yang diminta.
  3. Pengguna memutuskan apakah akan memberikan izin ke aplikasi Anda atau tidak.
  4. Aplikasi Anda akan mengetahui keputusan pengguna.
  5. Jika pengguna memberikan izin yang diminta, aplikasi Anda akan mengambil token yang diperlukan untuk membuat permintaan API atas nama pengguna.

Langkah 1: Tetapkan parameter otorisasi

Langkah pertama Anda adalah membuat permintaan otorisasi. Permintaan tersebut menetapkan parameter yang mengidentifikasi aplikasi Anda dan menentukan izin yang akan diminta pengguna untuk memberikannya ke aplikasi Anda.

  • Jika menggunakan library klien Google untuk autentikasi dan otorisasi OAuth 2.0, Anda harus membuat dan mengonfigurasi objek yang menentukan parameter ini.
  • Jika Anda memanggil endpoint Google OAuth 2.0 secara langsung, Anda akan membuat URL dan menetapkan parameter pada URL tersebut.

Tab di bawah menentukan parameter otorisasi yang didukung untuk aplikasi server web. Contoh khusus bahasa juga menunjukkan cara menggunakan library klien atau library otorisasi untuk mengonfigurasi objek yang menetapkan parameter tersebut.

PHP

Cuplikan kode di bawah membuat objek Google\Client(), yang menentukan parameter dalam permintaan otorisasi.

Objek tersebut menggunakan informasi dari file client_secret.json Anda untuk mengidentifikasi aplikasi Anda. (Lihat membuat kredensial otorisasi untuk mengetahui file tersebut lebih lanjut.) Objek ini juga mengidentifikasi cakupan yang diminta aplikasi Anda untuk mengakses dan URL ke endpoint autentikasi aplikasi Anda, yang akan menangani respons dari server OAuth 2.0 Google. Terakhir, kode tersebut menetapkan parameter access_type dan include_granted_scopes opsional.

Misalnya, kode ini meminta akses offline hanya baca ke Google Drive pengguna: 

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
// offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');
// Using "consent" ensures that your application always receives a refresh token.
// If you are not using offline access, you can omit this.
$client->setApprovalPrompt('consent');
$client->setIncludeGrantedScopes(true);   // incremental auth

Permintaan tersebut menetapkan informasi berikut:

Parameter
client_id Wajib

Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Credentials page API Console.

Di PHP, panggil fungsi setAuthConfig untuk memuat kredensial otorisasi dari file client_secret.json.

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');
redirect_uri Wajib

Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di Credentials page API Consoleklien Anda. Jika nilai ini tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client_id yang disediakan, Anda akan mendapatkan error redirect_uri_mismatch.

Perhatikan bahwa skema, kasus, dan garis miring (http) / atau https harus cocok.

Untuk menetapkan nilai ini di PHP, panggil fungsi setRedirectUri. Perhatikan bahwa Anda harus menentukan URI pengalihan yang valid untuk client_id yang disediakan.

$client->setRedirectUri('https://oauth2.example.com/code');
scope Wajib

Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menunjukkan layar izin yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.

Untuk menetapkan nilai ini di PHP, panggil fungsi addScope:

$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks jika memungkinkan. Dengan meminta akses ke data pengguna dalam konteks, melalui otorisasi inkremental, Anda membantu pengguna untuk lebih mudah memahami mengapa aplikasi Anda memerlukan akses yang diminta.
access_type Direkomendasikan

Menunjukkan apakah aplikasi Anda dapat me-refresh token akses saat pengguna tidak ada di browser. Parameter value yang valid adalah online, yang merupakan nilai default, dan offline.

Tetapkan nilai ke offline jika aplikasi perlu memperbarui token akses saat pengguna tidak ada di browser. Ini adalah metode untuk memperbarui token akses yang dijelaskan nanti dalam dokumen ini. Nilai ini memerintahkan server otorisasi Google untuk menampilkan token refresh dan token akses saat pertama kali aplikasi Anda menukar kode otorisasi dengan token.

Untuk menetapkan nilai ini di PHP, panggil fungsi setAccessType:

$client->setAccessType('offline');
state Direkomendasikan

Menentukan nilai string apa pun yang digunakan aplikasi untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi. Server menampilkan nilai persis yang Anda kirim sebagai pasangan name=value dalam komponen kueri URL (?) redirect_uri setelah pengguna menyetujui atau menolak permintaan akses aplikasi Anda.

Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar di aplikasi Anda, mengirim nonce, dan mengurangi pemalsuan permintaan lintas situs. Karena redirect_uri Anda dapat ditebak, menggunakan nilai state dapat meningkatkan jaminan bahwa koneksi masuk adalah hasil dari permintaan autentikasi. Jika membuat string acak atau mengenkode hash cookie atau nilai lain yang mengambil status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, yang memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs. Baca dokumentasi OpenID Connect untuk melihat contoh cara membuat dan mengonfirmasi token state.

Untuk menetapkan nilai ini di PHP, panggil fungsi setState:

$client->setState($sample_passthrough_value);
include_granted_scopes Opsional

Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke true dan permintaan otorisasi disetujui, token akses baru juga akan mencakup cakupan apa pun yang sebelumnya diberi akses aplikasi oleh pengguna. Lihat bagian otorisasi inkremental sebagai contoh.

Untuk menetapkan nilai ini di PHP, panggil fungsi setIncludeGrantedScopes:

$client->setIncludeGrantedScopes(true);
login_hint Opsional

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

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

Untuk menetapkan nilai ini di PHP, panggil fungsi setLoginHint:

$client->setLoginHint('None');
prompt Opsional

Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk menampilkan pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat pertama kali project Anda meminta akses. Lihat Meminta izin kembali untuk mengetahui informasi selengkapnya.

Untuk menetapkan nilai ini di PHP, panggil fungsi setApprovalPrompt:

$client->setApprovalPrompt('consent');

Nilai yang dimungkinkan adalah:

none Jangan tampilkan layar autentikasi atau izin. Tidak boleh ditentukan dengan nilai lain.
consent Minta izin pengguna.
select_account Minta pengguna memilih akun.

Python

Cuplikan kode berikut menggunakan modul google-auth-oauthlib.flow untuk membuat permintaan otorisasi.

Kode membuat objek Flow, yang mengidentifikasi aplikasi Anda menggunakan informasi dari file client_secret.json yang Anda download setelah membuat kredensial otorisasi. Objek tersebut juga mengidentifikasi cakupan yang diminta oleh aplikasi Anda untuk mengakses dan URL ke endpoint autentikasi aplikasi Anda, yang akan menangani respons dari server OAuth 2.0 Google. Terakhir, kode tersebut menetapkan parameter access_type dan include_granted_scopes opsional.

Misalnya, kode ini meminta akses offline hanya baca ke Google Drive pengguna: 

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Permintaan tersebut menetapkan informasi berikut:

Parameter
client_id Wajib

Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Credentials page API Console.

Dengan Python, panggil metode from_client_secrets_file untuk mengambil client ID dari file client_secret.json. (Anda juga dapat menggunakan metode from_client_config, yang meneruskan konfigurasi klien seperti yang awalnya muncul di file rahasia klien, tetapi tidak mengakses file tersebut.)

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])
redirect_uri Wajib

Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di Credentials page API Consoleklien Anda. Jika nilai ini tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client_id yang disediakan, Anda akan mendapatkan error redirect_uri_mismatch.

Perhatikan bahwa skema, kasus, dan garis miring (http) / atau https harus cocok.

Untuk menetapkan nilai ini dalam Python, tetapkan properti redirect_uri objek flow:

flow.redirect_uri = 'https://oauth2.example.com/code'
scope Wajib

Daftar cakupan yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menunjukkan layar izin yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.

Dalam Python, gunakan metode yang sama dengan yang Anda gunakan untuk menetapkan client_id untuk menentukan daftar cakupan. 

flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'])

Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks jika memungkinkan. Dengan meminta akses ke data pengguna dalam konteks, melalui otorisasi inkremental, Anda membantu pengguna untuk lebih mudah memahami mengapa aplikasi Anda memerlukan akses yang diminta.
access_type Direkomendasikan

Menunjukkan apakah aplikasi Anda dapat me-refresh token akses saat pengguna tidak ada di browser. Parameter value yang valid adalah online, yang merupakan nilai default, dan offline.

Tetapkan nilai ke offline jika aplikasi perlu memperbarui token akses saat pengguna tidak ada di browser. Ini adalah metode untuk memperbarui token akses yang dijelaskan nanti dalam dokumen ini. Nilai ini memerintahkan server otorisasi Google untuk menampilkan token refresh dan token akses saat pertama kali aplikasi Anda menukar kode otorisasi dengan token.

Di Python, tetapkan parameter access_type dengan menentukan access_type sebagai argumen kata kunci saat memanggil metode flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
state Direkomendasikan

Menentukan nilai string apa pun yang digunakan aplikasi untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi. Server menampilkan nilai persis yang Anda kirim sebagai pasangan name=value dalam komponen kueri URL (?) redirect_uri setelah pengguna menyetujui atau menolak permintaan akses aplikasi Anda.

Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar di aplikasi Anda, mengirim nonce, dan mengurangi pemalsuan permintaan lintas situs. Karena redirect_uri Anda dapat ditebak, menggunakan nilai state dapat meningkatkan jaminan bahwa koneksi masuk adalah hasil dari permintaan autentikasi. Jika membuat string acak atau mengenkode hash cookie atau nilai lain yang mengambil status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, yang memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs. Baca dokumentasi OpenID Connect untuk melihat contoh cara membuat dan mengonfirmasi token state.

Di Python, tetapkan parameter state dengan menentukan state sebagai argumen kata kunci saat memanggil metode flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    state=sample_passthrough_value,
    include_granted_scopes='true')
include_granted_scopes Opsional

Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke true dan permintaan otorisasi disetujui, token akses baru juga akan mencakup cakupan apa pun yang sebelumnya diberi akses aplikasi oleh pengguna. Lihat bagian otorisasi inkremental sebagai contoh.

Di Python, tetapkan parameter include_granted_scopes dengan menentukan include_granted_scopes sebagai argumen kata kunci saat memanggil metode flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true')
login_hint Opsional

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

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

Di Python, tetapkan parameter login_hint dengan menentukan login_hint sebagai argumen kata kunci saat memanggil metode flow.authorization_url:

authorization_url, state = flow.authorization_url(
    access_type='offline',
    login_hint='None',
    include_granted_scopes='true')
prompt Opsional

Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk menampilkan pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat pertama kali project Anda meminta akses. Lihat Meminta izin kembali untuk mengetahui informasi selengkapnya.

Di Python, tetapkan parameter prompt dengan menentukan prompt sebagai argumen kata kunci saat memanggil metode flow.authorization_url:

authorization_url, state = flow.authorization_url(
      access_type='offline',
      prompt='consent',
      include_granted_scopes='true')

Nilai yang dimungkinkan adalah:

none Jangan tampilkan layar autentikasi atau izin. Tidak boleh ditentukan dengan nilai lain.
consent Minta izin pengguna.
select_account Minta pengguna memilih akun.

Ruby

Gunakan file client_secrets.json yang Anda buat untuk mengonfigurasi objek klien di aplikasi Anda. Saat mengonfigurasi objek klien, Anda menentukan cakupan yang perlu diakses oleh aplikasi, beserta URL ke endpoint autentikasi aplikasi, yang akan menangani respons dari server OAuth 2.0.

Misalnya, kode ini meminta akses offline hanya baca ke Google Drive pengguna: 

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'

client_secrets = Google::APIClient::ClientSecrets.load
auth_client = client_secrets.to_authorization
auth_client.update!(
  :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
  :redirect_uri => 'http://www.example.com/oauth2callback',
  :additional_parameters => {
    "access_type" => "offline",         # offline access
    "include_granted_scopes" => "true"  # incremental auth
  }
)

Aplikasi Anda menggunakan objek klien untuk menjalankan operasi OAuth 2.0, seperti membuat URL permintaan otorisasi dan menerapkan token akses ke permintaan HTTP.

Node.js

Cuplikan kode di bawah membuat objek google.auth.OAuth2, yang menentukan parameter dalam permintaan otorisasi.

Objek tersebut menggunakan informasi dari file client_secret.json Anda untuk mengidentifikasi aplikasi Anda. Untuk meminta izin dari pengguna agar dapat mengambil token akses, Anda harus mengalihkan mereka ke halaman izin. Untuk membuat URL halaman izin:

const {google} = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

Catatan Penting - refresh_token hanya dikembalikan pada otorisasi pertama. Lihat detail selengkapnya di sini.

HTTP/REST

Endpoint OAuth 2.0 Google ada di https://accounts.google.com/o/oauth2/v2/auth. Endpoint ini hanya dapat diakses melalui HTTPS. Koneksi HTTP biasa ditolak.

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

Parameter
client_id Wajib

Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Credentials page API Console.
redirect_uri Wajib

Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di Credentials page API Consoleklien Anda. Jika nilai ini tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client_id yang disediakan, Anda akan mendapatkan error redirect_uri_mismatch.

Perhatikan bahwa skema, kasus, dan garis miring (http) / atau https harus cocok.
response_type Wajib

Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi.

Setel nilai parameter ke code untuk aplikasi server web.
scope Wajib

Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menunjukkan layar izin yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.

Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks jika memungkinkan. Dengan meminta akses ke data pengguna dalam konteks, melalui otorisasi inkremental, Anda membantu pengguna untuk lebih mudah memahami mengapa aplikasi Anda memerlukan akses yang diminta.
access_type Direkomendasikan

Menunjukkan apakah aplikasi Anda dapat me-refresh token akses saat pengguna tidak ada di browser. Parameter value yang valid adalah online, yang merupakan nilai default, dan offline.

Tetapkan nilai ke offline jika aplikasi perlu memperbarui token akses saat pengguna tidak ada di browser. Ini adalah metode untuk memperbarui token akses yang dijelaskan nanti dalam dokumen ini. Nilai ini memerintahkan server otorisasi Google untuk menampilkan token refresh dan token akses saat pertama kali aplikasi Anda menukar kode otorisasi dengan token.
state Direkomendasikan

Menentukan nilai string apa pun yang digunakan aplikasi untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi. Server menampilkan nilai persis yang Anda kirim sebagai pasangan name=value dalam komponen kueri URL (?) redirect_uri setelah pengguna menyetujui atau menolak permintaan akses aplikasi Anda.

Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar di aplikasi Anda, mengirim nonce, dan mengurangi pemalsuan permintaan lintas situs. Karena redirect_uri Anda dapat ditebak, menggunakan nilai state dapat meningkatkan jaminan bahwa koneksi masuk adalah hasil dari permintaan autentikasi. Jika membuat string acak atau mengenkode hash cookie atau nilai lain yang mengambil status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, yang memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs. Baca dokumentasi OpenID Connect untuk melihat contoh cara membuat dan mengonfirmasi token state.
include_granted_scopes Opsional

Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke true dan permintaan otorisasi disetujui, token akses baru juga akan mencakup cakupan apa pun yang sebelumnya diberi akses aplikasi oleh pengguna. Lihat bagian otorisasi inkremental sebagai contoh.
login_hint Opsional

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

Setel nilai parameter ke alamat email atau ID sub, yang setara dengan ID Google pengguna.
prompt Opsional

Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk menampilkan pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat pertama kali project Anda meminta akses. Lihat Meminta izin kembali untuk mengetahui informasi selengkapnya.

Nilai yang dimungkinkan adalah:

none Jangan tampilkan layar autentikasi atau izin. Tidak boleh ditentukan dengan nilai lain.
consent Minta izin pengguna.
select_account Minta pengguna memilih akun.

Langkah 2: Alihkan ke server OAuth 2.0 Google

Alihkan pengguna ke server OAuth 2.0 Google untuk memulai proses autentikasi dan otorisasi. Biasanya, ini terjadi saat aplikasi Anda pertama kali perlu mengakses data pengguna. Dalam kasus otorisasi inkremental, langkah ini juga terjadi ketika aplikasi Anda pertama kali perlu mengakses resource tambahan yang belum memiliki izin untuk mengaksesnya.

PHP

  1. Buat URL untuk meminta akses dari server OAuth 2.0 Google: 
    $auth_url = $client->createAuthUrl();
  2. Alihkan pengguna ke $auth_url: 
    header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

Contoh ini menunjukkan cara mengalihkan pengguna ke URL otorisasi menggunakan framework aplikasi web Flask:

return flask.redirect(authorization_url)

Ruby

  1. Buat URL untuk meminta akses dari server OAuth 2.0 Google: 
    auth_uri = auth_client.authorization_uri.to_s
  2. Alihkan pengguna ke auth_uri.

Node.js

  1. Gunakan URL yang dihasilkan authorizationUrl dari metode Langkah 1 generateAuthUrl untuk meminta akses dari server OAuth 2.0 Google.
  2. Alihkan pengguna ke authorizationUrl. 
    res.writeHead(301, { "Location": authorizationUrl });

HTTP/REST

Sample redirect to Google's authorization server

An example URL is shown below, with line breaks and spaces for readability.

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

Setelah Anda membuat URL permintaan, alihkan pengguna ke URL URL.

Server OAuth 2.0 Google mengautentikasi pengguna dan memperoleh izin dari pengguna untuk aplikasi Anda agar dapat mengakses cakupan yang diminta. Respons akan dikirim kembali ke aplikasi menggunakan URL alihan yang Anda tentukan.

Langkah 3: Google akan meminta izin pengguna

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

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

Error

Permintaan ke endpoint otorisasi OAuth 2.0 Google dapat menampilkan pesan error yang ditampilkan kepada pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode error umum dan resolusi yang disarankan tercantum di bawah ini.

admin_policy_enforced

Akun Google tidak dapat mengizinkan satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace-nya. Lihat artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal yang mengakses data Google Workspace untuk informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan yang dibatasi hingga akses diberikan secara eksplisit ke client ID OAuth Anda.

disallowed_useragent

Endpoint otorisasi ditampilkan di dalam agen pengguna tersemat yang tidak diizinkan oleh Kebijakan OAuth 2.0 Google.

Android

Developer Android mungkin mendapati pesan error ini saat membuka permintaan otorisasi di android.webkit.WebView. Sebagai gantinya, developer harus menggunakan library Android seperti Login dengan Google untuk Android atau AppAuth untuk Android dari OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi Android membuka link web umum dalam agen pengguna yang disematkan dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum terbuka di pengendali link default sistem operasi, yang mencakup pengendali Link Aplikasi Android atau aplikasi browser default. Library Tab Khusus Android juga merupakan opsi yang didukung.

iOS

Developer iOS dan macOS mungkin mengalami error ini saat membuka permintaan otorisasi di WKWebView. Sebagai gantinya, developer harus menggunakan library iOS seperti Login dengan Google untuk iOS atau AppAuth untuk iOS OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi iOS atau macOS membuka link web umum di agen pengguna tersemat dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum terbuka di pengendali link default sistem operasi, yang mencakup pengendali Universal Links atau aplikasi browser default. Library SFSafariViewController juga merupakan opsi yang didukung.
org_internal

Client ID OAuth dalam permintaan adalah bagian dari project yang membatasi akses ke Akun Google di Organisasi Google Cloud tertentu. Untuk informasi selengkapnya tentang opsi konfigurasi ini, lihat bagian Jenis pengguna di artikel bantuan layar Menyiapkan izin.

invalid_client

Rahasia klien OAuth salah. Tinjau konfigurasi klien OAuth, termasuk client ID dan rahasia yang digunakan untuk permintaan ini.

invalid_grant

Saat memperbarui token akses atau menggunakan otorisasi inkremental, token mungkin telah habis masa berlakunya atau menjadi tidak valid. Autentikasi pengguna lagi dan minta izin pengguna untuk mendapatkan token baru. Jika Anda terus melihat error ini, pastikan bahwa aplikasi Anda telah dikonfigurasi dengan benar dan Anda menggunakan token serta parameter yang benar dalam permintaan. Jika tidak, akun pengguna mungkin telah dihapus atau dinonaktifkan.

redirect_uri_mismatch

redirect_uri yang diteruskan dalam permintaan otorisasi tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client ID OAuth. Tinjau URI pengalihan yang diberi otorisasi di Google API Console Credentials page.

Parameter redirect_uri mungkin mengacu pada alur OAuth out-of-band (OOB) yang tidak digunakan lagi dan tidak didukung lagi. Lihat panduan migrasi untuk memperbarui integrasi Anda.

Langkah 4: Tangani respons server OAuth 2.0

Server OAuth 2.0 merespons permintaan akses aplikasi Anda dengan menggunakan URL yang ditentukan dalam permintaan.

Jika pengguna menyetujui permintaan akses, respons akan berisi kode otorisasi. Jika pengguna tidak menyetujui permintaan tersebut, respons akan berisi pesan error. Kode otorisasi atau pesan error yang dikembalikan ke server web muncul di string kueri, seperti yang ditampilkan di bawah ini:

Respons error:

https://oauth2.example.com/auth?error=access_denied

Respons kode otorisasi:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

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//www.googleapis.com/auth/drive.metadata.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

Setelah menyelesaikan alur OAuth 2.0, Anda akan dialihkan ke http://localhost/oauth2callback, yang mungkin akan menghasilkan error 404 NOT FOUND kecuali jika mesin lokal Anda menayangkan file di alamat tersebut. Langkah berikutnya memberikan detail selengkapnya tentang informasi yang ditampilkan di URI saat pengguna dialihkan kembali ke aplikasi Anda.

Langkah 5: Tukar kode otorisasi untuk memuat ulang dan mengakses token

Setelah menerima kode otorisasi, server web dapat menukarnya dengan token akses.

PHP

Untuk menukar kode otorisasi dengan token akses, gunakan metode authenticate:

$client->authenticate($_GET['code']);

Anda dapat mengambil token akses dengan metode getAccessToken:

$access_token = $client->getAccessToken();

Python

Di halaman callback, gunakan library google-auth untuk memverifikasi respons server otorisasi. Kemudian, gunakan metode flow.fetch_token untuk menukar kode otorisasi dalam respons tersebut dengan token akses:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'scopes': credentials.scopes}

Ruby

Untuk menukar kode otorisasi dengan token akses, gunakan metode fetch_access_token!:

auth_client.code = auth_code
auth_client.fetch_access_token!

Node.js

Untuk menukar kode otorisasi dengan token akses, gunakan metode getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
if (req.url.startsWith('/oauth2callback')) {
  // Handle the OAuth 2.0 server response
  let q = url.parse(req.url, true).query;

  // Get access and refresh tokens (if access_type is offline)
  let { tokens } = await oauth2Client.getToken(q.code);
  oauth2Client.setCredentials(tokens);
}

HTTP/REST

Untuk menukar kode otorisasi dengan token akses, panggil endpoint https://oauth2.googleapis.com/token dan tetapkan parameter berikut:

Kolom
client_id Client ID yang diperoleh dari API Console Credentials page.
client_secret Rahasia klien yang diperoleh dari API Console Credentials page.
code Kode otorisasi yang ditampilkan dari permintaan awal.
grant_type Seperti yang ditentukan dalam spesifikasi OAuth 2.0, nilai kolom ini harus ditetapkan ke authorization_code.
redirect_uri Salah satu URI pengalihan yang tercantum untuk project Anda di API Console Credentials page untuk client_id tertentu.

Cuplikan berikut menunjukkan permintaan contoh:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Google merespons permintaan ini dengan menampilkan objek JSON yang berisi token akses berjangka pendek dan token refresh. Perhatikan bahwa token refresh hanya ditampilkan jika aplikasi Anda menetapkan parameter access_type ke offline dalam permintaan awal ke server otorisasi Google.

Responsnya berisi kolom berikut:

Kolom
access_token Token yang dikirim aplikasi Anda untuk mengizinkan permintaan Google API.
expires_in Masa berlaku token akses yang tersisa dalam hitungan detik.
refresh_token Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token refresh valid hingga pengguna mencabut akses. Sekali lagi, kolom ini hanya ada dalam respons ini jika Anda menetapkan parameter access_type ke offline dalam permintaan awal ke server otorisasi Google.
scope Cakupan akses yang diberikan oleh access_token dinyatakan sebagai daftar string yang dipisahkan spasi dan peka huruf besar/kecil.
token_type Jenis token yang ditampilkan. Pada saat ini, nilai kolom ini selalu ditetapkan ke Bearer.

Cuplikan berikut menunjukkan contoh respons:

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

Error

Saat bertukar kode otorisasi untuk token akses, Anda mungkin mengalami error berikut, bukan respons yang diharapkan. Kode error umum dan penyelesaian yang disarankan tercantum di bawah ini.

invalid_grant

Kode otorisasi yang diberikan tidak valid atau dalam format yang salah. Minta kode baru dengan memulai ulang proses OAuth untuk meminta izin pengguna lagi.

Memanggil Google API

PHP

Gunakan token akses untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:

  1. Jika Anda perlu menerapkan token akses ke objek Google\Client baru — misalnya, jika Anda menyimpan token akses dalam sesi pengguna — gunakan metode setAccessToken: 
    $client->setAccessToken($access_token);
  2. Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan menyediakan objek Google\Client yang diotorisasi ke konstruktor untuk API yang ingin Anda panggil. Misalnya, untuk memanggil Drive API: 
    $drive = new Google\Service\Drive($client);
  3. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk membuat daftar file di Google Drive pengguna terautentikasi: 
    $files = $drive->files->listFiles(array())->getItems();

Python

Setelah memperoleh token akses, aplikasi Anda dapat menggunakan token tersebut untuk mengizinkan permintaan API atas nama akun pengguna atau akun layanan tertentu. Gunakan kredensial otorisasi khusus pengguna untuk membuat objek layanan bagi API yang ingin Anda panggil, lalu gunakan objek tersebut untuk membuat permintaan API yang diotorisasi.

  1. Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan memanggil metode build library googleapiclient.discovery dengan nama dan versi API serta kredensial pengguna: Misalnya, untuk memanggil Drive API versi 2: 
    from googleapiclient.discovery import build

drive = build('drive', 'v2', credentials=credentials)
  2. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk membuat daftar file di Google Drive pengguna terautentikasi: 
    files = drive.files().list().execute()

Ruby

Gunakan objek auth_client untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:

  1. Buat objek layanan untuk API yang ingin Anda panggil. Misalnya, untuk memanggil Drive API versi 2: 
    drive = Google::Apis::DriveV2::DriveService.new
  2. Tetapkan kredensial di layanan: 
    drive.authorization = auth_client
  3. Buat permintaan ke layanan API menggunakan antarmuka yang diberikan oleh objek layanan. Misalnya, untuk membuat daftar file di Google Drive pengguna terautentikasi: 
    files = drive.list_files

Atau, otorisasi dapat diberikan per metode dengan menyediakan parameter options ke metode:

files = drive.list_files(options: { authorization: auth_client })

Node.js

Setelah mendapatkan token akses dan menyetelnya ke objek OAuth2, gunakan objek tersebut untuk memanggil Google API. Aplikasi Anda dapat menggunakan token tersebut untuk mengizinkan permintaan API atas nama akun pengguna atau akun layanan tertentu. Buat objek layanan untuk API yang ingin Anda panggil.

const { google } = require('googleapis');

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

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 direkomendasikan, karena string kueri cenderung terlihat di log server. Dalam sebagian besar kasus, Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil Drive Files API).

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

Contoh HTTP GET

Panggilan ke endpoint drive.files (Drive Files API) yang menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. 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 terautentikasi menggunakan parameter string kueri access_token:

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

Contoh curl

Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut ini 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

Contoh lengkap

Contoh berikut mencetak daftar file berformat JSON di Google Drive pengguna setelah pengguna melakukan autentikasi dan memberikan izin bagi aplikasi untuk mengakses metadata Drive pengguna.

PHP

Untuk menjalankan contoh ini:

  1. Di API Console, tambahkan URL perangkat lokal ke daftar URL alihan. Misalnya, tambahkan http://localhost:8080.
  2. Membuat direktori baru dan mengubahnya. Contoh: 
    mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
  3. Instal Library Klien Google API untuk PHP menggunakan Composer: 
    composer require google/apiclient:^2.10
  4. Buat file index.php dan oauth2callback.php dengan konten di bawah.
  5. Jalankan contoh dengan server web yang dikonfigurasi untuk menayangkan PHP. Jika menggunakan PHP 5.6 atau yang lebih baru, Anda dapat menggunakan server web pengujian bawaan PHP: 
    php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secrets.json');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (isset($_SESSION['access_token']) && $_SESSION['access_token']) {
  $client->setAccessToken($_SESSION['access_token']);
  $drive = new Google\Service\Drive($client);
  $files = $drive->files->listFiles(array())->getItems();
  echo json_encode($files);
} else {
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfigFile('client_secrets.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');
$client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY);

if (! isset($_GET['code'])) {
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
} else {
  $client->authenticate($_GET['code']);
  $_SESSION['access_token'] = $client->getAccessToken();
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

Python

Contoh ini menggunakan framework Flask. Library ini menjalankan aplikasi web di http://localhost:8080 yang memungkinkan Anda menguji alur OAuth 2.0. Jika Anda membuka URL tersebut, Anda akan melihat empat link:

  • Uji permintaan API: Link ini mengarah ke halaman yang mencoba menjalankan permintaan API sampel. Jika perlu, alur otorisasi akan dimulai. Jika berhasil, halaman menampilkan respons API.
  • Menguji alur autentikasi secara langsung: Link ini mengarah ke halaman yang mencoba mengarahkan pengguna melalui alur otorisasi. Aplikasi meminta izin untuk mengirimkan permintaan API yang diotorisasi atas nama pengguna.
  • Mencabut kredensial saat ini: Link ini mengarah ke halaman yang mencabut izin yang telah diberikan pengguna ke aplikasi.
  • Hapus kredensial sesi Flask: Link ini menghapus kredensial otorisasi yang disimpan dalam sesi Flask. Ini memungkinkan Anda melihat apa yang akan terjadi jika pengguna yang telah memberikan izin ke aplikasi Anda mencoba menjalankan permintaan API di sesi baru. Cara ini juga memungkinkan Anda melihat respons API yang akan diterima aplikasi jika pengguna telah mencabut izin yang diberikan untuk aplikasi Anda, dan aplikasi masih mencoba mengizinkan permintaan dengan token akses yang dicabut.
# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# This OAuth 2.0 access scope allows for full read/write access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'


@app.route('/')
def index():
  return print_index_table()


@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
      **flask.session['credentials'])

  drive = googleapiclient.discovery.build(
      API_SERVICE_NAME, API_VERSION, credentials=credentials)

  files = drive.files().list().execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**files)


@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)


@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))


@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())


@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())


def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'scopes': credentials.scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')


if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

Contoh ini menggunakan framework Sinatra.

require 'google/apis/drive_v2'
require 'google/api_client/client_secrets'
require 'json'
require 'sinatra'

enable :sessions
set :session_secret, 'setme'

get '/' do
  unless session.has_key?(:credentials)
    redirect to('/oauth2callback')
  end
  client_opts = JSON.parse(session[:credentials])
  auth_client = Signet::OAuth2::Client.new(client_opts)
  drive = Google::Apis::DriveV2::DriveService.new
  files = drive.list_files(options: { authorization: auth_client })
  "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
end

get '/oauth2callback' do
  client_secrets = Google::APIClient::ClientSecrets.load
  auth_client = client_secrets.to_authorization
  auth_client.update!(
    :scope => 'https://www.googleapis.com/auth/drive.metadata.readonly',
    :redirect_uri => url('/oauth2callback'))
  if request['code'] == nil
    auth_uri = auth_client.authorization_uri.to_s
    redirect to(auth_uri)
  else
    auth_client.code = request['code']
    auth_client.fetch_access_token!
    auth_client.client_secret = nil
    session[:credentials] = auth_client.to_json
    redirect to('/')
  end
end

Node.js

Untuk menjalankan contoh ini:

  1. Di API Console, tambahkan URL komputer lokal ke daftar URL alihan. Misalnya, tambahkan http://localhost.
  2. Pastikan Anda memiliki LTS pemeliharaan, LTS aktif, atau rilis Node.js saat ini.
  3. Membuat direktori baru dan mengubahnya. Contoh: 
    mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
  4. Install the Google API Client Library for Node.js using npm: 
    npm install googleapis
  5. Buat file main.js dengan konten di bawah ini.
  6. Jalankan contoh: 
    node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for read-only Drive activity.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

// Generate a url that asks permissions for the Drive activity scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google's OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }

    // Receive the callback from Google's OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) { // An error response e.g. error=access_denied
        console.log('Error:' + q.error);
      } else { // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        /** Save credential to the global variable in case access token was refreshed.
          * ACTION ITEM: In a production app, you likely want to save the refresh token
          *              in a secure persistent database instead. */
        userCredential = tokens;

        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
    }

    // Example on revoking a token
    if (req.url == '/revoke') {
      // Build the string for the POST request
      let postData = "token=" + userCredential.access_token;

      // Options for POST request to Google's OAuth 2.0 server to revoke a token
      let postOptions = {
        host: 'oauth2.googleapis.com',
        port: '443',
        path: '/revoke',
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Content-Length': Buffer.byteLength(postData)
        }
      };

      // Set up the request
      const postReq = https.request(postOptions, function (res) {
        res.setEncoding('utf8');
        res.on('data', d => {
          console.log('Response: ' + d);
        });
      });

      postReq.on('error', error => {
        console.log(error)
      });

      // Post the request with data
      postReq.write(postData);
      postReq.end();
    }
    res.end();
  }).listen(80);
}
main().catch(console.error);

HTTP/REST

Contoh Python ini menggunakan framework Flask dan library Requests untuk menunjukkan alur web OAuth 2.0. Sebaiknya gunakan Library Klien Google API untuk Python untuk alur ini. (Contoh di tab Python menggunakan library klien.)

import json

import flask
import requests


app = flask.Flask(__name__)

CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'
REDIRECT_URI = 'http://example.com/oauth2callback'


@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))
  credentials = json.loads(flask.session['credentials'])
  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else:
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/drive/v2/files'
    r = requests.get(req_uri, headers=headers)
    return r.text


@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}').format(CLIENT_ID, REDIRECT_URI, SCOPE)
    return flask.redirect(auth_uri)
  else:
    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))


if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Aturan validasi URI pengalihan

Google menerapkan aturan validasi berikut untuk mengalihkan URI guna membantu developer menjaga keamanan aplikasi mereka. URI pengalihan harus mematuhi aturan ini. Lihat RFC 3986 bagian 3 untuk definisi domain, host, jalur, kueri, skema, dan infopengguna, yang disebutkan di bawah ini.

Aturan validasi
Skema

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

Host tidak boleh berupa alamat IP mentah. Alamat IP Localhost dikecualikan dari aturan ini.
Domain
  • TLD Host (Domain Level Teratas) harus termasuk dalam daftar akhiran publik.
  • Domain host tidak boleh “googleusercontent.com”.
  • URI pengalihan tidak boleh berisi domain penyingkat URL (misalnya, goo.gl) kecuali jika aplikasi memiliki domain tersebut. Selain itu, jika aplikasi yang memiliki domain penyingkat memilih untuk mengalihkan ke domain tersebut, URI pengalihan tersebut harus berisi “/google-callback/” dalam jalurnya atau diakhiri dengan “/google-callback”.
    		•
    Info pengguna

    URI pengalihan tidak boleh berisi subkomponen userinfo.
    Jalur

    URI pengalihan tidak boleh berisi traversal jalur (juga disebut pelacakan balik direktori), yang direpresentasikan oleh “/..” atau “\..” atau encoding URL-nya.
    Kueri

    URI pengalihan tidak boleh berisi pengalihan terbuka.
    Fragment

    URI pengalihan tidak boleh berisi komponen fragmen.
    Karakter URI pengalihan tidak boleh berisi karakter tertentu, termasuk:
    • Karakter pengganti ('*')
    • Karakter ASCII yang tidak dapat dicetak
    • Encoding persen tidak valid (encoding persen yang tidak mengikuti bentuk encoding URL dari tanda persen diikuti dengan dua digit heksadesimal)
    • Karakter null (karakter nullable yang dienkode, misalnya, %00, %C0%80)

    Otorisasi inkremental

    Dalam protokol OAuth 2.0, aplikasi Anda meminta otorisasi untuk mengakses resource, yang diidentifikasi oleh cakupan. Hal ini dianggap sebagai praktik pengalaman pengguna terbaik untuk meminta otorisasi bagi resource pada saat Anda membutuhkannya. Untuk mengaktifkan praktik tersebut, server otorisasi Google mendukung otorisasi inkremental. Fitur ini memungkinkan Anda meminta cakupan sesuai kebutuhan dan, jika pengguna memberikan izin untuk cakupan baru, akan menampilkan kode otorisasi yang dapat ditukar dengan token yang berisi semua cakupan yang telah diberikan pengguna ke project.

    Misalnya, aplikasi yang memungkinkan pengguna mengambil sampel trek musik dan membuat video mix mungkin memerlukan sangat sedikit resource pada saat login, mungkin tidak lebih dari nama pengguna yang login. Namun, untuk menyimpan campuran yang sudah selesai akan memerlukan akses ke Google Drive. Kebanyakan orang akan merasa alami jika mereka hanya diminta untuk mengakses Google Drive mereka pada saat aplikasi benar-benar membutuhkannya.

    Dalam hal ini, pada saat login, aplikasi dapat meminta cakupan openid dan profile untuk menjalankan login dasar, lalu meminta cakupan https://www.googleapis.com/auth/drive.file pada saat permintaan pertama untuk menyimpan campuran.

    Untuk menerapkan otorisasi inkremental, Anda menyelesaikan alur normal untuk meminta token akses, tetapi pastikan bahwa permintaan otorisasi menyertakan cakupan yang diberikan sebelumnya. Pendekatan ini memungkinkan aplikasi menghindari pengelolaan beberapa token akses.

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

    • Token tersebut dapat digunakan untuk mengakses resource yang sesuai dengan salah satu cakupan yang diluncurkan ke otorisasi gabungan yang baru.
    • Saat Anda menggunakan token refresh untuk otorisasi gabungan untuk mendapatkan token akses, token akses mewakili otorisasi gabungan dan dapat digunakan untuk salah satu nilai scope yang disertakan dalam respons.
    • Otorisasi gabungan mencakup semua cakupan yang diberikan pengguna ke project API meskipun hibah diminta dari klien yang berbeda. Misalnya, jika pengguna memberikan akses ke satu cakupan menggunakan klien desktop aplikasi, lalu diberi cakupan lain ke aplikasi yang sama melalui klien seluler, otorisasi gabungan akan menyertakan kedua cakupan tersebut.
    • Jika Anda mencabut token yang mewakili otorisasi gabungan, akses ke semua cakupan otorisasi tersebut atas nama pengguna terkait akan dicabut secara bersamaan.

    Contoh kode khusus bahasa pada Langkah 1: Tetapkan parameter otorisasi dan contoh URL pengalihan HTTP/REST pada Langkah 2: Alihkan ke server OAuth 2.0 Google menggunakan otorisasi inkremental. Contoh kode di bawah juga menunjukkan kode yang perlu Anda tambahkan untuk menggunakan otorisasi inkremental.

    PHP

    $client->setIncludeGrantedScopes(true);

    Python

    Di Python, tetapkan argumen kata kunci include_granted_scopes ke true untuk memastikan bahwa permintaan otorisasi menyertakan cakupan yang diberikan sebelumnya. Sangat mungkin bahwa include_granted_scopes tidak akan menjadi argumen kata kunci satu-satunya yang Anda tetapkan, seperti yang ditunjukkan dalam contoh di bawah.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Ruby

    auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

    Node.js

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    HTTP/REST

    GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.file&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

    Memperbarui token akses (akses offline)

    Masa berlaku token akses berakhir secara berkala dan menjadi tidak valid untuk permintaan API terkait. Anda dapat memperbarui token akses tanpa meminta izin pengguna (termasuk ketika pengguna tidak ada) jika meminta akses offline ke cakupan yang terkait dengan token.

    • Jika Anda menggunakan Library Klien Google API, objek klien akan memperbarui token akses sesuai kebutuhan selama Anda mengonfigurasi objek tersebut untuk akses offline.
    • Jika tidak menggunakan library klien, Anda harus menetapkan parameter kueri HTTP access_type ke offline saat mengalihkan pengguna ke server OAuth 2.0 Google. Dalam hal ini, server otorisasi Google akan menampilkan token refresh saat Anda menukarkan kode otorisasi dengan token akses. Kemudian, jika masa berlaku token akses berakhir (atau kapan saja), Anda dapat menggunakan token refresh untuk mendapatkan token akses baru.

    Meminta akses offline adalah persyaratan untuk setiap aplikasi yang perlu mengakses Google API ketika pengguna tidak ada. Misalnya, aplikasi yang menjalankan layanan pencadangan atau menjalankan tindakan pada waktu yang telah ditentukan harus dapat me-refresh token aksesnya jika pengguna tidak ada. Gaya akses default disebut online.

    Aplikasi web sisi server, aplikasi terinstal, dan perangkat semuanya memperoleh token refresh selama proses otorisasi. Token refresh biasanya tidak digunakan dalam aplikasi web sisi klien (JavaScript).

    PHP

    Jika aplikasi Anda memerlukan akses offline ke Google API, tetapkan jenis akses klien API ke offline:

    $client->setAccessType("offline");

    Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna sedang offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

    Python

    Di Python, tetapkan argumen kata kunci access_type ke offline untuk memastikan bahwa Anda dapat me-refresh token akses tanpa harus meminta ulang izin kepada pengguna. Ada kemungkinan bahwa access_type tidak akan menjadi argumen kata kunci satu-satunya yang Anda tetapkan, seperti yang ditunjukkan dalam contoh di bawah.

    authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

    Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna sedang offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

    Ruby

    Jika aplikasi Anda memerlukan akses offline ke Google API, tetapkan jenis akses klien API ke offline:

    auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

    Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna sedang offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

    Node.js

    Jika aplikasi Anda memerlukan akses offline ke Google API, tetapkan jenis akses klien API ke offline:

    const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

    Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna sedang offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

    Masa berlaku token akses berakhir. Library ini akan otomatis menggunakan token refresh untuk mendapatkan token akses baru jika masa berlakunya akan segera berakhir. Cara mudah untuk memastikan Anda selalu menyimpan token terbaru adalah dengan menggunakan peristiwa token:

    oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

    Peristiwa token ini hanya terjadi dalam otorisasi pertama, dan Anda harus menetapkan access_type ke offline saat memanggil metode generateAuthUrl untuk menerima token refresh. Jika sudah memberikan izin yang diperlukan pada aplikasi tanpa menetapkan batasan yang sesuai untuk menerima token refresh, Anda harus mengotorisasi ulang aplikasi untuk menerima token refresh baru.

    Untuk menetapkan refresh_token di lain waktu, Anda dapat menggunakan metode setCredentials: 

    oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

    Setelah klien memiliki token refresh, token akses akan diperoleh dan di-refresh secara otomatis pada panggilan berikutnya ke API.

    HTTP/REST

    Untuk memperbarui token akses, aplikasi Anda akan mengirimkan permintaan POST HTTPS ke server otorisasi Google (https://oauth2.googleapis.com/token) yang menyertakan parameter berikut:

    Kolom
    client_id Client ID yang diperoleh dari API Console.
    client_secret Rahasia klien yang diperoleh dari API Console.
    grant_type Seperti yang ditentukan dalam spesifikasi OAuth 2.0, nilai kolom ini harus ditetapkan ke refresh_token.
    refresh_token Token refresh ditampilkan dari pertukaran kode otorisasi.

    Cuplikan berikut menunjukkan permintaan contoh:

    POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

    Selama pengguna tidak mencabut akses yang diberikan ke aplikasi, server token akan menampilkan objek JSON yang berisi token akses baru. Cuplikan berikut menunjukkan contoh respons:

    {
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

    Perhatikan bahwa ada batas jumlah token refresh yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna di seluruh klien. Anda harus menyimpan token refresh dalam penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika meminta terlalu banyak token refresh, aplikasi Anda mungkin akan mencapai batas tersebut, sehingga token refresh yang lebih lama akan berhenti berfungsi.

    Mencabut token

    Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Pengguna dapat mencabut akses dengan membuka Setelan Akun. Lihat bagian Menghapus situs atau aplikasi dari situs & aplikasi pihak ketiga yang memiliki akses ke akun Anda untuk mengetahui informasi selengkapnya.

    Aplikasi juga dapat mencabut akses yang diberikan secara terprogram. Pencabutan terprogram diperlukan jika pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan ini dapat mencakup permintaan API untuk memastikan izin yang sebelumnya diberikan untuk aplikasi telah dihapus.

    PHP

    Untuk mencabut token secara terprogram, panggil revokeToken():

    $client->revokeToken();

    Python

    Untuk mencabut token secara terprogram, buat permintaan ke https://oauth2.googleapis.com/revoke yang menyertakan token sebagai parameter dan tetapkan header Content-Type:

    requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

    Ruby

    Untuk mencabut token secara terprogram, buat permintaan HTTP ke endpoint oauth2.revoke:

    uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

    Token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

    Jika pencabutan berhasil diproses, kode status respons adalah 200. Untuk kondisi error, kode status 400 ditampilkan bersama dengan kode error.

    Node.js

    Untuk mencabut token secara terprogram, buat permintaan POST HTTPS ke endpoint /revoke:

    const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

    Parameter token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

    Jika pencabutan berhasil diproses, kode status respons adalah 200. Untuk kondisi error, kode status 400 ditampilkan bersama dengan kode error.

    HTTP/REST

    Untuk mencabut token secara terprogram, aplikasi Anda membuat permintaan ke https://oauth2.googleapis.com/revoke dan menyertakan token tersebut 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 adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

    Jika pencabutan berhasil diproses, kode status HTTP respons adalah 200. Untuk kondisi error, kode status HTTP 400 ditampilkan bersama dengan kode error.