Dokumen ini menjelaskan cara aplikasi yang diinstal di perangkat seperti ponsel, tablet, dan komputer menggunakan endpoint OAuth 2.0 Google untuk memberikan otorisasi akses ke YouTube Analytics API atau YouTube Reporting API.
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.
Aplikasi yang diinstal didistribusikan ke setiap perangkat, dan diasumsikan bahwa aplikasi ini tidak dapat menyimpan rahasia. Aplikasi dapat mengakses Google API saat pengguna berada di aplikasi atau saat aplikasi berjalan di latar belakang.
Alur otorisasi ini mirip dengan yang digunakan untuk aplikasi server web. Perbedaan utamanya adalah aplikasi yang diinstal harus membuka browser sistem dan menyediakan URI pengalihan lokal untuk menangani respons dari server otorisasi Google.
Alternatif
Untuk aplikasi seluler, Anda dapat menggunakan Login dengan Google untuk Android atau iOS. Library klien Login dengan Google menangani autentikasi dan otorisasi pengguna, dan mungkin lebih mudah diterapkan daripada protokol tingkat rendah yang dijelaskan di sini.
Untuk aplikasi yang berjalan di perangkat yang tidak mendukung browser sistem atau yang memiliki kemampuan input terbatas, seperti TV, konsol game, kamera, atau printer, lihat OAuth 2.0 untuk TV & Perangkat atau Login di TV dan Perangkat Input Terbatas.
Library dan contoh
Sebaiknya gunakan library dan contoh berikut untuk membantu Anda menerapkan alur OAuth 2.0 yang dijelaskan dalam dokumen ini:
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.
- Bagian berikut menjelaskan jenis klien yang didukung server otorisasi Google. Pilih jenis klien yang direkomendasikan untuk aplikasi Anda, beri nama klien OAuth, dan tetapkan kolom lain dalam formulir sesuai kebutuhan.
Android
- Pilih jenis aplikasi Android.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
- Masukkan nama paket aplikasi Android Anda. Nilai ini ditentukan dalam
atribut
package
dari elemen<manifest>
dalam file manifes aplikasi Anda. - Masukkan sidik jari sertifikat penandatanganan SHA-1 dari distribusi aplikasi.
- Jika aplikasi Anda menggunakan penandatanganan aplikasi oleh Google Play, salin sidik jari SHA-1 dari halaman penandatanganan aplikasi di Konsol Play.
- Jika Anda mengelola keystore dan kunci penandatanganan Anda sendiri, gunakan utilitas keytool
yang disertakan dengan Java untuk mencetak informasi sertifikat dalam format yang dapat dibaca manusia. Salin nilai
SHA1
di bagianCertificate fingerprints
dari output keytool. Lihat Mengautentikasi Klien dalam dokumentasi Google API untuk Android guna mengetahui informasi selengkapnya.
- (Opsional) Verifikasi kepemilikan aplikasi Android Anda.
- Klik Buat.
iOS
- Pilih jenis aplikasi iOS.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
- Masukkan ID paket untuk aplikasi Anda. ID paket adalah nilai kunci
CFBundleIdentifier
dalam file resource daftar properti informasi aplikasi Anda (info.plist). Nilai ini
biasanya ditampilkan di panel Umum atau panel Signing & Capabilities di
editor project Xcode. ID paket juga ditampilkan di bagian Informasi Umum di
halaman Informasi Aplikasi untuk aplikasi di
situs App Store Connect Apple.
Pastikan Anda menggunakan ID paket yang benar untuk aplikasi Anda, karena Anda tidak akan dapat mengubahnya jika menggunakan fitur App Check.
- (Opsional)
Masukkan ID App Store aplikasi Anda jika aplikasi dipublikasikan di App Store Apple. ID Toko adalah string numerik yang disertakan dalam setiap URL Apple App Store.
- Buka aplikasi Apple App Store di perangkat iOS atau iPadOS Anda.
- Telusuri aplikasi Anda.
- Pilih tombol Bagikan (simbol persegi dan panah atas).
- Pilih Salin Link.
- Tempelkan link ke editor teks. ID App Store adalah bagian terakhir dari URL.
Contoh:
https://apps.apple.com/app/google/id284815942
- (Opsional)
Masukkan ID Tim Anda. Lihat Menemukan ID Tim Anda di dokumentasi Akun Developer Apple untuk mengetahui informasi selengkapnya.
Catatan: Kolom ID Tim diperlukan jika Anda mengaktifkan App Check untuk klien. - (Opsional)
Aktifkan App Check untuk aplikasi iOS Anda. Saat Anda mengaktifkan App Check, layanan App Attest Apple akan digunakan untuk memverifikasi bahwa permintaan OAuth 2.0 yang berasal dari klien OAuth Anda adalah asli dan berasal dari aplikasi Anda. Hal ini membantu mengurangi risiko peniruan identitas aplikasi. Pelajari lebih lanjut cara mengaktifkan App Check untuk aplikasi iOS Anda.
- Klik Buat.
UWP
- Pilih jenis aplikasi Universal Windows Platform.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
- Masukkan ID Microsoft Store 12 karakter aplikasi Anda. Anda dapat menemukan nilai ini di Microsoft Partner Center di halaman Identitas aplikasi di bagian Pengelolaan aplikasi.
- Klik Buat.
Untuk aplikasi UWP, skema URI kustom tidak boleh lebih dari 39 karakter.
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: Buat verifikasi kode dan tantangan
Google mendukung protokol Proof Key for Code Exchange (PKCE) untuk membuat alur aplikasi yang diinstal lebih aman. Pengverifikasi kode unik dibuat untuk setiap permintaan otorisasi, dan nilai yang diubahnya, yang disebut "code_challenge", dikirim ke server otorisasi untuk mendapatkan kode otorisasi.
Membuat verifikasi kode
code_verifier
adalah string acak kriptografis entropi tinggi yang menggunakan karakter yang tidak direservasi
[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", dengan panjang minimum 43 karakter
dan panjang maksimum 128 karakter.
Pengverifikasi kode harus memiliki entropi yang cukup sehingga tidak praktis untuk menebak nilainya.
Membuat tantangan kode
Ada dua metode untuk membuat tantangan kode yang didukung.
Metode Pembuatan Tantangan Kode | |
---|---|
S256 (direkomendasikan) | Tantangan kode adalah hash SHA256 yang dienkode Base64URL (tanpa padding) dari verifier
kode.
|
plain | Tantangan kode memiliki nilai yang sama dengan verifikasi kode yang dihasilkan di atas.
|
Langkah 2: Kirim permintaan ke server OAuth 2.0 Google
Untuk mendapatkan otorisasi pengguna, kirim permintaan ke server otorisasi Google di
https://accounts.google.com/o/oauth2/v2/auth
. Endpoint ini menangani pencarian sesi aktif,
mengautentikasi pengguna, dan mendapatkan izin pengguna. Endpoint hanya dapat diakses melalui SSL, dan menolak koneksi HTTP (non-SSL).
Server otorisasi mendukung parameter string kueri berikut untuk aplikasi yang diinstal:
Parameter | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Wajib
Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di . |
||||||||||||||||||
redirect_uri |
Wajib
Menentukan cara server otorisasi Google mengirim respons ke aplikasi Anda. Ada beberapa opsi pengalihan yang tersedia untuk aplikasi yang diinstal, dan Anda akan menyiapkan kredensial otorisasi dengan mempertimbangkan metode pengalihan tertentu. 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 yang diotorisasi, Anda akan mendapatkan error Tabel di bawah menunjukkan nilai parameter
|
||||||||||||||||||
response_type |
Wajib
Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Tetapkan 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. |
||||||||||||||||||
code_challenge |
Direkomendasikan
Menentukan |
||||||||||||||||||
code_challenge_method |
Direkomendasikan
Menentukan metode yang digunakan untuk mengenkode |
||||||||||||||||||
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 |
||||||||||||||||||
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 |
Contoh URL otorisasi
Tab di bawah menunjukkan contoh URL otorisasi untuk berbagai opsi URI pengalihan.
Setiap URL meminta akses ke cakupan yang mengizinkan akses untuk mengambil laporan YouTube Analytics pengguna.URL-nya identik, kecuali untuk nilai parameter redirect_uri
. URL ini
juga berisi parameter response_type
dan client_id
yang diperlukan serta
parameter state
opsional. Setiap URL berisi baris baru dan spasi agar lebih mudah dibaca.
Skema URI kustom
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Alamat IP loopback
https://accounts.google.com/o/oauth2/v2/auth? scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Langkah 3: 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_grant
Jika Anda menggunakan
verifikasi kode dan
tantangan, parameter code_callenge
tidak valid atau tidak ada. Pastikan parameter
code_challenge
disetel dengan benar.
Saat memuat ulang token akses, token mungkin sudah tidak berlaku 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.
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
.
redirect_uri
yang diteruskan mungkin tidak valid untuk jenis klien.
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
- Skema kustom digunakan untuk URI pengalihan : Jika Anda melihat pesan error Skema URI kustom tidak didukung di aplikasi Chrome atau Skema URI kustom tidak diaktifkan untuk klien Android Anda, artinya Anda menggunakan skema URI kustom yang tidak didukung di aplikasi Chrome dan dinonaktifkan secara default di Android. Pelajari lebih lanjut alternatif skema URI kustom
Langkah 4: Tangani respons server OAuth 2.0
Cara aplikasi Anda menerima respons otorisasi bergantung pada
skema URI pengalihan yang digunakannya. Terlepas dari skema yang digunakan, respons akan berisi kode otorisasi (code
) atau error (error
). Misalnya, error=access_denied
menunjukkan bahwa pengguna menolak permintaan.
Jika pengguna memberikan akses ke aplikasi Anda, Anda dapat menukarkan kode otorisasi dengan token akses dan token refresh seperti yang dijelaskan pada langkah berikutnya.
Langkah 5: Tukarkan kode otorisasi untuk token refresh dan akses
Untuk menukarkan kode otorisasi dengan token akses, panggil
endpoint https://oauth2.googleapis.com/token
dan tetapkan parameter berikut:
Kolom | |
---|---|
client_id |
Client ID yang diperoleh dari . |
client_secret |
Rahasia klien yang diperoleh dari . |
code |
Kode otorisasi yang ditampilkan dari permintaan awal. |
code_verifier |
Pengverifikasi kode yang Anda buat di Langkah 1. |
grant_type |
Seperti yang ditentukan dalam spesifikasi
OAuth 2.0, nilai kolom ini harus ditetapkan ke authorization_code . |
redirect_uri |
Salah satu URI pengalihan yang tercantum untuk project Anda di
untuk
client_id yang diberikan. |
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=http://127.0.0.1:9004& grant_type=authorization_code
Google merespons permintaan ini dengan menampilkan objek JSON yang berisi token akses dengan masa berlaku singkat dan token refresh.
Respons berisi kolom berikut:
Kolom | |
---|---|
access_token |
Token yang dikirimkan aplikasi Anda untuk memberikan otorisasi pada permintaan Google API. |
expires_in |
Masa berlaku token akses yang tersisa dalam hitungan detik. |
id_token |
Catatan: Properti ini hanya ditampilkan jika permintaan Anda menyertakan cakupan identitas,
seperti openid , profile , atau email . Nilainya adalah Token Web JSON (JWT) yang berisi informasi identitas yang ditandatangani secara digital tentang pengguna. |
refresh_token |
Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token refresh berlaku hingga pengguna mencabut akses. Perhatikan bahwa token refresh selalu ditampilkan untuk aplikasi yang diinstal. |
scope |
Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang peka huruf besar/kecil dan dipisahkan spasi. |
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/yt-analytics.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Langkah 6: 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.
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
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
Memperbarui token akses
Masa berlaku token akses secara berkala habis dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat memuat ulang token akses tanpa meminta izin pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token.
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 . |
client_secret |
Rahasia klien yang diperoleh dari .
(client_secret tidak berlaku untuk permintaan dari klien yang terdaftar sebagai
aplikasi Android, iOS, atau Chrome.)
|
grant_type |
Seperti
yang ditentukan 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 https://www.googleapis.com/auth/calendar.readonly", "token_type": "Bearer" }
Perhatikan bahwa ada batasan jumlah token refresh yang akan diterbitkan; satu batasan per kombinasi klien/pengguna, dan satu lagi 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 mengalami batas ini, dalam hal ini token refresh 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 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.
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.
Metode pengalihan aplikasi
Skema URI kustom (Android, iOS, UWP)
Skema URI kustom adalah bentuk deep linking yang menggunakan skema yang ditentukan kustom untuk membuka aplikasi Anda.
Alternatif untuk menggunakan skema URI kustom di Android
Gunakan Google Sign-In untuk Android SDK yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak memerlukan URI pengalihan.
Cara bermigrasi ke Google Sign-In for Android SDK
Jika menggunakan skema kustom untuk integrasi OAuth di Android, Anda harus menyelesaikan tindakan berikut untuk bermigrasi sepenuhnya ke penggunaan Login dengan Google untuk Android SDK yang direkomendasikan:
- Perbarui kode Anda untuk menggunakan Google Sign-In SDK.
- Menonaktifkan dukungan untuk skema kustom di Konsol API Google.
Ikuti langkah-langkah di bawah untuk bermigrasi ke Android SDK Login dengan Google:
-
Perbarui kode Anda untuk menggunakan Android SDK Login dengan Google:
-
Periksa kode Anda untuk mengidentifikasi tempat Anda
mengirim permintaan ke server OAuth 2.0 Google; jika menggunakan skema kustom, permintaan Anda akan terlihat seperti di bawah ini:
https://accounts.google.com/o/oauth2/v2/auth? scope=<SCOPES>& response_type=code& &state=<STATE>& redirect_uri=com.example.app:/oauth2redirect& client_id=<CLIENT_ID>
com.example.app:/oauth2redirect
adalah URI pengalihan skema kustom dalam contoh di atas. Lihat definisi parameterredirect_uri
untuk mengetahui detail selengkapnya tentang format nilai skema URI kustom. -
Catat parameter permintaan
scope
danclient_id
yang diperlukan untuk mengonfigurasi Google Sign-In SDK. -
Ikuti petunjuk
Memulai Integrasi Login dengan Google ke Aplikasi Android
untuk menyiapkan SDK. Anda dapat melewati
langkah Mendapatkan client ID OAuth 2.0 server backend karena Anda akan menggunakan kembali
client_id
yang diambil dari langkah sebelumnya. -
Ikuti petunjuk
Mengaktifkan akses API Sisi Server. Hal ini mencakup langkah-langkah berikut:
-
Gunakan metode
getServerAuthCode
untuk mengambil kode autentikasi untuk cakupan yang izinnya Anda minta. - Kirim kode autentikasi ke backend aplikasi Anda untuk menukarnya dengan token akses & refresh.
- Gunakan token akses yang diambil untuk melakukan panggilan ke Google API atas nama pengguna.
-
Gunakan metode
-
Periksa kode Anda untuk mengidentifikasi tempat Anda
mengirim permintaan ke server OAuth 2.0 Google; jika menggunakan skema kustom, permintaan Anda akan terlihat seperti di bawah ini:
-
Nonaktifkan dukungan untuk skema kustom di Konsol API Google:
- Buka daftar kredensial OAuth 2.0 dan pilih klien Android Anda.
- Buka bagian Setelan Lanjutan, hapus centang pada kotak Aktifkan Skema URI Kustom, lalu klik Simpan untuk menonaktifkan dukungan skema URI kustom.
Mengaktifkan skema URI kustom
Jika alternatif yang direkomendasikan tidak berfungsi untuk Anda, Anda dapat mengaktifkan skema URI kustom untuk klien Android dengan mengikuti petunjuk di bawah:- Buka daftar kredensial OAuth 2.0 dan pilih klien Android Anda.
- Buka bagian Setelan Lanjutan, centang kotak Aktifkan Skema URI Kustom, lalu klik Simpan untuk mengaktifkan dukungan skema URI kustom.
Alternatif untuk menggunakan skema URI kustom di aplikasi Chrome
Gunakan Chrome Identity API yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak memerlukan URI alihan.
Alamat IP loopback (desktop macOS, Linux, Windows)
Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus memproses di server web lokal. Hal ini dapat dilakukan di banyak platform, tetapi tidak semua. Namun, jika platform Anda mendukungnya, ini adalah mekanisme yang direkomendasikan untuk mendapatkan kode otorisasi.
Saat aplikasi Anda menerima respons otorisasi, untuk kegunaan terbaik, aplikasi harus merespons dengan menampilkan halaman HTML yang menginstruksikan pengguna untuk menutup browser dan kembali ke aplikasi Anda.
Penggunaan yang direkomendasikan | Aplikasi desktop macOS, Linux, dan Windows (tetapi bukan Universal Windows Platform) |
Nilai formulir | Tetapkan jenis aplikasi ke Desktop app. |
Salin/tempel manual (Tidak digunakan lagi)
Melindungi aplikasi Anda
Memverifikasi kepemilikan aplikasi (Android, Chrome)
Anda dapat memverifikasi kepemilikan aplikasi untuk mengurangi risiko peniruan identitas aplikasi.
Android
Untuk menyelesaikan proses verifikasi, Anda dapat menggunakan Akun Developer Google Play jika memilikinya dan aplikasi Anda terdaftar di Konsol Google Play. Persyaratan berikut harus dipenuhi agar verifikasi berhasil:
- Anda harus memiliki aplikasi terdaftar di Konsol Google Play dengan nama paket dan sidik jari sertifikat penandatanganan SHA-1 yang sama dengan klien OAuth Android yang Anda selesaikan verifikasinya.
- Anda harus memiliki izin Admin untuk aplikasi di Konsol Google Play. Pelajari lebih lanjut pengelolaan akses di Konsol Google Play.
Di bagian Verifikasi Kepemilikan Aplikasi pada klien Android, klik tombol Verifikasi Kepemilikan untuk menyelesaikan proses verifikasi.
Jika verifikasi berhasil, notifikasi akan ditampilkan untuk mengonfirmasi keberhasilan proses verifikasi. Jika tidak, perintah error akan ditampilkan.
Untuk memperbaiki verifikasi yang gagal, coba langkah berikut:
- Pastikan aplikasi yang Anda verifikasi adalah aplikasi terdaftar di Konsol Google Play.
- Pastikan Anda memiliki izin Admin untuk aplikasi di Konsol Google Play.
Chrome
Untuk menyelesaikan proses verifikasi, Anda akan menggunakan akun Developer Chrome Web Store. Persyaratan berikut harus dipenuhi agar verifikasi berhasil:
- Anda harus memiliki item terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang verifikasinya Anda selesaikan.
- Anda harus menjadi penayang untuk item Chrome Web Store. Pelajari lebih lanjut pengelolaan akses di Dasbor Developer Chrome Web Store.
Di bagian Verifikasi Kepemilikan Aplikasi pada klien Ekstensi Chrome, klik tombol Verifikasi Kepemilikan untuk menyelesaikan proses verifikasi.
Catatan: Tunggu beberapa menit sebelum menyelesaikan proses verifikasi setelah memberikan akses ke akun Anda.
Jika verifikasi berhasil, notifikasi akan ditampilkan untuk mengonfirmasi keberhasilan proses verifikasi. Jika tidak, perintah error akan ditampilkan.
Untuk memperbaiki verifikasi yang gagal, coba langkah berikut:
- Pastikan ada item terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang verifikasinya Anda selesaikan.
- Pastikan Anda adalah penayang untuk aplikasi, yaitu, Anda harus menjadi penayang individual aplikasi atau anggota penayang grup aplikasi. Pelajari lebih lanjut pengelolaan akses di Dasbor Developer Chrome Web Store.
- Jika Anda baru saja memperbarui daftar penayang grup, pastikan daftar keanggotaan penayang grup disinkronkan di Dasbor Developer Chrome Web Store. Pelajari lebih lanjut cara menyinkronkan daftar keanggotaan penayang Anda.
App Check (khusus iOS)
Fitur App Check membantu melindungi aplikasi iOS Anda dari penggunaan yang tidak sah dengan menggunakan layanan App Attest Apple untuk memverifikasi bahwa permintaan yang dibuat ke endpoint OAuth 2.0 Google berasal dari aplikasi asli Anda. Hal ini membantu mengurangi risiko peniruan identitas aplikasi.
Mengaktifkan App Check untuk Klien iOS Anda
Persyaratan berikut harus dipenuhi agar berhasil mengaktifkan App Check untuk klien iOS Anda:- Anda harus menentukan ID tim untuk klien iOS.
- Anda tidak boleh menggunakan karakter pengganti di ID paket karena dapat me-resolve ke lebih dari satu aplikasi. Artinya, ID paket tidak boleh menyertakan simbol tanda bintang (*).
Setelah mengaktifkan App Check, Anda akan mulai melihat metrik yang terkait dengan permintaan OAuth dari klien di tampilan edit klien OAuth. Permintaan dari sumber yang tidak terverifikasi tidak akan diblokir hingga Anda menerapkan App Check. Informasi di halaman pemantauan metrik dapat membantu Anda menentukan kapan harus memulai penerapan.
Anda mungkin melihat error yang terkait dengan fitur App Check saat mengaktifkan App Check untuk aplikasi iOS. Untuk memperbaiki error ini, coba langkah-langkah berikut:
- Pastikan ID paket dan ID tim yang Anda tentukan valid.
- Pastikan Anda tidak menggunakan karakter pengganti untuk ID paket.
Menerapkan App Check untuk Klien iOS
Mengaktifkan App Check untuk aplikasi Anda tidak otomatis memblokir permintaan yang tidak dikenal. Untuk menerapkan perlindungan ini, buka tampilan edit klien iOS Anda. Di sana, Anda akan melihat metrik App Check di sebelah kanan halaman di bagian Google Identity for iOS. Metrik ini mencakup informasi berikut:- Jumlah permintaan terverifikasi - permintaan yang memiliki token App Check yang valid. Setelah Anda mengaktifkan penerapan App Check, hanya permintaan dalam kategori ini yang akan berhasil.
- Jumlah permintaan yang tidak diverifikasi: kemungkinan permintaan klien sudah lama - permintaan yang tidak memiliki token App Check; permintaan ini mungkin berasal dari versi lama aplikasi Anda yang tidak menyertakan penerapan App Check.
- Jumlah permintaan yang tidak diverifikasi: permintaan dengan asal yang tidak diketahui - permintaan yang tidak memiliki token App Check dan sepertinya tidak berasal dari aplikasi Anda.
- Jumlah permintaan yang belum diverifikasi: permintaan tidak valid - permintaan dengan token App Check yang tidak valid, yang mungkin berasal dari klien palsu yang mencoba meniru aplikasi Anda, atau dari lingkungan yang diemulasikan.
Untuk menerapkan Pemeriksaan Aplikasi, klik tombol ENFORCE dan konfirmasi pilihan Anda. Setelah penerapan aktif, semua permintaan yang belum diverifikasi dari klien Anda akan ditolak.
Catatan: setelah Anda mengaktifkan penerapan, perlu waktu hingga 15 menit agar perubahan dapat diterapkan.
Membatalkan penerapan App Check untuk Klien iOS Anda
Jika App Check untuk aplikasi Anda tidak diterapkan, penerapan akan dihentikan dan semua permintaan dari klien Anda ke endpoint Google OAuth 2.0 akan diizinkan, termasuk permintaan yang belum diverifikasi.
Untuk membatalkan penerapan App Check untuk klien iOS, buka tampilan edit klien iOS, lalu klik tombol UNENFORCE dan konfirmasi pilihan Anda.
Catatan: setelah tidak menerapkan Pemeriksaan Aplikasi, perlu waktu hingga 15 menit agar perubahan diterapkan.
Menonaktifkan App Check untuk Klien iOS Anda
Menonaktifkan App Check untuk aplikasi Anda akan menghentikan semua pemantauan dan penerapan App Check. Sebaiknya nonaktifkan App Check agar Anda dapat terus memantau metrik untuk klien.
Untuk menonaktifkan App Check bagi klien iOS, buka tampilan edit klien iOS dan nonaktifkan tombol Protect your OAuth client from abuse with Firebase App Check.
Catatan: setelah menonaktifkan Pemeriksaan Aplikasi, perlu waktu hingga 15 menit agar perubahan diterapkan.
Bacaan Lebih Lanjut
Praktik Terbaik Saat Ini IETF OAuth 2.0 untuk Aplikasi Native menetapkan banyak praktik terbaik yang didokumentasikan di sini.
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.