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 untuk berbagi data tertentu dengan aplikasi, sekaligus tetap menjaga kerahasiaan nama pengguna, sandi, dan informasi mereka lainnya. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna untuk menyimpan file di Google Drive mereka.
Alur OAuth 2.0 ini khusus untuk otorisasi pengguna. Didesain untuk aplikasi yang dapat menyimpan informasi rahasia dan menjaga status. Aplikasi server web yang diotorisasi dengan tepat dapat mengakses API saat pengguna berinteraksi dengan aplikasi atau setelah pengguna meninggalkan 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 spesifik per pengguna. Aplikasi server web dapat menggunakan akun layanan bersamaan 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 terlebih dahulu menginstal library klien untuk bahasa Anda.
Ketika Anda menggunakan Library Klien Google API untuk menangani alur OAuth 2.0 aplikasi Anda, library klien akan melakukan banyak tindakan yang seharusnya tidak perlu ditangani aplikasi itu sendiri. Misalnya, kebijakan ini menentukan kapan aplikasi dapat menggunakan atau memuat ulang token akses tersimpan serta kapan aplikasi harus mendapatkan kembali izin. Library klien juga menghasilkan URL alihan yang benar dan membantu menerapkan pengendali pengalihan yang menukar kode otorisasi dengan token akses.
Library Klien Google API untuk aplikasi sisi server tersedia dalam 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:
- Open the API Library di Google API Console.
- If prompted, select a project, or create a new one.
- 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 menemukannya, atau klik Lihat Semua di kelompok produknya.
- Pilih API yang ingin Anda aktifkan, lalu klik tombol Aktifkan.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Membuat 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 project Anda. Selanjutnya, aplikasi Anda dapat menggunakan kredensial tersebut untuk mengakses API yang telah Anda aktifkan untuk project tersebut.
- Go to the Credentials page.
- Klik Buat kredensial > client ID OAuth.
- Pilih jenis aplikasi Aplikasi web.
- Isi formulir lalu klik Buat. 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 digunakan server OAuth 2.0 untuk mengirim respons. Endpoint
ini harus mematuhi aturan validasi Google.
Untuk pengujian, Anda dapat menentukan URI yang merujuk ke mesin lokal, seperti
http://localhost:8080
. Dengan memperhatikan hal tersebut, perlu diperhatikan bahwa semua contoh dalam dokumen ini menggunakanhttp://localhost:8080
sebagai URI pengalihan.Sebaiknya desain endpoint autentikasi aplikasi agar aplikasi tidak mengekspos kode otorisasi ke resource lain pada halaman tersebut.
Setelah membuat kredensial Anda, 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 diperlukannya 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 untuk mendapatkan izin pengguna.
Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya identifikasi cakupan yang memerlukan izin untuk diakses oleh aplikasi Anda.
Sebaiknya aplikasi Anda juga meminta akses ke cakupan otorisasi melalui proses otorisasi inkremental, yang mana aplikasi Anda akan meminta akses ke data pengguna sesuai konteks. Praktik terbaik ini membantu pengguna agar lebih mudah memahami alasan aplikasi memerlukan akses yang diminta.
Dokumen Cakupan API OAuth 2.0 berisi daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API.
Persyaratan spesifik per bahasa
Untuk menjalankan salah satu 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 khusus bahasa di bawah ini.
PHP
Untuk menjalankan contoh kode PHP dalam dokumen ini, Anda akan membutuhkan:
- PHP 5.6 atau yang lebih baru dengan antarmuka command line (CLI) dan ekstensi JSON yang terinstal.
- Alat pengelolaan dependensi Composer.
-
Library Klien Google API untuk PHP:
composer require google/apiclient:^2.10
Python
Untuk menjalankan contoh kode Python dalam dokumen ini, Anda akan 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
, dangoogle-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 dalam dokumen ini, Anda memerlukan:
- Ruby 2.6 atau yang lebih baru
-
Google Auth Library untuk Ruby:
gem install googleauth
-
Framework aplikasi web Sinatra Ruby.
gem install sinatra
Node.js
Untuk menjalankan contoh kode Node.js dalam dokumen ini, Anda akan memerlukan:
- 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 agar dapat langsung memanggil endpoint OAuth 2.0.
Memperoleh token akses OAuth 2.0
Langkah-langkah berikut menunjukkan cara aplikasi Anda berinteraksi dengan server OAuth 2.0 Google untuk mendapatkan izin pengguna guna 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 merangkum langkah-langkah berikut dengan cepat:
- Aplikasi Anda mengidentifikasi izin yang dibutuhkan.
- Aplikasi Anda mengalihkan pengguna ke Google beserta daftar izin yang diminta.
- Pengguna akan memutuskan apakah akan memberikan izin ke aplikasi Anda.
- Aplikasi Anda mengetahui apa yang diputuskan pengguna.
- Jika pengguna memberikan izin yang diminta, aplikasi Anda akan mengambil token yang diperlukan untuk membuat permintaan API atas nama pengguna.
Langkah 1: Menetapkan parameter otorisasi
Langkah pertama Anda adalah membuat permintaan otorisasi. Permintaan tersebut menetapkan parameter yang mengidentifikasi aplikasi Anda dan mendefinisikan izin yang akan diminta untuk diberikan pengguna ke aplikasi Anda.
- Jika Anda menggunakan library klien Google untuk autentikasi dan otorisasi OAuth 2.0, Anda dapat membuat dan mengonfigurasi objek yang mendefinisikan parameter tersebut.
- Jika Anda memanggil endpoint Google OAuth 2.0 secara langsung, Anda akan membuat URL dan menetapkan parameter pada URL tersebut.
Tab di bawah ini 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 informasi selengkapnya tentang
file tersebut.) Objek ini juga mengidentifikasi cakupan yang izin aksesnya diminta aplikasi Anda 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 berikut meminta akses hanya baca dan offline 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" will prompt the user for consent $client->setPrompt('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 API Console Credentials page. Di PHP, panggil fungsi $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 konfigurasi di API Console
Credentials pageklien. Jika nilai ini tidak cocok dengan URI pengalihan yang diotorisasi untuk Perhatikan bahwa skema, kapitalisasi, dan garis miring di akhir Untuk menetapkan nilai ini di PHP, panggil fungsi $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 menentukan layar izin yang ditampilkan Google kepada pengguna. Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukannya 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 untuk mendapatkan izin pengguna. Untuk menetapkan nilai ini di PHP, panggil fungsi $client->addScope(Google\Service\Drive::DRIVE_METADATA_READONLY); Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi sesuai konteks jika memungkinkan. Dengan meminta akses ke data pengguna sesuai konteks, melalui otorisasi inkremental, Anda membantu pengguna agar lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta. |
||||||
access_type |
Direkomendasikan
Menunjukkan apakah aplikasi Anda dapat memuat ulang token akses saat pengguna tidak ada
di browser. Parameter value yang valid adalah Setel nilai ke Untuk menetapkan nilai ini di PHP, panggil fungsi $client->setAccessType('offline'); |
||||||
state |
Direkomendasikan
Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara
permintaan otorisasi dan respons server otorisasi.
Server menampilkan nilai persis yang Anda kirim sebagai pasangan Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke
resource yang benar dalam aplikasi, mengirim nonce, dan memitigasi pemalsuan permintaan
lintas situs. Karena Untuk menetapkan nilai ini di PHP, panggil fungsi $client->setState($sample_passthrough_value); |
||||||
include_granted_scopes |
Opsional
Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke Untuk menetapkan nilai ini di PHP, panggil fungsi $client->setIncludeGrantedScopes(true); |
||||||
enable_granular_consent |
Opsional
Default-nya adalah |
||||||
login_hint |
Opsional
Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi Anda dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login, baik dengan mengisi kolom email terlebih dahulu di formulir login, atau dengan memilih sesi multi-login yang sesuai. Tetapkan parameter value ke alamat email atau ID Untuk menetapkan nilai ini di PHP, panggil fungsi $client->setLoginHint('None'); |
||||||
prompt |
Opsional
Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat project Anda pertama kali meminta akses. Lihat Meminta izin ulang untuk informasi selengkapnya. Untuk menetapkan nilai ini di PHP, panggil fungsi $client->setPrompt('consent'); Nilai yang dimungkinkan adalah:
|
Python
Cuplikan kode berikut menggunakan modul google-auth-oauthlib.flow
untuk membuat
permintaan otorisasi.
Kode tersebut 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 izin aksesnya diminta aplikasi Anda 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 berikut meminta akses hanya baca dan offline 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 API Console Credentials page. Dalam Python, panggil metode 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 konfigurasi di API Console
Credentials pageklien. Jika nilai ini tidak cocok dengan URI pengalihan yang diotorisasi untuk Perhatikan bahwa skema, kapitalisasi, dan garis miring di akhir Untuk menetapkan nilai ini di Python, tetapkan properti
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 menentukan layar izin yang ditampilkan Google kepada pengguna. Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukannya 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 untuk mendapatkan izin pengguna. Di Python, gunakan metode yang sama dengan yang Anda gunakan untuk menetapkan 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 sesuai konteks jika memungkinkan. Dengan meminta akses ke data pengguna sesuai konteks, melalui otorisasi inkremental, Anda membantu pengguna agar lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta. |
||||||
access_type |
Direkomendasikan
Menunjukkan apakah aplikasi Anda dapat memuat ulang token akses saat pengguna tidak ada
di browser. Parameter value yang valid adalah Setel nilai ke Di Python, tetapkan parameter authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
state |
Direkomendasikan
Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara
permintaan otorisasi dan respons server otorisasi.
Server menampilkan nilai persis yang Anda kirim sebagai pasangan Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke
resource yang benar dalam aplikasi, mengirim nonce, dan memitigasi pemalsuan permintaan
lintas situs. Karena Di Python, tetapkan parameter 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 sesuai konteks. Jika Anda menetapkan nilai parameter ini ke Di Python, tetapkan parameter authorization_url, state = flow.authorization_url( access_type='offline', include_granted_scopes='true') |
||||||
enable_granular_consent |
Opsional
Default-nya adalah |
||||||
login_hint |
Opsional
Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi Anda dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login, baik dengan mengisi kolom email terlebih dahulu di formulir login, atau dengan memilih sesi multi-login yang sesuai. Tetapkan parameter value ke alamat email atau ID Di Python, tetapkan parameter 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 ditampilkan kepada pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat project Anda pertama kali meminta akses. Lihat Meminta izin ulang untuk informasi selengkapnya. Di Python, tetapkan parameter authorization_url, state = flow.authorization_url( access_type='offline', prompt='consent', include_granted_scopes='true') Nilai yang dimungkinkan adalah:
|
Ruby
Gunakan file client_secrets.json yang Anda buat untuk mengonfigurasi objek klien dalam aplikasi Anda. Ketika mengonfigurasi objek klien, tentukan cakupan yang perlu diakses oleh aplikasi Anda, beserta URL ke endpoint autentikasi aplikasi Anda, yang akan menangani respons dari server OAuth 2.0.
Misalnya, kode berikut meminta akses hanya baca dan offline ke Google Drive pengguna:
require 'google/apis/drive_v3' require "googleauth" require 'googleauth/stores/redis_token_store' client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json') scope = 'https://www.googleapis.com/auth/drive.metadata.readonly' token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope, token_store, '/oauth2callback')Your application uses the client object to perform OAuth 2.0 operations, such as generating authorization request URLs and applying access tokens to HTTP requests.
Node.js
The code snippet below creates a google.auth.OAuth2
object, which defines the
parameters in the authorization request.
That object uses information from your client_secret.json file to identify your application. To ask for permissions from a user to retrieve an access token, you redirect them to a consent page. To create a consent page URL:
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 ditampilkan pada otorisasi pertama. Lihat detail selengkapnya
di sini.
HTTP/REST
Endpoint OAuth 2.0 Google berada 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 API Console Credentials page. |
||||||
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 konfigurasi di API Console
Credentials pageklien. Jika nilai ini tidak cocok dengan URI pengalihan yang diotorisasi untuk Perhatikan bahwa skema, kapitalisasi, dan garis miring di akhir |
||||||
response_type |
Wajib
Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Setel nilai parameter ke |
||||||
scope |
Wajib
Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna. Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukannya 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 untuk mendapatkan izin pengguna. Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi sesuai konteks jika memungkinkan. Dengan meminta akses ke data pengguna sesuai konteks, melalui otorisasi inkremental, Anda membantu pengguna agar lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta. |
||||||
access_type |
Direkomendasikan
Menunjukkan apakah aplikasi Anda dapat memuat ulang token akses saat pengguna tidak ada
di browser. Parameter value yang valid adalah Setel nilai ke |
||||||
state |
Direkomendasikan
Menentukan nilai string yang digunakan aplikasi Anda untuk mempertahankan status antara
permintaan otorisasi dan respons server otorisasi.
Server menampilkan nilai persis yang Anda kirim sebagai pasangan Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke
resource yang benar dalam aplikasi, mengirim nonce, dan memitigasi pemalsuan permintaan
lintas situs. Karena |
||||||
include_granted_scopes |
Opsional
Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan sesuai konteks. Jika Anda menetapkan nilai parameter ini ke |
||||||
enable_granular_consent |
Opsional
Default-nya adalah |
||||||
login_hint |
Opsional
Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi Anda dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login, baik dengan mengisi kolom email terlebih dahulu di formulir login, atau dengan memilih sesi multi-login yang sesuai. Tetapkan parameter value ke alamat email atau ID |
||||||
prompt |
Opsional
Daftar perintah yang dipisahkan spasi dan peka huruf besar/kecil untuk ditampilkan kepada pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan dimintai akses saat project Anda pertama kali meminta akses. Lihat Meminta izin ulang untuk informasi selengkapnya. Nilai yang dimungkinkan adalah:
|
Langkah 2: Alihkan ke server OAuth 2.0 Google
Alihkan pengguna ke server OAuth 2.0 Google untuk memulai proses autentikasi dan otorisasi. Biasanya, hal ini terjadi saat aplikasi Anda perlu mengakses data pengguna terlebih dahulu. Dalam kasus otorisasi inkremental, langkah ini juga terjadi saat aplikasi Anda perlu terlebih dahulu mengakses resource tambahan yang belum memiliki izin untuk diakses.
PHP
- Buat URL untuk meminta akses dari server OAuth 2.0 Google:
$auth_url = $client->createAuthUrl();
- 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
- Buat URL untuk meminta akses dari server OAuth 2.0 Google:
auth_uri = authorizer.get_authorization_url(login_hint: user_id, request: request)
- Alihkan pengguna ke
auth_uri
.
Node.js
-
Gunakan URL yang dihasilkan
authorizationUrl
dari metodegenerateAuthUrl
Langkah 1 untuk meminta akses dari server OAuth 2.0 Google. -
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 tersebut.
Server OAuth 2.0 Google mengautentikasi pengguna dan memperoleh izin dari pengguna untuk aplikasi Anda guna mengakses cakupan yang diminta. Responsnya dikirim kembali ke aplikasi Anda menggunakan URL alihan yang telah ditentukan.
Langkah 3: Google meminta izin pengguna
Pada langkah ini, pengguna memutuskan apakah akan memberikan akses yang diminta ke aplikasi Anda. Pada tahap ini, Google akan menampilkan jendela izin yang menampilkan nama aplikasi Anda dan layanan Google API yang meminta izin untuk diakses dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Kemudian, pengguna dapat mengizinkan 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 akses telah diberikan. Respons tersebut dijelaskan dalam langkah berikut.
Error
Permintaan ke endpoint otorisasi OAuth 2.0 Google mungkin 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. Baca artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal yang mengakses data Google Workspace untuk mengetahui 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 sebaiknya menggunakan library Android seperti Login dengan Google untuk Android atau AppAuth for Android dari OpenID Foundation.
Developer web mungkin mengalami error ini saat aplikasi Android 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 untuk dibuka 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 sebaiknya menggunakan library iOS seperti Login dengan Google untuk iOS atau AppAuth for 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 untuk dibuka di pengendali link default sistem operasi, yang menyertakan 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 mengetahui informasi selengkapnya tentang opsi konfigurasi ini, lihat bagian Jenis pengguna di artikel bantuan Menyiapkan layar izin OAuth.
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 sudah tidak berlaku atau tidak valid. Autentikasi pengguna lagi dan minta izin pengguna untuk mendapatkan token baru. Jika Anda terus melihat error ini, pastikan aplikasi telah dikonfigurasi dengan benar dan Anda menggunakan token dan 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 telah diberi otorisasi untuk client ID OAuth. Tinjau URI pengalihan yang diberi otorisasi di
Google API Console Credentials page.
Parameter redirect_uri
dapat merujuk pada alur out-of-band (OOB) OAuth yang tidak digunakan lagi dan tidak didukung lagi. Lihat
panduan migrasi untuk memperbarui
integrasi Anda.
invalid_request
Ada yang salah dengan permintaan yang Anda buat. Hal ini dapat disebabkan oleh sejumlah alasan:
- Permintaan tidak diformat dengan benar
- Permintaan tidak memiliki parameter yang diperlukan
- Permintaan menggunakan metode otorisasi yang tidak didukung oleh Google. Memastikan integrasi OAuth menggunakan metode integrasi yang direkomendasikan
Langkah 4: Tangani respons server OAuth 2.0
Server OAuth 2.0 merespons permintaan akses aplikasi Anda menggunakan URL yang ditentukan dalam permintaan tersebut.
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 ditampilkan ke server web muncul pada 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 kemungkinan akan menghasilkan
error 404 NOT FOUND
kecuali jika mesin lokal Anda menyalurkan file di alamat tersebut. Langkah berikutnya memberikan detail selengkapnya tentang informasi yang ditampilkan dalam URI saat pengguna dialihkan kembali ke aplikasi Anda.
Langkah 5: Tukar kode otorisasi untuk token refresh dan akses
Setelah menerima kode otorisasi, server web dapat menukar kode otorisasi 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
Pada halaman callback, gunakan library google-auth
untuk memverifikasi respons server otorisasi. Selanjutnya, 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
Pada halaman callback, gunakan library googleauth
untuk memverifikasi respons server
otorisasi. Gunakan metode authorizer.handle_auth_callback_deferred
untuk menyimpan
kode otorisasi dan mengalihkan kembali ke URL yang awalnya meminta otorisasi. Tindakan ini
menunda pertukaran kode dengan menyembunyikan hasil untuk sementara dalam sesi pengguna.
target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url
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 ditetapkan 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 dalam
API Console
Credentials page untuk
client_id yang ditentukan. |
Cuplikan berikut menunjukkan contoh permintaan:
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 berumur pendek dan token refresh.
Perlu diperhatikan bahwa token refresh hanya ditampilkan jika aplikasi Anda menetapkan parameter access_type
ke offline
dalam permintaan awal ke server otorisasi Google.
Respons berisi kolom berikut:
Kolom | |
---|---|
access_token |
Token yang dikirimkan aplikasi Anda untuk mengizinkan permintaan Google API. |
expires_in |
Sisa masa berlaku token akses 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 yang dinyatakan sebagai daftar string yang dipisahkan spasi dan peka huruf besar/kecil. |
token_type |
Jenis token yang ditampilkan. 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 dengan token akses, Anda mungkin mendapati error berikut, bukan respons yang diharapkan. Kode error umum dan resolusi yang disarankan tercantum di bawah ini.
invalid_grant
Kode otorisasi yang diberikan tidak valid atau formatnya salah. Minta kode baru dengan memulai ulang proses OAuth untuk meminta pengguna memberikan izin lagi.
Memanggil Google API
PHP
Gunakan token akses untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:
- Jika Anda perlu menerapkan token akses ke objek
Google\Client
baru — misalnya, jika Anda menyimpan token akses dalam sesi pengguna — gunakan metodesetAccessToken
:$client->setAccessToken($access_token);
- Buat objek layanan untuk API yang ingin Anda panggil. Anda mem-build objek layanan dengan memberikan objek
Google\Client
yang diotorisasi ke konstruktor untuk API yang ingin Anda panggil. Misalnya, untuk memanggil Drive API:$drive = new Google\Service\Drive($client);
- Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan.
Misalnya, untuk mencantumkan file di Google Drive pengguna yang diautentikasi:
$files = $drive->files->listFiles(array())->getItems();
Python
Setelah mendapatkan 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 mem-build objek layanan untuk API yang ingin Anda panggil, lalu gunakan objek tersebut untuk membuat permintaan API yang diotorisasi.
- Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan memanggil metode
build
librarygoogleapiclient.discovery
beserta nama dan versi API serta kredensial pengguna: Misalnya, untuk memanggil Drive API versi 3:from googleapiclient.discovery import build drive = build('drive', 'v2', credentials=credentials)
- Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan.
Misalnya, untuk mencantumkan file di Google Drive pengguna yang diautentikasi:
files = drive.files().list().execute()
Ruby
Setelah mendapatkan token akses, aplikasi Anda dapat menggunakan token tersebut untuk membuat permintaan API atas nama akun pengguna atau akun layanan tertentu. Gunakan kredensial otorisasi khusus pengguna untuk mem-build objek layanan untuk API yang ingin Anda panggil, lalu gunakan objek tersebut untuk membuat permintaan API yang diotorisasi.
- Buat objek layanan untuk API yang ingin Anda panggil.
Misalnya, untuk memanggil Drive API versi 3:
drive = Google::Apis::DriveV3::DriveService.new
- Tetapkan kredensial di layanan:
drive.authorization = credentials
- Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan.
Misalnya, untuk mencantumkan file di Google Drive pengguna yang diautentikasi:
files = drive.list_files
Atau, otorisasi dapat diberikan per metode dengan menyediakan
parameter options
ke suatu metode:
files = drive.list_files(options: { authorization: credentials })
Node.js
Setelah mendapatkan token akses dan menyetelnya ke objek OAuth2
, gunakan objek
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 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,
sebaiknya gunakan header HTTP, karena string kueri cenderung terlihat di log server. Pada umumnya, 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) menggunakan header HTTP Authorization: Bearer
mungkin terlihat seperti berikut. Perhatikan bahwa Anda harus 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 yang diautentikasi 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 disarankan):
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:
- Pada API Console, tambahkan URL komputer lokal ke daftar URL alihan. Misalnya, tambahkan
http://localhost:8080
. - Buat direktori baru dan ubah ke direktori tersebut. Contoh:
mkdir ~/php-oauth2-example cd ~/php-oauth2-example
- Instal Library Klien Google API untuk PHP menggunakan Composer:
composer require google/apiclient:^2.10
- Buat file
index.php
danoauth2callback.php
dengan konten di bawah ini. - Jalankan contoh dengan server web yang dikonfigurasi untuk menyalurkan 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 membuka URL tersebut, Anda akan melihat empat link:
- Menguji permintaan API: Link ini mengarah ke halaman yang mencoba menjalankan contoh permintaan API. Jika perlu, alur otorisasi akan dimulai. Jika berhasil, halaman akan menampilkan respons API.
- Uji 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. Hal ini memungkinkan Anda melihat apa yang akan terjadi jika pengguna yang telah memberikan izin ke aplikasi Anda mencoba menjalankan permintaan API dalam sesi baru. Tindakan ini juga memungkinkan Anda melihat respons API yang akan diperoleh aplikasi Anda jika pengguna telah mencabut izin yang diberikan ke aplikasi Anda, dan aplikasi Anda 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_v3' require 'sinatra' require 'googleauth' require 'googleauth/stores/redis_token_store' configure do enable :sessions set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json') set :scope, Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new) set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope, settings.token_store, '/oauth2callback') end get '/' do user_id = settings.client_id.id credentials = settings.authorizer.get_credentials(user_id, request) if credentials.nil? redirect settings.authorizer.get_authorization_url(login_hint: user_id, request: request) end drive = Google::Apis::DriveV3::DriveService.new files = drive.list_files(options: { authorization: credentials }) "<pre>#{JSON.pretty_generate(files.to_h)}</pre>" end get '/oauth2callback' do target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request) redirect target_url end
Node.js
Untuk menjalankan contoh ini:
-
Pada API Console, tambahkan URL
komputer lokal ke daftar URL alihan. Misalnya, tambahkan
http://localhost
. - Pastikan Anda telah menginstal LTS pemeliharaan, LTS aktif, atau rilis Node.js saat ini.
-
Buat direktori baru dan ubah ke direktori tersebut. Contoh:
mkdir ~/nodejs-oauth2-example cd ~/nodejs-oauth2-example
-
Install the
Google API Client
Library
for Node.js using npm:
npm install googleapis
-
Buat file
main.js
dengan konten di bawah ini. -
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 mendemonstrasikan 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 userinfo, 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. |
Pembawa Acara |
Host tidak boleh berupa alamat IP mentah. Alamat IP localhost dikecualikan dari aturan ini. |
Domain |
“googleusercontent.com” .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/” di jalurnya atau diakhiri dengan
“/google-callback” . |
Info pengguna |
URI pengalihan tidak boleh berisi subkomponen userinfo. |
Jalur |
URI pengalihan tidak boleh berisi path traversal (juga disebut backtracking direktori), yang diwakili oleh |
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:
|
Otorisasi inkremental
Pada protokol OAuth 2.0, aplikasi Anda meminta otorisasi untuk mengakses resource, yang diidentifikasi menurut cakupan. Meminta otorisasi untuk resource pada saat Anda membutuhkannya akan dianggap sebagai praktik pengalaman pengguna terbaik. Untuk memungkinkan praktik tersebut, server otorisasi Google mendukung otorisasi inkremental. Fitur ini memungkinkan Anda meminta cakupan sesuai kebutuhan dan, jika pengguna memberikan izin untuk cakupan yang baru, menampilkan kode otorisasi yang dapat ditukarkan dengan token yang berisi semua cakupan yang telah diberikan pengguna pada project.
Misalnya, aplikasi yang memungkinkan orang mengambil sampel trek musik dan membuat mix mungkin memerlukan resource yang sangat sedikit pada saat login, mungkin tidak lebih dari nama orang yang login. Namun, menyimpan mix yang sudah selesai akan memerlukan akses ke Google Drive mereka. Kebanyakan orang akan merasa hal itu wajar jika mereka hanya dimintai akses ke Google Drive pada saat aplikasi benar-benar memerlukannya.
Dalam hal ini, pada saat login, aplikasi mungkin meminta cakupan openid
dan
profile
untuk melakukan login dasar, lalu meminta
cakupan https://www.googleapis.com/auth/drive.file
pada saat permintaan pertama untuk menyimpan
campuran.
Untuk menerapkan otorisasi inkremental, selesaikan alur normal untuk meminta token akses, tetapi pastikan permintaan otorisasi menyertakan cakupan yang telah diberikan sebelumnya. Dengan pendekatan ini, aplikasi Anda tidak perlu mengelola beberapa token akses.
Aturan berikut berlaku untuk token akses yang diperoleh dari otorisasi inkremental:
- Token ini dapat digunakan untuk mengakses resource yang sesuai dengan salah satu cakupan yang digabungkan ke dalam otorisasi gabungan baru.
- Saat Anda menggunakan token refresh untuk otorisasi gabungan guna mendapatkan token akses, token akses merepresentasikan otorisasi gabungan dan dapat digunakan untuk setiap nilai
scope
yang disertakan dalam respons. - Otorisasi gabungan mencakup semua cakupan yang diberikan pengguna ke project API, meskipun jika pemberian izin diminta dari klien yang berbeda. Misalnya, jika pengguna memberikan akses ke satu cakupan menggunakan klien desktop aplikasi, lalu memberikan cakupan lain ke aplikasi yang sama melalui klien seluler, otorisasi gabungan akan mencakup 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 di Langkah 1: Tetapkan parameter otorisasi dan contoh URL alihan HTTP/REST di Langkah 2: Alihkan ke server OAuth 2.0 Google, semuanya menggunakan otorisasi tambahan. Contoh kode di bawah ini 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 satu-satunya argumen kata kunci 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)
Token akses akan habis masa berlakunya secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat me-refresh token akses tanpa meminta izin kepada pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token tersebut.
- 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 perlu menetapkan parameter kueri HTTP
access_type
keoffline
saat mengalihkan pengguna ke server OAuth 2.0 Google. Dalam hal ini, server otorisasi Google akan menampilkan token refresh saat Anda menukar 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 saat pengguna tidak ada. Misalnya, aplikasi yang menjalankan layanan pencadangan atau
menjalankan tindakan pada waktu yang telah ditentukan harus dapat memperbarui token aksesnya
jika pengguna tidak ada. Gaya akses default disebut online
.
Aplikasi web sisi server, aplikasi terinstal, dan perangkat semuanya mendapatkan 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 akan dapat me-refresh token akses tanpa harus meminta izin kembali kepada pengguna. Sangat mungkin bahwa access_type
tidak akan menjadi satu-satunya argumen kata kunci 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 habis. 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 memberi aplikasi izin yang diperlukan
tanpa menetapkan batasan yang sesuai untuk menerima token refresh, Anda perlu
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 dimuat ulang 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 ditetapkan dalam
spesifikasi OAuth 2.0,
nilai kolom ini harus ditetapkan ke refresh_token . |
refresh_token |
Token refresh yang ditampilkan dari pertukaran kode otorisasi. |
Cuplikan berikut menunjukkan contoh permintaan:
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 belum 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" }
Perlu diperhatikan bahwa ada batasan jumlah token refresh yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu batas per pengguna di semua klien. Anda harus menyimpan token refresh dalam penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika aplikasi Anda meminta terlalu banyak token refresh, aplikasi tersebut mungkin akan mencapai batas ini, 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 akses situs atau aplikasi di Dokumen dukungan Situs & aplikasi pihak ketiga yang memiliki akses ke akun Anda untuk mengetahui informasi selengkapnya.
Aplikasi juga mungkin mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram sangat penting 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 menyertakan permintaan API untuk memastikan izin yang sebelumnya diberikan kepada 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 tersebut 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
akan 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
akan ditampilkan bersama dengan
kode error.
HTTP/REST
Untuk mencabut token secara terprogram, aplikasi Anda akan membuat permintaan ke
https://oauth2.googleapis.com/revoke
dan menyertakan token sebagai parameter:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \ https://oauth2.googleapis.com/revoke?token={token}
Token tersebut dapat berupa token akses atau token refresh. Jika token ini adalah token akses dan memiliki token refresh yang terkait, token refresh juga akan dicabut.
Jika pencabutan berhasil diproses, kode status HTTP untuk respons tersebut adalah
200
. Untuk kondisi error, kode status HTTP 400
akan ditampilkan bersama
dengan kode error.