Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses Google API dari aplikasi web JavaScript. OAuth 2.0 memungkinkan pengguna berbagi data tertentu dengan aplikasi sambil menjaga kerahasiaan nama pengguna, sandi, dan informasi lainnya. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna guna menyimpan file di Google Drive.
Alur OAuth 2.0 ini disebut alur pemberian implisit. Dirancang untuk aplikasi yang hanya mengakses API saat pengguna ada di aplikasi. Aplikasi ini tidak dapat menyimpan informasi rahasia.
Dalam alur ini, aplikasi Anda akan membuka URL Google yang menggunakan parameter kueri untuk mengidentifikasi aplikasi dan jenis akses API yang diperlukan aplikasi. Anda dapat membuka URL di jendela browser saat ini atau pop-up. Pengguna dapat melakukan autentikasi dengan Google dan memberikan izin yang diminta. Google kemudian mengalihkan pengguna kembali ke aplikasi Anda. Pengalihan ini mencakup token akses, yang diverifikasi aplikasi Anda lalu digunakan untuk membuat permintaan API.
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 mencarinya, atau klik Lihat Semua dalam kategori 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
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.
- Go to the Credentials page.
- Klik Create credentials > OAuth client ID.
- Pilih jenis aplikasi Aplikasi web.
- Lengkapi formulir. Aplikasi yang menggunakan JavaScript untuk membuat permintaan Google API yang diotorisasi harus menentukan asal JavaScript yang diotorisasi. Asal mengidentifikasi domain tempat aplikasi Anda dapat mengirim permintaan ke server OAuth 2.0. Asal ini harus mematuhi aturan validasi Google.
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.
Dokumen Cakupan API OAuth 2.0 berisi daftar lengkap cakupan yang mungkin Anda gunakan untuk mengakses Google API.
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.
Langkah 1: Konfigurasikan objek klien
Jika Anda menggunakan library klien Google API untuk JavaScript untuk menangani alur OAuth 2.0, langkah pertama Anda adalah mengonfigurasi objek gapi.auth2
dan gapi.client
. Objek ini memungkinkan aplikasi Anda mendapatkan otorisasi pengguna dan membuat permintaan API yang diotorisasi.
Objek klien mengidentifikasi cakupan yang diminta oleh aplikasi Anda untuk diakses. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna.
Library Klien JS
Library klien JavaScript menyederhanakan banyak aspek proses otorisasi:
- Tindakan ini membuat URL alihan untuk server otorisasi Google dan menyediakan metode untuk mengarahkan pengguna ke URL tersebut.
- Lapisan ini menangani pengalihan dari server tersebut kembali ke aplikasi Anda.
- Metode ini memvalidasi token akses yang ditampilkan oleh server otorisasi.
- Cloud Firestore menyimpan token akses yang dikirim server otorisasi ke aplikasi Anda dan mengambilnya saat aplikasi Anda kemudian melakukan panggilan API yang diotorisasi.
Cuplikan kode di bawah ini adalah nukilan dari contoh lengkap yang ditampilkan nanti
dalam dokumen ini. Kode ini melakukan inisialisasi objek gapi.client
, yang nantinya akan digunakan aplikasi Anda untuk melakukan panggilan API. Saat objek tersebut dibuat, objek
gapi.auth2
, yang digunakan aplikasi Anda untuk memeriksa dan memantau status otorisasi
pengguna, juga diinisialisasi.
Panggilan ke gapi.client.init
menentukan kolom berikut:
- Nilai
apiKey
danclientId
menentukan kredensial otorisasi aplikasi Anda. Seperti yang dibahas di bagian membuat kredensial otorisasi, nilai ini dapat diperoleh di API Console. Perhatikan bahwaclientId
diperlukan jika aplikasi Anda membuat permintaan API yang diotorisasi. Aplikasi yang hanya membuat permintaan yang tidak sah dapat hanya menentukan kunci API. -
Kolom
scope
menentukan daftar cakupan akses yang dipisahkan spasi yang sesuai dengan resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini akan menginformasikan layar izin yang ditampilkan Google kepada 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 akan membantu pengguna untuk lebih memahami alasan aplikasi Anda memerlukan akses yang diminta.
- Kolom
discoveryDocs
mengidentifikasi daftar dokumen Discovery API yang digunakan aplikasi Anda. Dokumen Discovery menjelaskan platform API, termasuk skema resource-nya, dan library klien JavaScript menggunakan informasi tersebut untuk menghasilkan metode yang dapat digunakan aplikasi. Dalam contoh ini, kode mengambil dokumen penemuan untuk Google Drive API versi 3.
Setelah panggilan gapi.client.init
selesai, kode akan menetapkan variabel GoogleAuth
untuk mengidentifikasi objek Google Auth. Terakhir, kode tersebut menetapkan pemroses yang memanggil fungsi saat status login pengguna berubah. (Fungsi tersebut tidak ditetapkan dalam
cuplikan.)
var GoogleAuth; // Google Auth object. function initClient() { gapi.client.init({ 'apiKey': 'YOUR_API_KEY', 'clientId': 'YOUR_CLIENT_ID', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly', 'discoveryDocs': ['https://www.googleapis.com/discovery/v1/apis/drive/v3/rest'] }).then(function () { GoogleAuth = gapi.auth2.getAuthInstance(); // Listen for sign-in state changes. GoogleAuth.isSignedIn.listen(updateSigninStatus); }); }
Endpoint OAuth 2.0
Jika Anda langsung mengakses endpoint OAuth 2.0, Anda dapat melanjutkan ke langkah berikutnya.
Langkah 2: Alihkan ke server OAuth 2.0 Google
Untuk meminta izin mengakses data pengguna, alihkan pengguna ke server OAuth 2.0 Google.
Library Klien JS
Panggil metode GoogleAuth.signIn()
untuk mengarahkan pengguna ke server otorisasi Google.
GoogleAuth.signIn();
Dalam praktiknya, aplikasi Anda mungkin menetapkan nilai Boolean untuk menentukan apakah akan memanggil metode signIn()
sebelum mencoba melakukan panggilan API.
Cuplikan kode di bawah menunjukkan cara Anda akan memulai alur otorisasi pengguna. Perhatikan poin-poin berikut tentang cuplikan:
-
Objek
GoogleAuth
yang direferensikan dalam kode sama dengan variabel global yang ditentukan dalam cuplikan kode di langkah 1. - Fungsi
updateSigninStatus
adalah pemroses yang memproses perubahan pada status otorisasi pengguna. Perannya sebagai pemroses juga ditentukan dalam cuplikan kode di langkah 1:GoogleAuth.isSignedIn.listen(updateSigninStatus);
Cuplikan ini menentukan dua variabel global tambahan:
isAuthorized
adalah variabel Boolean yang menunjukkan apakah pengguna sudah login atau belum. Nilai ini dapat ditetapkan saat aplikasi dimuat dan diperbarui jika pengguna login atau logout dari aplikasi.Dalam cuplikan ini, fungsi
sendAuthorizedApiRequest
memeriksa nilai variabel untuk menentukan apakah aplikasi harus mencoba permintaan API yang memerlukan otorisasi atau meminta pengguna untuk mengizinkan aplikasi.currentApiRequest
adalah objek yang menyimpan detail tentang permintaan API terakhir yang dicoba oleh pengguna. Nilai objek ditetapkan saat aplikasi memanggil fungsisendAuthorizedApiRequest
.Jika pengguna telah mengizinkan aplikasi, permintaan akan segera dieksekusi. Jika tidak, fungsi itu akan mengalihkan pengguna untuk login. Setelah pengguna login, fungsi
updateSignInStatus
memanggilsendAuthorizedApiRequest
, yang meneruskan permintaan yang sama dengan yang dicoba sebelum alur otorisasi dimulai.
var isAuthorized; var currentApiRequest; /** * Store the request details. Then check to determine whether the user * has authorized the application. * - If the user has granted access, make the API request. * - If the user has not granted access, initiate the sign-in flow. */ function sendAuthorizedApiRequest(requestDetails) { currentApiRequest = requestDetails; if (isAuthorized) { // Make API request // gapi.client.request(requestDetails) // Reset currentApiRequest variable. currentApiRequest = {}; } else { GoogleAuth.signIn(); } } /** * Listener called when user completes auth flow. If the currentApiRequest * variable is set, then the user was prompted to authorize the application * before the request executed. In that case, proceed with that API request. */ function updateSigninStatus(isSignedIn) { if (isSignedIn) { isAuthorized = true; if (currentApiRequest) { sendAuthorizedApiRequest(currentApiRequest); } } else { isAuthorized = false; } }
Endpoint OAuth 2.0
Buat URL untuk meminta akses dari endpoint OAuth 2.0 Google di
https://accounts.google.com/o/oauth2/v2/auth
. Endpoint ini 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 Perhatikan bahwa skema, kasus, dan garis miring ( |
||||||
response_type |
Wajib
Aplikasi JavaScript perlu menetapkan nilai parameter ke |
||||||
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. |
||||||
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 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 |
||||||
include_granted_scopes |
Opsional
Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan
tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke |
||||||
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 |
||||||
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:
|
Contoh pengalihan ke server otorisasi Google
Contoh URL ditampilkan di bawah ini, dengan baris baru dan spasi untuk keterbacaan.
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Setelah Anda membuat URL permintaan, alihkan pengguna ke URL URL.
Kode contoh JavaScript
Cuplikan JavaScript berikut menunjukkan cara memulai alur otorisasi di JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Karena endpoint OAuth 2.0 ini tidak mendukung Cross-Origin Resource Sharing (CORS), cuplikan akan membuat formulir yang membuka permintaan ke endpoint tersebut.
/* * Create form to request access token from Google's OAuth 2.0 server. */ function oauthSignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create <form> element to submit parameters to OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': 'YOUR_CLIENT_ID', 'redirect_uri': 'YOUR_REDIRECT_URI', 'response_type': 'token', 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly', 'include_granted_scopes': 'true', 'state': 'pass-through value'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); }
Langkah 3: Google 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
Asal permintaan dibuat tidak diizinkan untuk klien ini. Lihat
origin_mismatch
.
invalid_grant
Saat menggunakan otorisasi inkremental, token mungkin telah habis masa berlakunya atau telah dibatalkan validasinya. 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.
origin_mismatch
Skema, domain, dan/atau port JavaScript yang berasal dari permintaan otorisasi mungkin tidak cocok dengan URI asal JavaScript resmi yang terdaftar untuk client ID OAuth. Tinjau asal JavaScript yang diizinkan di Google API Console Credentials page.
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.
Skema, domain, dan/atau port JavaScript yang berasal dari permintaan otorisasi mungkin tidak cocok dengan URI asal JavaScript resmi yang terdaftar untuk client ID OAuth. Tinjau asal JavaScript resmi 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
Library Klien JS
Library klien JavaScript menangani respons dari server otorisasi Google. Jika Anda menetapkan pemroses untuk memantau perubahan status login pengguna saat ini, fungsi tersebut akan dipanggil saat pengguna memberikan akses yang diminta ke aplikasi.
Endpoint OAuth 2.0
Server OAuth 2.0 mengirimkan respons ke redirect_uri
yang ditentukan dalam permintaan token akses Anda.
Jika pengguna menyetujui permintaan, respons akan berisi token akses. Jika pengguna tidak menyetujui permintaan tersebut, respons akan berisi pesan error. Token akses atau pesan error ditampilkan pada fragmen hash URI pengalihan, seperti yang ditunjukkan di bawah ini:
Respons token akses:
https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600
Selain parameter
access_token
, string fragmen juga berisi parametertoken_type
, yang selalu ditetapkan keBearer
, dan parameterexpires_in
, yang menentukan masa berlaku token, dalam detik. Jika parameterstate
ditentukan dalam permintaan token akses, nilainya juga akan disertakan dalam respons.- Respons error:
https://oauth2.example.com/callback#error=access_denied
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& include_granted_scopes=true& response_type=token& state=state_parameter_passthrough_value& redirect_uri=https%3A//oauth2.example.com/code& client_id=client_id
Setelah menyelesaikan alur OAuth 2.0, Anda akan dialihkan ke
http://localhost/oauth2callback
. URL tersebut akan menghasilkan error 404 NOT FOUND
kecuali jika komputer lokal Anda menyajikan file di alamat tersebut. Langkah berikutnya memberikan detail lebih lanjut tentang informasi yang ditampilkan dalam URI saat pengguna dialihkan kembali ke aplikasi Anda.
Memanggil Google API
Library Klien JS
Setelah aplikasi mendapatkan token akses, Anda dapat menggunakan library klien JavaScript untuk membuat permintaan API atas nama pengguna. Library klien mengelola token akses untuk Anda, dan Anda tidak perlu melakukan tindakan khusus untuk mengirimnya dalam permintaan.
Library klien mendukung dua cara untuk memanggil metode API. Jika Anda telah memuat dokumen penemuan, API akan menentukan fungsi khusus metode untuk Anda. Anda juga dapat menggunakan
fungsi gapi.client.request
untuk memanggil metode API.
Dua cuplikan berikut menunjukkan opsi ini untuk metode about.get
Drive API.
// Example 1: Use method-specific function var request = gapi.client.drive.about.get({'fields': 'user'}); // Execute the API request. request.execute(function(response) { console.log(response); }); // Example 2: Use gapi.client.request(args) function var request = gapi.client.request({ 'method': 'GET', 'path': '/drive/v3/about', 'params': {'fields': 'user'} }); // Execute the API request. request.execute(function(response) { console.log(response); });
Endpoint OAuth 2.0
Setelah aplikasi Anda mendapatkan token akses, Anda dapat menggunakan token tersebut untuk melakukan panggilan ke Google API atas nama akun pengguna tertentu jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk 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
Kode contoh JavaScript
Cuplikan kode di bawah ini menunjukkan cara menggunakan CORS (Cross-origin resource sharing) untuk mengirim permintaan ke Google API. Contoh ini tidak menggunakan Library Klien Google API untuk JavaScript. Namun, meskipun Anda tidak menggunakan library klien, panduan dukungan CORS dalam dokumentasi library tersebut kemungkinan akan membantu Anda lebih memahami permintaan ini.
Dalam cuplikan kode ini, variabel access_token
mewakili token yang telah Anda peroleh untuk membuat permintaan API atas nama pengguna yang diotorisasi. Contoh
lengkap menunjukkan cara menyimpan token tersebut di penyimpanan lokal browser dan mengambilnya
saat membuat permintaan API.
var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Contoh lengkap
Library Klien JS
Demo kode contoh
Bagian ini berisi demo cara kerja contoh kode berikut untuk menunjukkan perilaku kode dalam aplikasi yang sebenarnya. Setelah Anda memberikan otorisasi, aplikasi akan tercantum dalam aplikasi yang terhubung ke Akun Google Anda. Aplikasi ini diberi nama OAuth 2.0 Demo for Google API Docs. Demikian pula, jika Anda mencabut akses dan memuat ulang halaman tersebut, aplikasi tersebut tidak akan lagi tercantum.
Perhatikan bahwa aplikasi ini meminta akses ke cakupan https://www.googleapis.com/auth/drive.metadata.readonly
. Akses
hanya diminta untuk menunjukkan cara memulai alur OAuth 2.0 di aplikasi JavaScript.
Aplikasi ini tidak membuat permintaan API apa pun.
Kode contoh JavaScript
Seperti yang ditunjukkan di atas, contoh kode ini ditujukan untuk halaman (aplikasi) yang memuat Library Klien Google API untuk JavaScript dan memulai alur OAuth 2.0. Halaman akan menampilkan:
- Satu tombol yang memungkinkan pengguna login ke aplikasi. Jika pengguna belum memberi otorisasi aplikasi sebelumnya, aplikasi akan meluncurkan alur OAuth 2.0.
- Dua tombol yang memungkinkan pengguna untuk logout dari aplikasi atau mencabut akses yang sebelumnya diberikan ke aplikasi. Jika Anda logout dari aplikasi, Anda belum mencabut akses yang diberikan ke aplikasi. Anda harus login lagi sebelum aplikasi dapat membuat permintaan resmi lainnya atas nama Anda, tetapi Anda tidak perlu memberikan akses lagi saat menggunakan aplikasi ini lagi. Namun, jika Anda mencabut akses, maka Anda harus memberikan akses lagi.
Anda juga dapat mencabut akses ke aplikasi melalui halaman Izin untuk Akun Google Anda. Aplikasi tersebut tercantum sebagai OAuth 2.0 Demo for Google API Docs.
<script> var GoogleAuth; var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; function handleClientLoad() { // Load the API's client and auth2 modules. // Call the initClient function after the modules load. gapi.load('client:auth2', initClient); } function initClient() { // In practice, your app can retrieve one or more discovery documents. var discoveryUrl = 'https://www.googleapis.com/discovery/v1/apis/drive/v3/rest'; // Initialize the gapi.client object, which app uses to make API requests. // Get API key and client ID from API Console. // 'scope' field specifies space-delimited list of access scopes. gapi.client.init({ 'apiKey': 'YOUR_API_KEY', 'clientId': 'YOUR_CLIENT_ID', 'discoveryDocs': [discoveryUrl], 'scope': SCOPE }).then(function () { GoogleAuth = gapi.auth2.getAuthInstance(); // Listen for sign-in state changes. GoogleAuth.isSignedIn.listen(updateSigninStatus); // Handle initial sign-in state. (Determine if user is already signed in.) var user = GoogleAuth.currentUser.get(); setSigninStatus(); // Call handleAuthClick function when user clicks on // "Sign In/Authorize" button. $('#sign-in-or-out-button').click(function() { handleAuthClick(); }); $('#revoke-access-button').click(function() { revokeAccess(); }); }); } function handleAuthClick() { if (GoogleAuth.isSignedIn.get()) { // User is authorized and has clicked "Sign out" button. GoogleAuth.signOut(); } else { // User is not signed in. Start Google auth flow. GoogleAuth.signIn(); } } function revokeAccess() { GoogleAuth.disconnect(); } function setSigninStatus() { var user = GoogleAuth.currentUser.get(); var isAuthorized = user.hasGrantedScopes(SCOPE); if (isAuthorized) { $('#sign-in-or-out-button').html('Sign out'); $('#revoke-access-button').css('display', 'inline-block'); $('#auth-status').html('You are currently signed in and have granted ' + 'access to this app.'); } else { $('#sign-in-or-out-button').html('Sign In/Authorize'); $('#revoke-access-button').css('display', 'none'); $('#auth-status').html('You have not authorized this app or you are ' + 'signed out.'); } } function updateSigninStatus() { setSigninStatus(); } </script> <button id="sign-in-or-out-button" style="margin-left: 25px">Sign In/Authorize</button> <button id="revoke-access-button" style="display: none; margin-left: 25px">Revoke access</button> <div id="auth-status" style="display: inline; padding-left: 25px"></div><hr> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> <script async defer src="https://apis.google.com/js/api.js" onload="this.onload=function(){};handleClientLoad()" onreadystatechange="if (this.readyState === 'complete') this.onload()"> </script>
Endpoint OAuth 2.0
Contoh kode ini menunjukkan cara menyelesaikan alur OAuth 2.0 di JavaScript tanpa menggunakan Library Klien Google API untuk JavaScript. Kode ini untuk halaman HTML yang menampilkan tombol untuk mencoba permintaan API. Jika Anda mengklik tombol, kode akan memeriksa untuk melihat apakah halaman telah menyimpan token akses API di penyimpanan lokal browser. Jika ya, permintaan API akan dieksekusi. Jika tidak, metode ini akan memulai alur OAuth 2.0.
Untuk alur OAuth 2.0, halaman ini mengikuti langkah-langkah berikut:
- Fungsi ini mengarahkan pengguna ke server OAuth 2.0 Google, yang meminta akses ke
cakupan
https://www.googleapis.com/auth/drive.metadata.readonly
. - Setelah memberikan (atau menolak) akses ke satu atau beberapa cakupan yang diminta, pengguna akan dialihkan ke halaman asli, yang akan mengurai token akses dari string ID fragmen.
Halaman tersebut menggunakan token akses untuk membuat permintaan API contoh.
Permintaan API memanggil metode
about.get
Drive API untuk mengambil informasi tentang akun Google Drive pengguna yang diotorisasi.- Jika permintaan berhasil dieksekusi, respons API dicatat di konsol debug browser.
Anda dapat mencabut akses ke aplikasi melalui halaman Izin untuk Akun Google Anda. Aplikasi akan dicantumkan sebagai Demo OAuth 2.0 untuk Dokumen Google API.
Untuk menjalankan kode ini secara lokal, Anda perlu menetapkan nilai untuk variabel YOUR_CLIENT_ID
dan
YOUR_REDIRECT_URI
yang sesuai dengan
kredensial otorisasi Anda. Variabel YOUR_REDIRECT_URI
harus ditetapkan ke URL yang sama tempat halaman ditayangkan. Nilai harus sama persis dengan salah satu
URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di
API Console Credentials page. Jika
nilai ini tidak cocok dengan URI yang diberi otorisasi, Anda akan mendapatkan error redirect_uri_mismatch
. Project Anda juga harus
mengaktifkan API yang sesuai untuk permintaan ini.
<html><head></head><body> <script> var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE'; var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE'; var fragmentString = location.hash.substring(1); // Parse query string to see if page request is coming from OAuth 2.0 server. var params = {}; var regex = /([^&=]+)=([^&]*)/g, m; while (m = regex.exec(fragmentString)) { params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]); } if (Object.keys(params).length > 0) { localStorage.setItem('oauth2-test-params', JSON.stringify(params) ); if (params['state'] && params['state'] == 'try_sample_request') { trySampleRequest(); } } // If there's an access token, try an API request. // Otherwise, start OAuth 2.0 flow. function trySampleRequest() { var params = JSON.parse(localStorage.getItem('oauth2-test-params')); if (params && params['access_token']) { var xhr = new XMLHttpRequest(); xhr.open('GET', 'https://www.googleapis.com/drive/v3/about?fields=user&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { if (xhr.readyState === 4 && xhr.status === 200) { console.log(xhr.response); } else if (xhr.readyState === 4 && xhr.status === 401) { // Token invalid, so prompt for user permission. oauth2SignIn(); } }; xhr.send(null); } else { oauth2SignIn(); } } /* * Create form to request access token from Google's OAuth 2.0 server. */ function oauth2SignIn() { // Google's OAuth 2.0 endpoint for requesting an access token var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth'; // Create element to open OAuth 2.0 endpoint in new window. var form = document.createElement('form'); form.setAttribute('method', 'GET'); // Send as a GET request. form.setAttribute('action', oauth2Endpoint); // Parameters to pass to OAuth 2.0 endpoint. var params = {'client_id': YOUR_CLIENT_ID, 'redirect_uri': YOUR_REDIRECT_URI, 'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly', 'state': 'try_sample_request', 'include_granted_scopes': 'true', 'response_type': 'token'}; // Add form parameters as hidden input values. for (var p in params) { var input = document.createElement('input'); input.setAttribute('type', 'hidden'); input.setAttribute('name', p); input.setAttribute('value', params[p]); form.appendChild(input); } // Add form to page and submit it to open the OAuth 2.0 endpoint. document.body.appendChild(form); form.submit(); } </script> <button onclick="trySampleRequest();">Try sample request</button> </body></html>
Aturan validasi asal JavaScript
Google menerapkan aturan validasi berikut ke asal JavaScript untuk membantu developer menjaga keamanan aplikasinya. Asal JavaScript Anda harus mematuhi aturan ini. Lihat RFC 3986 bagian 3 untuk definisi domain, host, dan skema, yang disebutkan di bawah.
Aturan validasi | |
---|---|
Skema |
Asal JavaScript 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 |
“googleusercontent.com” .goo.gl )
kecuali jika aplikasi memiliki domain tersebut. |
Info pengguna |
Asal JavaScript tidak boleh berisi subkomponen userinfo. |
Jalur |
Asal JavaScript tidak boleh berisi komponen jalur. |
Kueri |
Asal JavaScript tidak boleh berisi komponen kueri. |
Fragment |
Asal JavaScript tidak boleh berisi komponen fragmen. |
Karakter |
Asal JavaScript tidak boleh berisi karakter tertentu, termasuk:
|
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.
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 di bawah ini menunjukkan cara menambahkan cakupan ke token akses yang ada. Pendekatan ini memungkinkan aplikasi Anda menghindari pengelolaan beberapa token akses.
Library Klien JS
Untuk menambahkan cakupan ke token akses yang ada, panggil metode GoogleUser.grant(options)
. Objek options
mengidentifikasi cakupan tambahan yang ingin Anda berikan akses.
// Space-separated list of additional scope(s) you are requesting access to. // This code adds read-only access to the user's calendars via the Calendar API. var NEW_SCOPES = 'https://www.googleapis.com/auth/calendar.readonly'; // Retrieve the GoogleUser object for the current user. var GoogleUser = GoogleAuth.currentUser.get(); GoogleUser.grant({'scope': NEW_SCOPES});
Endpoint OAuth 2.0
Untuk menambahkan cakupan ke token akses yang ada, sertakan parameter include_granted_scopes
dalam permintaan ke server OAuth 2.0 Google.
Cuplikan kode berikut menunjukkan cara melakukannya. Cuplikan tersebut mengasumsikan bahwa Anda telah menyimpan cakupan yang valid untuk token akses Anda di penyimpanan lokal browser. (Kode contoh lengkap menyimpan daftar cakupan yang token akses-nya valid dengan menetapkan properti oauth2-test-params.scope
di penyimpanan lokal browser.)
Cuplikan membandingkan cakupan yang memiliki token akses yang valid dengan cakupan yang ingin digunakan untuk kueri tertentu. Jika token akses tidak mencakup cakupan tersebut, alur OAuth 2.0 akan dimulai.
Di sini, fungsi oauth2SignIn
sama dengan yang disediakan dalam
langkah 2 (dan yang disediakan nanti dalam contoh
lengkap).
var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly'; var params = JSON.parse(localStorage.getItem('oauth2-test-params')); var current_scope_granted = false; if (params.hasOwnProperty('scope')) { var scopes = params['scope'].split(' '); for (var s = 0; s < scopes.length; s++) { if (SCOPE == scopes[s]) { current_scope_granted = true; } } } if (!current_scope_granted) { oauth2SignIn(); // This function is defined elsewhere in this document. } else { // Since you already have access, you can proceed with the API request. }
Mencabut token
Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. 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.
Library Klien JS
Untuk mencabut token secara terprogram, panggil
GoogleAuth.disconnect()
:
GoogleAuth.disconnect();
Endpoint OAuth 2.0
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.
Cuplikan JavaScript berikut menunjukkan cara mencabut token di JavaScript tanpa menggunakan
Library Klien Google API untuk JavaScript. Karena endpoint OAuth 2.0 Google untuk mencabut
token tidak mendukung Cross-origin Resource Sharing (CORS), kode akan membuat formulir dan mengirimkan
formulir tersebut ke endpoint, bukan menggunakan metode XMLHttpRequest()
untuk memposting
permintaan.
function revokeAccess(accessToken) { // Google's OAuth 2.0 endpoint for revoking access tokens. var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke'; // Create <form> element to use to POST data to the OAuth 2.0 endpoint. var form = document.createElement('form'); form.setAttribute('method', 'post'); form.setAttribute('action', revokeTokenEndpoint); // Add access token to the form so it is set as value of 'token' parameter. // This corresponds to the sample curl request, where the URL is: // https://oauth2.googleapis.com/revoke?token={token} var tokenField = document.createElement('input'); tokenField.setAttribute('type', 'hidden'); tokenField.setAttribute('name', 'token'); tokenField.setAttribute('value', accessToken); form.appendChild(tokenField); // Add form to page and submit it to actually revoke the token. document.body.appendChild(form); form.submit(); }