Dokumen ini menjelaskan cara aplikasi yang diinstal di perangkat seperti ponsel, tablet, dan komputer menggunakan endpoint OAuth 2.0 Google untuk mengizinkan akses ke YouTube Analytics API atau YouTube Reporting API.
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 pengambilan data YouTube Analytics suatu channel.
Aplikasi terinstal didistribusikan ke setiap perangkat, dan aplikasi dianggap tidak dapat menjaga rahasia. Modul tersebut 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 terinstal harus membuka browser sistem dan memberikan URI pengalihan lokal untuk menangani respons dari server otorisasi Google.
Alternatif
Untuk aplikasi seluler, Anda dapat memilih 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
Kami merekomendasikan library dan contoh berikut untuk membantu Anda menerapkan alur OAuth 2.0 yang dijelaskan dalam dokumen ini:
- Library AppAuth untuk Android
- Library AppAuth for iOS
- OAuth untuk Aplikasi: Contoh Windows
Prasyarat
Mengaktifkan API untuk project Anda
Aplikasi apa pun yang memanggil Google API harus mengaktifkan API tersebut di API Console.
Untuk mengaktifkan API project Anda:
- Open the API Library dalam Google API Console.
- If prompted, select a project, or create a new one.
- Gunakan halaman Koleksi untuk menemukan dan mengaktifkan YouTube Analytics API dan YouTube Reporting API. Banyak aplikasi yang mengambil data YouTube Analytics juga berinteraksi dengan YouTube Data API. Temukan API lain yang akan digunakan aplikasi Anda dan aktifkan juga API tersebut.
Membuat kredensial otorisasi
Semua 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 diaktifkan untuk project tersebut.
- Go to the Credentials page.
- Klik Create credentials > OAuth client ID.
- Bagian di bawah ini menjelaskan jenis klien dan metode pengalihan yang didukung oleh server otorisasi Google. Pilih jenis klien yang direkomendasikan untuk aplikasi Anda, beri nama klien OAuth Anda, dan tetapkan kolom lain dalam formulir yang sesuai.
Android
- Pilih jenis aplikasi Android.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page project Anda untuk mengidentifikasi klien.
- Masukkan nama paket aplikasi Android Anda. Nilai ini ditetapkan dalam
atribut
package
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 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
pada output keytool. Baca bagian Mengautentikasi Klien dalam dokumentasi Google API untuk Android untuk mengetahui informasi lebih lanjut.
- (Opsional) Verifikasi kepemilikan aplikasi Android Anda.
- Klik Create.
iOS
- Pilih jenis aplikasi iOS.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page 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 paling sering ditampilkan di panel General atau panel Penandatanganan & Kemampuan di editor project Xcode. ID paket juga ditampilkan di bagian Informasi Umum pada halaman Informasi Aplikasi untuk aplikasi di situs App Store Connect Apple.
- (Opsional)
Masukkan ID App Store aplikasi Anda jika aplikasi dipublikasikan di App Store Apple. ID Store adalah string numerik yang disertakan di setiap URL Apple App Store.
- Buka aplikasi Apple App Store di perangkat iOS atau iPadOS Anda.
- Telusuri aplikasi Anda.
- Pilih tombol Share (simbol kotak dan panah ke atas).
- Pilih Salin Link.
- Tempelkan link ke editor teks. ID App Store adalah bagian akhir dari URL.
Contoh:
https://apps.apple.com/app/google/id284815942
- (Opsional)
Masukkan ID Tim Anda. Lihat Menemukan ID Tim di dokumentasi Akun Developer Apple untuk mengetahui informasi selengkapnya.
- Klik Create.
UWP
- Pilih jenis aplikasi Universal Windows Platform.
- Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page project Anda untuk mengidentifikasi klien.
- Masukkan ID Microsoft Store 12 karakter untuk aplikasi Anda. Anda dapat menemukan nilai ini di Microsoft Partner Center pada halaman Identitas aplikasi di bagian Pengelolaan aplikasi.
- Klik Create.
Untuk aplikasi UWP, skema URI kustom tidak boleh melebihi 39 karakter.
Skema URI kustom (Android, iOS, UWP)
Skema URI kustom adalah bentuk deep link yang menggunakan skema yang ditentukan secara kustom untuk membuka aplikasi Anda.
Alternatif selain menggunakan skema URI kustom di AndroidGunakan Login dengan Google untuk Android SDK yang memberikan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak perlu menggunakan URI pengalihan.
Cara bermigrasi ke Login dengan Google untuk Android SDK
Jika saat ini Anda menggunakan skema kustom untuk integrasi OAuth di Android, Anda perlu menyelesaikan tindakan di bawah ini untuk sepenuhnya bermigrasi ke penggunaan Login dengan Google yang direkomendasikan untuk Android SDK:
- Perbarui kode Anda untuk menggunakan SDK Login dengan Google.
- Nonaktifkan dukungan untuk skema kustom di Konsol API Google.
Ikuti langkah-langkah di bawah untuk bermigrasi ke Google Sign-In Android SDK:
-
Update kode Anda untuk menggunakan Android SDK Login dengan Google:
-
Periksa kode 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 Anda perlukan untuk mengonfigurasi SDK Login dengan Google. -
Ikuti petunjuk
Mulai Mengintegrasikan Login dengan Google ke dalam Aplikasi Android Anda
untuk menyiapkan SDK. Anda dapat melewati langkah Mendapatkan client ID OAuth 2.0 server backend Anda 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 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, lalu pilih klien Android Anda.
- Buka bagian Advanced Settings, hapus centang pada kotak Enable Custom URI Scheme, lalu klik Save untuk menonaktifkan dukungan skema URI kustom.
Mengaktifkan skema URI kustom
Jika alternatif yang direkomendasikan tidak berhasil, Anda dapat mengaktifkan skema URI kustom untuk klien Android Anda dengan mengikuti petunjuk di bawah ini:- Buka daftar kredensial OAuth 2.0, lalu pilih klien Android Anda.
- Buka bagian Advanced Settings, centang kotak Enable Custom URI Scheme, lalu klik Save untuk mengaktifkan dukungan skema URI kustom.
Gunakan Chrome Identity API yang memberikan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak perlu lagi URI pengalihan.
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 sudah memilikinya dan aplikasi Anda terdaftar di Konsol Google Play. Persyaratan berikut harus dipenuhi agar verifikasi berhasil:
- Anda harus memiliki aplikasi yang terdaftar di Konsol Google Play dengan nama paket dan sidik jari sertifikat penandatanganan SHA-1 yang sama dengan klien OAuth Android yang Anda isi 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, dialog error akan ditampilkan.
Untuk memperbaiki verifikasi yang gagal, coba langkah berikut:
- Pastikan aplikasi yang Anda verifikasi adalah aplikasi yang 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 yang terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang sedang Anda selesaikan verifikasinya.
- 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, dialog 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 Anda selesaikan verifikasinya.
- Pastikan Anda adalah penayang aplikasi, yaitu Anda harus menjadi penayang individual aplikasi atau anggota penayang grup aplikasi tersebut. Pelajari lebih lanjut pengelolaan akses di Dasbor Developer Chrome Web Store.
- Jika Anda baru saja memperbarui daftar penayang grup, pastikan daftar keanggotaan penayang grup telah disinkronkan di Dasbor Developer Chrome Web Store. Pelajari lebih lanjut cara menyinkronkan daftar keanggotaan penayang.
Alamat IP loopback (macOS, Linux, desktop Windows)
Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus memproses di server web lokal. Hal itu bisa dilakukan di banyak, tetapi tidak semua, platform. Namun, jika platform Anda mendukungnya, ini adalah mekanisme yang direkomendasikan untuk mendapatkan kode otorisasi.
Saat 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 | Setel jenis aplikasi ke Aplikasi desktop. |
Salin/tempel manual
Mengidentifikasi cakupan akses
Dengan cakupan, aplikasi Anda dapat hanya meminta akses ke resource yang diperlukannya, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.
Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan yang memerlukan izin akses untuk aplikasi Anda.
YouTube Analytics API menggunakan cakupan berikut:
Cakupan | |
---|---|
https://www.googleapis.com/auth/youtube | Kelola akun YouTube Anda |
https://www.googleapis.com/auth/youtube.readonly | Lihat 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 | Lihat laporan moneter dan non-moneter YouTube Analytics untuk konten YouTube Anda |
https://www.googleapis.com/auth/yt-analytics.readonly | Lihat laporan YouTube Analytics untuk konten YouTube Anda |
YouTube Reporting API menggunakan cakupan berikut:
Cakupan | |
---|---|
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | Lihat laporan moneter dan non-moneter YouTube Analytics untuk konten YouTube Anda |
https://www.googleapis.com/auth/yt-analytics.readonly | Lihat laporan YouTube Analytics untuk konten YouTube Anda |
Dokumen Cakupan OAuth 2.0 API berisi daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API.
Mendapatkan token akses OAuth 2.0
Langkah-langkah berikut menunjukkan cara aplikasi berinteraksi dengan server OAuth 2.0 Google guna mendapatkan izin pengguna untuk menjalankan permintaan API atas nama pengguna. Aplikasi Anda harus memiliki izin tersebut sebelum dapat mengeksekusi permintaan Google API yang memerlukan otorisasi pengguna.
Langkah 1: Buat pemverifikasi kode dan verifikasi
Google mendukung protokol Proof Key untuk Code Exchange (PKCE) untuk membuat alur aplikasi terinstal lebih aman. Pemverifikasi kode unik dibuat untuk setiap permintaan otorisasi, dan nilai transformasinya, yang disebut "code_challenge", dikirim ke server otorisasi untuk mendapatkan kode otorisasi.
Membuat pemverifikasi kode
code_verifier
adalah string acak kriptografis dengan entropi tinggi yang menggunakan karakter yang tidak dicadangkan [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", dengan panjang minimum 43 karakter dan panjang maksimum 128 karakter.
Pemverifikasi kode harus memiliki entropi yang cukup sehingga tidak praktis untuk menebak nilai.
Membuat tantangan kode
Dua metode pembuatan tantangan kode didukung.
Metode Pembuatan Tantangan Kode | |
---|---|
S256 (direkomendasikan) | Tantangan kode adalah hash SHA256 yang dienkode Base64URL (tanpa padding) dari pemverifikasi kode.
|
biasa | Tantangan kode adalah nilai yang sama dengan pemverifikasi 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 memperoleh izin pengguna. Endpoint hanya dapat diakses melalui SSL dan menolak koneksi HTTP (non-SSL).
Server otorisasi mendukung parameter string kueri berikut untuk aplikasi terinstal:
Parameter | |||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Wajib
Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di API Console Credentials page. |
||||||||||||||||||
redirect_uri |
Wajib
Menentukan cara server otorisasi Google mengirim respons ke aplikasi Anda. Ada beberapa opsi pengalihan yang tersedia untuk aplikasi terinstal, dan Anda akan menyiapkan kredensial otorisasi dengan mempertimbangkan metode pengalihan tertentu. 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 yang diberi otorisasi, Anda akan mendapatkan error Tabel di bawah menunjukkan nilai parameter
|
||||||||||||||||||
response_type |
Wajib
Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Setel nilai parameter ke |
||||||||||||||||||
scope |
Wajib
Daftar cakupan yang dipisahkan spasi, yang mengidentifikasi resource yang dapat diakses aplikasi Anda untuk pengguna. Nilai ini menentukan layar izin yang ditampilkan Google kepada pengguna. Dengan cakupan, aplikasi Anda dapat hanya meminta akses ke resource yang diperlukannya, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, terdapat hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna. YouTube Analytics API menggunakan cakupan berikut:
YouTube Reporting API menggunakan cakupan berikut:
Dokumen Cakupan OAuth 2.0 API 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 yang digunakan aplikasi untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi.
Server menampilkan nilai yang tepat 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 aplikasi Anda mengetahui pengguna mana yang mencoba melakukan autentikasi, aplikasi tersebut dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk tersebut untuk menyederhanakan alur login, baik dengan mengisi otomatis kolom email di formulir login maupun dengan memilih sesi multi-login yang sesuai. Setel nilai parameter ke alamat email atau ID |
Contoh URL otorisasi
Tab di bawah ini menampilkan 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 tersebut
juga berisi parameter response_type
dan client_id
yang diperlukan serta
parameter state
opsional. Setiap URL berisi jeda baris dan spasi agar
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 akan 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. Kemudian, pengguna dapat mengizinkan akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan tersebut.
Pada tahap ini, aplikasi Anda tidak perlu melakukan apa pun karena menunggu respons dari server OAuth 2.0 Google yang menunjukkan apakah akses telah diberikan atau belum. Respons tersebut dijelaskan dalam langkah berikut.
Error
Permintaan ke endpoint otorisasi OAuth 2.0 Google mungkin menampilkan pesan error yang ditampilkan kepada pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode error umum dan penyelesaian yang disarankan tercantum di bawah ini.
admin_policy_enforced
Akun Google tidak dapat memberikan otorisasi ke satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace mereka. Lihat artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal mana yang mengakses data Google Workspace untuk mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan yang 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
.
Developer sebaiknya menggunakan library Android seperti Login dengan Google untuk Android atau AppAuth for Android dari OpenID Foundation.
Developer web mungkin mengalami error ini saat aplikasi Android membuka link web umum di agen pengguna yang disematkan 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 Khusus Android juga merupakan opsi yang didukung.
iOS
Developer iOS dan macOS mungkin mengalami error ini saat membuka permintaan otorisasi di WKWebView
.
Developer sebaiknya menggunakan library iOS seperti Login dengan Google untuk iOS atau AppAuth for iOS dari OpenID Foundation.
Developer web mungkin mengalami error ini saat aplikasi iOS atau macOS membuka link web umum di
agen pengguna yang disematkan 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 Universal
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 lebih lanjut tentang opsi konfigurasi ini, lihat bagian Jenis pengguna di artikel bantuan Menyiapkan layar izin OAuth.
invalid_grant
Jika Anda menggunakan pemverifikasi kode dan verifikasi, parameter code_callenge
tidak valid atau tidak ada. Pastikan parameter code_challenge
ditetapkan dengan benar.
Saat memuat ulang token akses, masa berlaku token mungkin telah berakhir atau telah dibatalkan. Autentikasi pengguna lagi 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. Jika tidak, akun pengguna mungkin telah dihapus atau dinonaktifkan.
redirect_uri_mismatch
redirect_uri
yang diteruskan dalam permintaan otorisasi tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client ID OAuth. Tinjau URI pengalihan yang diberi otorisasi di
Google API Console Credentials page.
redirect_uri
yang diteruskan mungkin tidak valid untuk jenis klien.
Parameter redirect_uri
dapat merujuk pada alur out-of-band (OOB) OAuth yang tidak digunakan lagi dan tidak didukung lagi. Lihat panduan migrasi untuk memperbarui integrasi Anda.
invalid_request
Ada yang salah dengan permintaan yang Anda buat. Ini bisa disebabkan oleh beberapa alasan:
- Permintaan tidak diformat dengan benar
- Permintaan tidak berisi parameter yang diperlukan
- Permintaan tersebut menggunakan metode otorisasi yang tidak didukung oleh Google. Pastikan integrasi OAuth Anda menggunakan metode integrasi yang direkomendasikan
- Skema kustom digunakan untuk URI pengalihan : Jika Anda melihat pesan error Custom URI scheme is not supported on Chrome apps atau Skema URI Kustom tidak diaktifkan untuk klien Android Anda, itu berarti 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. Apa pun skemanya, responsnya akan berisi kode otorisasi (code
) atau error
(error
). Misalnya, error=access_denied
menunjukkan bahwa pengguna
menolak permintaan.
Jika pengguna memberikan akses ke aplikasi, Anda dapat menukar kode otorisasi dengan token akses dan token refresh seperti yang dijelaskan pada langkah berikutnya.
Langkah 5: Tukar kode otorisasi dengan token refresh dan akses
Untuk menukar kode otorisasi dengan token akses, panggil endpoint https://oauth2.googleapis.com/token
dan tetapkan parameter berikut:
Kolom | |
---|---|
client_id |
Client ID yang diperoleh dari API Console Credentials page. |
client_secret |
Rahasia klien yang diperoleh dari API Console Credentials page. |
code |
Kode otorisasi yang ditampilkan dari permintaan awal. |
code_verifier |
Pemverifikasi kode yang Anda buat di Langkah 1. |
grant_type |
Sebagaimana ditentukan dalam spesifikasi OAuth 2.0, nilai kolom ini harus ditetapkan ke authorization_code . |
redirect_uri |
Salah satu URI pengalihan yang tercantum untuk project Anda di
API Console
Credentials page untuk
client_id yang ditentukan. |
Cuplikan berikut menunjukkan contoh permintaan:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Google merespons permintaan ini dengan menampilkan objek JSON yang berisi token akses berumur pendek dan token refresh.
Respons berisi kolom berikut:
Kolom | |
---|---|
access_token |
Token yang dikirimkan aplikasi Anda untuk mengizinkan permintaan Google API. |
expires_in |
Sisa masa pakai token akses dalam hitungan detik. |
id_token |
Catatan: Properti ini hanya ditampilkan jika permintaan Anda menyertakan cakupan identitas, seperti openid , profile , atau email . Nilainya adalah JSON Web Token (JWT) yang berisi informasi identitas pengguna yang ditandatangani secara digital. |
refresh_token |
Token yang dapat digunakan untuk mendapatkan token akses baru. Token refresh berlaku hingga pengguna mencabut akses. Perhatikan bahwa token refresh selalu dikembalikan untuk aplikasi yang diinstal. |
scope |
Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang dipisahkan spasi dan peka huruf besar/kecil. |
token_type |
Jenis token yang ditampilkan. Saat ini, nilai kolom ini selalu ditetapkan ke Bearer . |
Cuplikan berikut menunjukkan contoh respons:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/yt-analytics.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 akan lebih disukai karena string kueri cenderung terlihat di log server. Pada umumnya, 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 GET HTTP
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 terautentikasi yang 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 ini 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, sebagai alternatif, 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 habis secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat memperbarui token akses tanpa meminta izin kepada pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token tersebut.
Untuk memperbarui token akses, aplikasi Anda mengirim permintaan POST
HTTPS ke server otorisasi Google (https://oauth2.googleapis.com/token
) yang menyertakan parameter berikut:
Kolom | |
---|---|
client_id |
Client ID yang diperoleh dari API Console. |
client_secret |
Rahasia klien yang diperoleh dari API Console.
(client_secret tidak berlaku untuk permintaan dari klien yang terdaftar sebagai
aplikasi Android, iOS, atau Chrome.)
|
grant_type |
Seperti
yang ditetapkan dalam
spesifikasi OAuth 2.0,
nilai kolom ini harus ditetapkan ke refresh_token . |
refresh_token |
Token refresh yang ditampilkan dari pertukaran kode otorisasi. |
Cuplikan berikut menunjukkan contoh permintaan:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Selama pengguna belum mencabut akses yang diberikan ke aplikasi, server token akan menampilkan objek JSON yang berisi token akses baru. Cuplikan berikut menunjukkan contoh respons:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/drive.metadata.readonly", "token_type": "Bearer" }
Perhatikan bahwa ada batasan jumlah token refresh yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu batas per pengguna untuk 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 mungkin akan mencapai batas ini, sehingga 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 dokumen dukungan Menghapus akses situs atau aplikasi di situs & aplikasi pihak ketiga yang memiliki akses ke akun Anda untuk mengetahui informasi selengkapnya.
Aplikasi juga dapat mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram penting jika pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan dapat mencakup permintaan API untuk memastikan izin yang sebelumnya diberikan ke aplikasi telah dihapus.
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 tersebut adalah
200
. Untuk kondisi error, kode status HTTP 400
ditampilkan bersama dengan kode error.
Bacaan Lebih Lanjut
Praktik Terbaik Saat Ini dari IETF OAuth 2.0 untuk Aplikasi Native menetapkan banyak praktik terbaik yang didokumentasikan di sini.