Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses YouTube Analytics API atau YouTube Reporting API dari aplikasi web JavaScript. OAuth 2.0 memungkinkan pengguna 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 guna mengambil data YouTube Analytics channel.
Alur OAuth 2.0 ini disebut alur pemberian implisit. API ini dirancang untuk aplikasi yang hanya mengakses API saat pengguna berada 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 Anda dan jenis akses API yang diperlukan aplikasi. Anda dapat membuka URL di jendela browser atau pop-up saat ini. Pengguna dapat mengautentikasi dengan Google dan memberikan izin yang diminta. Google kemudian mengalihkan pengguna kembali ke aplikasi Anda. Pengalihan ini menyertakan token akses, yang diverifikasi oleh aplikasi Anda, lalu digunakan untuk membuat permintaan API.
Library Klien Google API dan Layanan Identitas Google
Jika menggunakan library klien Google API untuk JavaScript untuk melakukan panggilan yang diotorisasi ke Google, Anda harus menggunakan library JavaScript Google Identity Services untuk menangani alur OAuth 2.0. Lihat model token Layanan Identitas Google, yang didasarkan pada alur pemberian implisit OAuth 2.0.
Prasyarat
Mengaktifkan API untuk project Anda
Setiap aplikasi yang memanggil Google API harus mengaktifkan API tersebut di .
Untuk mengaktifkan API untuk project Anda:
- di .
- Gunakan halaman Library untuk menemukan dan mengaktifkan YouTube Analytics API dan YouTube Reporting API. Banyak aplikasi yang mengambil data YouTube Analytics juga memiliki antarmuka dengan YouTube Data API. Temukan API lain yang akan digunakan aplikasi Anda dan aktifkan juga API tersebut.
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. Kemudian, aplikasi Anda dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk project tersebut.
- Klik Create credentials > OAuth client ID.
- Pilih jenis aplikasi Aplikasi web.
- Isi formulir. Aplikasi yang menggunakan JavaScript untuk membuat permintaan Google API resmi harus menentukan asal JavaScript resmi. Origin mengidentifikasi domain tempat aplikasi Anda dapat mengirim permintaan ke server OAuth 2.0. Origin 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 mereka berikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.
Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya identifikasi cakupan yang memerlukan izin akses aplikasi Anda.
YouTube Analytics API menggunakan cakupan berikut:
| Cakupan | |
|---|---|
| https://www.googleapis.com/auth/youtube | Mengelola akun YouTube Anda |
| https://www.googleapis.com/auth/youtube.readonly | Melihat akun YouTube Anda |
| https://www.googleapis.com/auth/youtubepartner | Melihat dan mengelola aset Anda dan konten terkait di YouTube |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Melihat laporan moneter dan non-moneter YouTube Analytics untuk konten YouTube Anda |
| https://www.googleapis.com/auth/yt-analytics.readonly | Melihat laporan YouTube Analytics untuk konten YouTube Anda |
YouTube Reporting API menggunakan cakupan berikut:
| Cakupan | |
|---|---|
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Melihat laporan moneter dan non-moneter YouTube Analytics untuk konten YouTube Anda |
| https://www.googleapis.com/auth/yt-analytics.readonly | Melihat laporan YouTube Analytics untuk konten YouTube Anda |
Dokumen Cakupan API OAuth 2.0 berisi daftar lengkap cakupan yang dapat 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 guna melakukan permintaan API atas nama pengguna. Aplikasi Anda harus memiliki izin tersebut sebelum dapat menjalankan permintaan Google API yang memerlukan otorisasi pengguna.
Langkah 1: Alihkan ke server OAuth 2.0 Google
Untuk meminta izin guna mengakses data pengguna, alihkan pengguna ke server OAuth 2.0 Google.
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 . |
||||||||||||||||||
redirect_uri |
Wajib
Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan
alur otorisasi. Nilai ini harus sama persis dengan salah satu URI alihan yang diotorisasi untuk
klien OAuth 2.0, yang Anda konfigurasikan di
klien. Jika nilai ini tidak cocok dengan URI pengalihan resmi untuk Perhatikan bahwa skema, huruf besar/kecil, dan garis miring akhir |
||||||||||||||||||
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 menginformasikan 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 mereka berikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna. YouTube Analytics API menggunakan cakupan berikut:
YouTube Reporting API menggunakan cakupan berikut:
Dokumen Cakupan API OAuth 2.0 memberikan daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API. Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks jika memungkinkan. Dengan meminta akses ke data pengguna sesuai konteks, melalui otorisasi inkremental, Anda membantu pengguna lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta. |
||||||||||||||||||
state |
Direkomendasikan
Menentukan nilai string apa pun 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 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 |
||||||||||||||||||
enable_granular_consent |
Opsional
Default-nya adalah Saat Google mengaktifkan izin terperinci untuk aplikasi, parameter ini tidak akan lagi berpengaruh. |
||||||||||||||||||
login_hint |
Opsional
Jika mengetahui pengguna mana yang mencoba melakukan autentikasi, aplikasi Anda dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login dengan mengisi otomatis kolom email di formulir login atau dengan memilih sesi multi-login yang sesuai. Tetapkan nilai parameter ke alamat email atau ID |
||||||||||||||||||
prompt |
Opsional
Daftar perintah yang peka huruf besar/kecil dan dipisahkan spasi untuk ditampilkan kepada pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan diminta saat pertama kali project Anda meminta akses. Lihat Meminta izin ulang untuk informasi selengkapnya. Nilai yang dimungkinkan adalah:
|
||||||||||||||||||
Contoh pengalihan ke server otorisasi Google
Contoh URL di bawah meminta akses offline
(access_type=offline) ke cakupan yang mengizinkan akses untuk mengambil
laporan YouTube Analytics pengguna. API ini menggunakan otorisasi inkremental untuk
memastikan bahwa token akses baru mencakup cakupan apa pun yang sebelumnya
diberikan pengguna kepada aplikasi. URL juga menetapkan nilai untuk
parameter redirect_uri, response_type, dan
client_id yang diperlukan serta untuk parameter
state. URL berisi baris baru dan spasi agar lebih mudah dibaca.
https://accounts.google.com/o/oauth2/v2/auth?
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
include_granted_scopes=true&
state=state_parameter_passthrough_value&
redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
response_type=token&
client_id=client_idSetelah Anda membuat URL permintaan, alihkan pengguna ke URL tersebut.
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/yt-analytics.readonly https://www.googleapis.com/auth/calendar.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 2: Google 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 menampilkan nama aplikasi Anda dan layanan Google API yang meminta izin untuk diakses dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Pengguna kemudian dapat mengizinkan pemberian 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 diberikan atau tidak. Respons tersebut dijelaskan di langkah berikutnya.
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 solusi yang disarankan tercantum di bawah.
admin_policy_enforced
Akun Google tidak dapat memberikan otorisasi untuk 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 mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan 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 melihat 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 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 dibuka di pengendali link default sistem operasi, yang mencakup pengendali Link Aplikasi Android atau aplikasi browser default. Library Tab Kustom 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
Google Sign-In 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 dibuka 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 dalam artikel bantuan Menyiapkan layar izin OAuth.
invalid_client
Asal permintaan tidak diizinkan untuk klien ini. Lihat
origin_mismatch.
invalid_grant
Saat menggunakan otorisasi inkremental, masa berlaku token mungkin telah berakhir atau telah dibatalkan. Lakukan autentikasi ulang pengguna dan minta izin pengguna untuk mendapatkan token baru. Jika Anda terus melihat error ini, pastikan aplikasi Anda telah dikonfigurasi dengan benar dan Anda menggunakan token dan parameter yang benar dalam permintaan Anda. 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 origin JavaScript resmi di .
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 sah di
.
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 origin JavaScript resmi di .
Parameter redirect_uri dapat merujuk ke alur out-of-band (OOB) OAuth yang
tidak digunakan lagi dan tidak didukung lagi. Lihat
panduan migrasi untuk mengupdate
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 Google. Memverifikasi integrasi OAuth Anda menggunakan metode integrasi yang direkomendasikan
Langkah 3: Tangani respons server OAuth 2.0
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 permintaan tersebut tidak disetujui, respons akan berisi pesan error. Token akses atau pesan error ditampilkan pada fragmen hash URI alihan, seperti yang ditunjukkan di bawah:
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 aktif token, dalam detik. Jika parameterstateditentukan 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 URL contoh berikut, yang meminta akses hanya baca untuk melihat metadata berbagai file di Google Drive dan akses hanya baca untuk melihat acara Google Kalender:
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& include_granted_scopes=true& state=state_parameter_passthrough_value& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& response_type=token& 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 mesin lokal Anda kebetulan menayangkan file di alamat tersebut. Langkah berikutnya memberikan detail selengkapnya tentang informasi yang ditampilkan dalam
URI saat pengguna dialihkan kembali ke aplikasi Anda.
Langkah 4: Periksa cakupan yang diberikan pengguna
Saat meminta beberapa cakupan sekaligus, pengguna mungkin tidak memberikan semua cakupan yang diminta aplikasi Anda. Aplikasi Anda harus selalu memeriksa cakupan yang diberikan oleh pengguna dan menangani penolakan cakupan dengan menonaktifkan fitur yang relevan. Tinjau Cara menangani izin terperinci untuk mengetahui informasi selengkapnya.
Endpoint OAuth 2.0
Untuk memeriksa apakah pengguna telah memberikan akses ke cakupan tertentu kepada aplikasi Anda,
periksa kolom scope dalam respons token akses. Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang peka huruf besar/kecil dan dipisahkan spasi.
Misalnya, contoh respons token akses berikut menunjukkan bahwa pengguna telah memberikan akses aplikasi Anda ke izin aktivitas Drive dan acara Kalender hanya baca:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Memanggil Google API
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 disarankan 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 YouTube Analytics API).
Perhatikan bahwa YouTube Analytics API tidak mendukung alur akun layanan. YouTube Reporting API hanya mendukung akun layanan untuk pemilik konten YouTube yang memiliki dan mengelola beberapa channel YouTube, seperti label rekaman dan studio film.
Anda dapat mencoba semua Google API dan melihat cakupannya di OAuth 2.0 Playground.
Contoh HTTP GET
Panggilan ke endpoint
reports.query (YouTube Analytics API) menggunakan header HTTP
Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:
GET /youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views 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/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Contoh curl
Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut adalah
contoh yang menggunakan opsi header HTTP (lebih disukai):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Atau, opsi parameter string kueri:
curl https://www.googleapis.com/youtube/analytics/v1/reports?access_token=access_token&ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views
Kode contoh JavaScript
Cuplikan kode di bawah 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/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' + 'access_token=' + params['access_token']); xhr.onreadystatechange = function (e) { console.log(xhr.response); }; xhr.send(null);
Contoh lengkap
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 ditujukan untuk halaman HTML yang menampilkan tombol untuk mencoba permintaan API. Jika Anda mengklik tombol, kode akan memeriksa apakah halaman telah menyimpan token akses API di penyimpanan lokal browser Anda. Jika ya, permintaan API akan dieksekusi. Jika tidak, alur OAuth 2.0 akan dimulai.
Untuk alur OAuth 2.0, halaman mengikuti langkah-langkah berikut:
- Tindakan ini akan mengarahkan pengguna ke server OAuth 2.0 Google, yang meminta akses ke cakupan
https://www.googleapis.com/auth/yt-analytics.readonlydanhttps://www.googleapis.com/auth/calendar.readonly. - Setelah memberikan (atau menolak) akses ke satu atau beberapa cakupan yang diminta, pengguna akan dialihkan ke halaman asli, yang mengurai token akses dari string ID fragmen.
- Halaman ini memeriksa cakupan yang telah diberikan akses ke aplikasi oleh pengguna.
Jika pengguna telah memberikan akses ke scope() yang diminta, halaman akan menggunakan token akses untuk membuat permintaan API contoh.
Permintaan API ini memanggil metode
reports.queryYouTube Analytics API untuk mengambil jumlah penayangan untuk channel YouTube pengguna yang diotorisasi.- Jika permintaan berhasil dijalankan, respons API akan dicatat dalam konsol proses debug browser.
Anda dapat mencabut akses ke aplikasi melalui halaman Izin untuk Akun Google Anda. Aplikasi akan tercantum 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 dengan tempat halaman ditayangkan. Nilai ini harus sama persis dengan salah satu URI alihan yang diotorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di . Jika nilai ini tidak cocok dengan URI yang diotorisasi, Anda akan mendapatkan error redirect_uri_mismatch. Project Anda juga harus telah 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';
// Parse query string to see if page request is coming from OAuth 2.0 server.
var fragmentString = location.hash.substring(1);
var params = {};
var regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(fragmentString)) {
params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}
if (Object.keys(params).length > 0 && params['state']) {
if (params['state'] == localStorage.getItem('state')) {
localStorage.setItem('oauth2-test-params', JSON.stringify(params) );
trySampleRequest();
} else {
console.log('State mismatch. Possible CSRF attack');
}
}
// Function to generate a random state value
function generateCryptoRandomState() {
const randomValues = new Uint32Array(2);
window.crypto.getRandomValues(randomValues);
// Encode as UTF-8
const utf8Encoder = new TextEncoder();
const utf8Array = utf8Encoder.encode(
String.fromCharCode.apply(null, randomValues)
);
// Base64 encode the UTF-8 data
return btoa(String.fromCharCode.apply(null, utf8Array))
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=+$/, '');
}
// 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']) {
// User authorized the request. Now, check which scopes were granted.
if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
// User authorized read-only Drive activity permission.
// Calling the APIs, etc.
var xhr = new XMLHttpRequest();
xhr.open('GET',
'https://www.googleapis.com/youtube/analytics/v1/reports?ids=channel%3D%3DMINE&start-date=2016-05-01&end-date=2016-06-30&metrics=views&' +
'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 {
// User didn't authorize read-only Drive activity permission.
// Update UX and application accordingly
console.log('User did not authorize read-only Drive activity permission.');
}
// Check if user authorized Calendar read permission.
if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
// User authorized Calendar read permission.
// Calling the APIs, etc.
console.log('User authorized Calendar read permission.');
}
else {
// User didn't authorize Calendar read permission.
// Update UX and application accordingly
console.log('User did not authorize Calendar read permission.');
}
} else {
oauth2SignIn();
}
}
/*
* Create form to request access token from Google's OAuth 2.0 server.
*/
function oauth2SignIn() {
// create random state value and store in local storage
var state = generateCryptoRandomState();
localStorage.setItem('state', state);
// 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/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly',
'state': state,
'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 origin JavaScript
Google menerapkan aturan validasi berikut ke origin JavaScript untuk membantu developer menjaga keamanan aplikasi mereka. Origin JavaScript Anda harus mematuhi aturan ini. Lihat RFC 3986 bagian 3 untuk definisi domain, host, dan skema, yang disebutkan di bawah.
| Aturan validasi | |
|---|---|
| Skema |
Origin 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. |
| Userinfo |
Origin JavaScript tidak boleh berisi subkomponen userinfo. |
| Jalur |
Origin JavaScript tidak boleh berisi komponen jalur. |
| Kueri |
Asal JavaScript tidak boleh berisi komponen kueri. |
| Fragment |
Asal JavaScript tidak boleh berisi komponen fragmen. |
| Karakter |
Origin 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. Meminta otorisasi untuk resource pada saat Anda membutuhkannya dianggap sebagai praktik pengalaman pengguna terbaik. 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, menampilkan kode otorisasi yang dapat ditukar dengan token yang berisi semua cakupan yang telah diberikan pengguna ke project.
Misalnya, aplikasi mengambil laporan YouTube Analytics, beberapa
di antaranya adalah laporan moneter yang memerlukan akses ke cakupan tambahan yang tidak
diperlukan untuk laporan lainnya. Dalam hal ini, pada waktu login, aplikasi mungkin hanya
meminta akses ke
cakupan https://www.googleapis.com/auth/yt-analytics.readonly.
Namun, jika pengguna mencoba mengambil laporan keuangan, aplikasi juga dapat
meminta akses ke
cakupan
https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Aturan berikut berlaku untuk token akses yang diperoleh dari otorisasi inkremental:
- Token dapat digunakan untuk mengakses resource yang sesuai dengan cakupan apa pun yang digabungkan ke dalam otorisasi gabungan baru.
- Saat Anda menggunakan token refresh untuk otorisasi gabungan guna mendapatkan token akses, token akses mewakili otorisasi gabungan dan dapat digunakan untuk salah satu
nilai
scopeyang disertakan dalam respons. - Otorisasi gabungan mencakup semua cakupan yang diberikan pengguna ke project API meskipun pemberian tersebut 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 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 menunjukkan cara menambahkan cakupan ke token akses yang ada. Pendekatan ini memungkinkan aplikasi Anda menghindari pengelolaan beberapa token akses.
Endpoint OAuth 2.0
Dalam contoh ini, aplikasi panggilan meminta akses untuk mengambil data YouTube Analytics pengguna selain akses lain yang telah diberikan pengguna ke aplikasi.
Untuk menambahkan cakupan ke token akses yang ada, sertakan parameter include_granted_scopes
dalam permintaan Anda ke server OAuth 2.0 Google.
Cuplikan kode berikut menunjukkan cara melakukannya. Cuplikan mengasumsikan bahwa Anda telah menyimpan cakupan yang valid untuk token akses Anda di penyimpanan lokal browser. (Kode
contoh lengkap menyimpan daftar cakupan yang token aksesnya
valid dengan menetapkan properti oauth2-test-params.scope di penyimpanan lokal browser.)
Cuplikan membandingkan cakupan yang valid untuk token akses dengan cakupan yang ingin Anda gunakan untuk kueri tertentu. Jika token akses tidak mencakup cakupan tersebut, alur OAuth 2.0 akan dimulai.
Di sini, fungsi oauth2SignIn sama dengan yang diberikan di
langkah 2 (dan yang diberikan nanti di contoh lengkap).
var SCOPE = 'https://www.googleapis.com/auth/yt-analytics.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 Hapus akses situs atau aplikasi di dokumen dukungan Situs & aplikasi pihak ketiga yang dapat mengakses akun Anda untuk mengetahui informasi selengkapnya.
Aplikasi juga dapat mencabut akses yang diberikan secara terprogram. Pencabutan terprogram penting dalam kasus saat pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan dapat mencakup permintaan API untuk memastikan izin yang sebelumnya diberikan ke aplikasi dihapus.
Endpoint OAuth 2.0
Untuk mencabut token secara terprogram, aplikasi Anda 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 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 responsnya 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 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(); }
Menerapkan Perlindungan Lintas Akun
Langkah tambahan yang harus Anda lakukan untuk melindungi akun pengguna adalah menerapkan Perlindungan lintas akun dengan memanfaatkan Layanan Perlindungan Lintas Akun Google. Layanan ini memungkinkan Anda berlangganan notifikasi peristiwa keamanan yang memberikan informasi kepada aplikasi tentang perubahan besar pada akun pengguna. Anda kemudian dapat menggunakan informasi tersebut untuk mengambil tindakan, bergantung pada cara Anda memutuskan untuk merespons peristiwa.
Beberapa contoh jenis peristiwa yang dikirim ke aplikasi Anda oleh Layanan Perlindungan Lintas Akun Google adalah:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Lihat halaman Melindungi akun pengguna dengan Perlindungan Lintas Akun untuk mengetahui informasi selengkapnya tentang cara menerapkan Perlindungan Lintas Akun dan untuk mengetahui daftar lengkap peristiwa yang tersedia.