OAuth 2.0 untuk Aplikasi Seluler & Desktop

Ringkasan ini merangkum alur OAuth 2.0 yang didukung Google, yang dapat membantu Anda memastikan bahwa Anda telah memilih alur yang tepat untuk aplikasi Anda.

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 sembari menjaga kerahasiaan nama pengguna, sandi, dan informasi mereka lainnya. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin mengambil data YouTube Analytics suatu channel.

Aplikasi terinstal didistribusikan ke masing-masing 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 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 lebih 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 untuk iOS
• OAuth for Apps: Windows Samples

Prasyarat

Mengaktifkan API untuk project Anda

Aplikasi apa pun yang memanggil Google API harus mengaktifkan API tersebut di API Console.

Untuk mengaktifkan API bagi project Anda:

1. Open the API Library di Google API Console.
2. If prompted, select a project, or create a new one.
3. 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.

Buat kredensial otorisasi

Aplikasi apa pun yang menggunakan OAuth 2.0 untuk mengakses Google API harus memiliki kredensial otorisasi yang mengidentifikasi aplikasi ke server OAuth 2.0 Google. Langkah-langkah berikut menjelaskan cara membuat kredensial untuk project Anda. Selanjutnya, aplikasi Anda dapat menggunakan kredensial tersebut untuk mengakses API yang telah Anda aktifkan untuk project tersebut.

1. Go to the Credentials page.
2. Klik Create credentials > OAuth client ID.
3. Bagian di bawah ini menjelaskan jenis klien dan metode pengalihan yang didukung server otorisasi Google. Pilih jenis klien yang direkomendasikan untuk aplikasi Anda, beri nama klien OAuth, lalu tetapkan kolom lainnya dalam formulir yang sesuai.

Android

1. Pilih jenis aplikasi Android.
2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page project Anda untuk mengidentifikasi klien.
3. Masukkan nama paket aplikasi Android Anda. Nilai ini ditentukan dalam atribut package elemen <manifest> dalam file manifes aplikasi Anda.
4. Masukkan sidik jari sertifikat penandatanganan SHA-1 untuk 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 kunci penandatanganan dan keystore sendiri, gunakan utilitas keytool yang disertakan dengan Java untuk mencetak informasi sertifikat dalam format yang dapat dibaca manusia. Salin nilai SHA1 di bagian Certificate fingerprints dari output keytool. Lihat artikel Mengautentikasi Klien dalam dokumentasi Google API untuk Android untuk mengetahui informasi selengkapnya.
5. (Opsional) Verifikasi kepemilikan aplikasi Android Anda.
6. Klik Create.

iOS

1. Pilih jenis aplikasi iOS.
2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page project Anda untuk mengidentifikasi klien.
3. 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 General atau panel Penandatanganan & Kemampuan editor project Xcode. ID paket juga ditampilkan di bagian Informasi Umum pada halaman Informasi Aplikasi untuk aplikasi tersebut di situs App Store Connect Apple.
4. (Opsional)

   Masukkan ID App Store aplikasi Anda jika aplikasi dipublikasikan di App Store Apple. ID Toko adalah string numerik yang disertakan di setiap URL Apple App Store.

   1. Buka aplikasi Apple App Store di perangkat iOS atau iPadOS Anda.
   2. Telusuri aplikasi Anda.
   3. Pilih tombol Share (simbol persegi dan panah atas).
   4. Pilih Salin Link.
   5. Tempelkan link ke editor teks. ID App Store adalah bagian akhir URL.

      Contoh: https://apps.apple.com/app/google/id284815942

5. (Opsional)

   Masukkan ID Tim Anda. Baca artikel Menemukan ID Tim dalam dokumentasi Akun Developer Apple untuk mengetahui informasi selengkapnya.

6. Klik Create.

UWP

1. Pilih jenis aplikasi Universal Windows Platform.
2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di Credentials page project Anda untuk mengidentifikasi klien.
3. Masukkan ID Microsoft Store yang berisi 12 karakter untuk aplikasi Anda. Anda dapat menemukan nilai ini di Pusat Partner Microsoft di halaman Identitas aplikasi di bagian Pengelolaan aplikasi.
4. Klik Create.

Untuk aplikasi UWP, skema URI kustom tidak boleh lebih dari 39 karakter.

Skema URI kustom (Android, iOS, UWP)

Skema URI kustom adalah bentuk deep link yang menggunakan skema yang didefinisikan secara kustom untuk membuka aplikasi Anda.

Penting: Skema URI kustom tidak lagi didukung di aplikasi Chrome baru dan dinonaktifkan secara default pada klien Android baru karena adanya risiko peniruan identitas aplikasi.

Alternatif selain menggunakan skema URI kustom di Android

Gunakan Login dengan Google untuk SDK Android yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda sehingga tidak diperlukan lagi 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 menggunakan Login dengan Google untuk Android SDK yang direkomendasikan:

1. Update kode Anda untuk menggunakan Google Sign-In SDK.
2. Nonaktifkan dukungan untuk skema kustom di Konsol API Google.

Catatan: Anda harus menyelesaikan dan men-deploy pembaruan kode (dengan memperhitungkan waktu adopsi di seluruh basis pengguna atau perangkat yang lebih lama) sebelum menonaktifkan dukungan untuk skema kustom di Konsol API Google agar pengguna tidak mendapatkan pesan error invalid_request saat mereka mencoba menggunakan aplikasi Anda.

Ikuti langkah-langkah di bawah untuk bermigrasi ke Google Sign-In Android SDK:

1. Update kode Anda untuk menggunakan Login dengan Google Android SDK:
   1. Periksa kode Anda untuk mengidentifikasi tempat Anda mengirim permintaan ke server OAuth 2.0 Google; jika menggunakan skema kustom, permintaan Anda akan terlihat seperti berikut:

        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 parameter redirect_uri untuk mengetahui detail selengkapnya tentang format nilai skema URI kustom.
   2. Catat parameter permintaan scope dan client_id yang akan Anda perlukan untuk mengonfigurasi Login dengan Google SDK.
      Catatan: Jika Anda menggunakan library pihak ketiga, tinjau file konfigurasi library untuk menemukan informasi ini.
   3. Ikuti petunjuk Memulai Mengintegrasikan Login dengan Google ke dalam 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.
   4. Ikuti petunjuk Mengaktifkan akses API Sisi Server. Hal ini mencakup langkah-langkah berikut:
      1. Gunakan metode getServerAuthCode untuk mengambil kode autentikasi untuk cakupan yang izinnya Anda minta.
      2. Kirim kode autentikasi ke backend aplikasi Anda untuk ditukarkan dengan token akses & refresh.
      3. Gunakan token akses yang diambil untuk melakukan panggilan ke Google API atas nama pengguna.
      Catatan: Jika aplikasi Anda tidak memerlukan akses offline, ikuti petunjuk ini untuk meminta akses API sisi klien.
2. Nonaktifkan dukungan untuk skema kustom di Konsol API Google:
   1. Buka daftar OAuth 2.0 credentials dan pilih klien Android Anda.
   2. 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 dengan mengikuti petunjuk di bawah ini:

1. Buka daftar OAuth 2.0 credentials, lalu pilih klien Android Anda.
2. Buka bagian Advanced Settings, centang kotak Enable Custom URI Scheme, lalu klik Save untuk mengaktifkan dukungan skema URI kustom.

Alternatif selain menggunakan skema URI kustom pada aplikasi Chrome

Gunakan Chrome Identity API yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda sehingga tidak diperlukan lagi URI pengalihan.

Memverifikasi kepemilikan aplikasi (Android, Chrome)

Anda dapat memverifikasi kepemilikan aplikasi untuk mengurangi risiko peniruan identitas aplikasi.

Android

Catatan: Verifikasi kepemilikan aplikasi Android saat ini hanya tersedia untuk aplikasi Google Play.

Untuk menyelesaikan proses verifikasi, Anda dapat menggunakan Akun Developer Google Play jika ada 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 akan 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 hal 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, gunakan akun Developer Chrome Web Store Anda. 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 akan 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, perintah error akan ditampilkan.

Untuk memperbaiki verifikasi yang gagal, coba hal berikut:

• Pastikan ada item yang terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang Anda selesaikan verifikasinya.
• Pastikan Anda adalah penerbit aplikasi, artinya Anda harus menjadi penerbit individual aplikasi atau anggota penerbit 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 telah disinkronkan di Dasbor Developer Chrome Web Store. Pelajari lebih lanjut cara menyinkronkan daftar keanggotaan penayang.

Alamat IP loopback (macOS, Linux, desktop Windows)

Penting: Opsi pengalihan alamat IP loopback TIDAK DIGUNAKAN LAGI untuk jenis klien OAuth Android, aplikasi Chrome, dan iOS. Tinjau panduan migrasi alamat IP loopback untuk mengetahui petunjuk tentang cara bermigrasi ke alternatif yang didukung.

Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus memproses di server web lokal. Hal ini bisa dilakukan di banyak platform, tetapi tidak semuanya. Namun, jika platform Anda mendukungnya, ini adalah mekanisme yang direkomendasikan untuk mendapatkan kode otorisasi.

Saat menerima respons otorisasi, aplikasi Anda harus merespons otorisasi dengan menampilkan halaman HTML yang menginstruksikan pengguna untuk menutup browser dan kembali ke aplikasi Anda untuk mendapatkan kegunaan terbaik.

Penggunaan yang direkomendasikan	Aplikasi desktop macOS, Linux, dan Windows (tetapi bukan Universal Windows Platform)
Nilai formulir	Tetapkan jenis aplikasi ke Aplikasi desktop.

Catatan: Lihat definisi parameter redirect_uri untuk mengetahui informasi selengkapnya tentang alamat IP loopback. Anda juga dapat menggunakan localhost sebagai pengganti IP loopback, tetapi konfigurasi ini dapat menyebabkan masalah pada firewall klien. Sebagian besar, tetapi tidak semua, firewall mengizinkan komunikasi loopback.

Salin/tempel manual

Penting: Opsi salin/tempel manual, yang juga disebut sebagai metode pengalihan out of band (OOB), tidak lagi didukung. Tinjau panduan migrasi OOB untuk mendapatkan petunjuk tentang cara bermigrasi ke alternatif yang aman.

Mengidentifikasi cakupan akses

Dengan cakupan, aplikasi Anda hanya dapat 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 untuk mendapatkan izin pengguna.

Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya identifikasi cakupan yang memerlukan izin untuk diakses oleh aplikasi Anda.

Catatan: Otorisasi inkremental tidak didukung untuk aplikasi atau perangkat terinstal.

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 mungkin Anda gunakan untuk mengakses Google API.

Jika aplikasi publik Anda menggunakan cakupan yang mengizinkan akses ke data pengguna tertentu, aplikasi tersebut harus menyelesaikan proses verifikasi. Jika melihat aplikasi yang belum terverifikasi di layar saat menguji aplikasi, Anda harus mengirimkan permintaan verifikasi untuk menghapusnya. Cari tahu selengkapnya tentang aplikasi yang belum diverifikasi dan dapatkan jawaban atas pertanyaan umum (FAQ) tentang verifikasi aplikasi di Pusat Bantuan.

Memperoleh token akses OAuth 2.0

Langkah berikut menunjukkan cara aplikasi Anda berinteraksi dengan server OAuth 2.0 Google untuk mendapatkan izin pengguna guna 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 login

Google mendukung protokol Proof Key for Code Exchange (PKCE) agar alur aplikasi yang diinstal lebih aman. Pemverifikasi kode unik dibuat untuk setiap permintaan otorisasi, dan nilai yang diubah, yang disebut "code_challenge", dikirim ke server otorisasi untuk mendapatkan kode otorisasi.

Membuat pemverifikasi kode

code_verifier adalah string acak kriptografi entropi tinggi yang menggunakan karakter [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", dengan panjang minimum 43 karakter dan panjang maksimum 128 karakter.

Pemverifikasi kode harus memiliki entropi yang cukup sehingga sulit untuk menebak nilainya.

Membuat tantangan kode

Dua metode pembuatan tantangan kode didukung.

Metode Pembuatan Tantangan Kode
S256 (direkomendasikan)	Tantangan kodenya adalah hash SHA256 berenkode Base64URL (tanpa padding) dari pemverifikasi kode. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
biasa	Verifikasi kode adalah nilai yang sama dengan pemverifikasi kode yang dibuat di atas. code_challenge = code_verifier

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 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 mengirimkan respons ke aplikasi Anda. Ada beberapa opsi pengalihan yang tersedia untuk aplikasi terinstal, dan Anda sudah 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 API Console Credentials pageklien. Jika nilai ini tidak cocok dengan URI yang diberi otorisasi, Anda akan mendapatkan error redirect_uri_mismatch. Tabel di bawah menampilkan parameter value redirect_uri yang sesuai untuk setiap metode: Nilai redirect_uri Skema URI kustom com.example.app:redirect_uri_path atau com.googleusercontent.apps.123:redirect_uri_path com.example.app adalah notasi DNS terbalik dari domain yang berada di bawah kontrol Anda. Skema kustom harus berisi titik agar valid. com.googleusercontent.apps.123 adalah notasi DNS terbalik dari client ID. redirect_uri_path adalah komponen jalur opsional, seperti /oauth2redirect. Perhatikan bahwa jalur harus diawali dengan satu garis miring, yang berbeda dengan URL HTTP biasa. Catatan : Skema URI kustom tidak lagi didukung di aplikasi Chrome dan dinonaktifkan secara default di Android. Pelajari lebih lanjut alternatif skema kustom untuk aplikasi Android dan Chrome. Alamat IP loop http://127.0.0.1:port atau http://[::1]:port Buat kueri platform Anda untuk alamat IP loopback yang relevan dan mulai pemroses HTTP pada port acak yang tersedia. Ganti port dengan nomor port sebenarnya yang diproses aplikasi Anda. Perhatikan bahwa dukungan untuk opsi pengalihan alamat IP loopback pada aplikasi seluler TIDAK DIGUNAKAN LAGI.
response_type	Wajib Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Setel parameter value ke code untuk aplikasi terinstal.
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. Dengan cakupan, aplikasi Anda dapat 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 untuk mendapatkan izin pengguna. 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 menyediakan daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API.
code_challenge	Direkomendasikan Menentukan code_verifier dienkode yang akan digunakan sebagai tantangan sisi server selama pertukaran kode otorisasi. Lihat bagian membuat tantangan kode di atas untuk informasi selengkapnya.
code_challenge_method	Direkomendasikan Menentukan metode yang digunakan untuk mengenkode code_verifier yang akan digunakan selama pertukaran kode otorisasi. Parameter ini harus digunakan dengan parameter code_challenge yang dijelaskan di atas. Nilai default code_challenge_method adalah plain jika tidak ada dalam permintaan yang menyertakan code_challenge. Satu-satunya nilai yang didukung untuk parameter ini adalah S256 atau plain.
state	Direkomendasikan Menentukan nilai string yang digunakan aplikasi untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi. Server menampilkan nilai persis yang Anda kirim sebagai pasangan name=value dalam ID fragmen URL (#) dari redirect_uri setelah pengguna menyetujui atau menolak permintaan akses aplikasi Anda. Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar di aplikasi, mengirim nonce, dan mengurangi pemalsuan permintaan lintas situs. Karena redirect_uri dapat ditebak, penggunaan nilai state dapat meningkatkan keyakinan Anda bahwa koneksi masuk merupakan hasil dari permintaan autentikasi. Jika Anda membuat string acak atau mengenkode hash cookie atau nilai lain yang menangkap status klien, Anda juga dapat memvalidasi respons untuk memastikan juga bahwa permintaan dan respons berasal dari browser yang sama, sehingga memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs. Lihat dokumentasi OpenID Connect untuk contoh cara membuat dan mengonfirmasi token state.
login_hint	Opsional Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi tersebut dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login, baik dengan mengisi kolom email secara otomatis di formulir login maupun dengan memilih sesi multi-login yang sesuai. Tetapkan parameter value ke alamat email atau ID sub, yang setara dengan ID Google pengguna.

Catatan: otorisasi inkremental dengan aplikasi terinstal tidak didukung karena klien tidak dapat menjaga kerahasiaan client_secret.

Contoh URL otorisasi

Tab di bawah ini menampilkan contoh URL otorisasi untuk opsi URI pengalihan yang berbeda.

Setiap URL meminta akses ke cakupan yang mengizinkan akses untuk mengambil laporan YouTube Analytics pengguna.

URL tersebut 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 memutuskan apakah akan memberikan akses yang diminta kepada aplikasi Anda. Pada tahap ini, Google akan menampilkan jendela izin yang menampilkan nama aplikasi Anda dan layanan Google API yang izin aksesnya diminta dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Selanjutnya, pengguna dapat setuju untuk memberikan akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan tersebut.

Aplikasi Anda tidak perlu melakukan apa pun pada tahap ini karena menunggu respons dari server OAuth 2.0 Google yang menunjukkan apakah akses telah diberikan. Respons tersebut dijelaskan dalam langkah berikut.

Error

Permintaan ke endpoint otorisasi OAuth 2.0 Google mungkin menampilkan pesan error yang dilihat pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode error umum dan resolusi yang disarankan tercantum di bawah ini.

admin_policy_enforced

Akun Google tidak dapat mengizinkan satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace mereka. Baca artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal yang mengakses data Google Workspace untuk mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan 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 menemukan pesan error ini saat membuka permintaan otorisasi di android.webkit.WebView. Sebagai gantinya, developer sebaiknya menggunakan library Android seperti Login dengan Google untuk Android atau AppAuth untuk Android dari OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi Android membuka link web umum di agen pengguna tersemat dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum untuk dibuka di pengendali link default sistem operasi, yang mencakup pengendali Link Aplikasi Android atau aplikasi browser default. Library Tab Khusus Android juga merupakan opsi yang didukung.

iOS

Developer iOS dan macOS mungkin mengalami error ini saat membuka permintaan otorisasi di WKWebView. Sebagai gantinya, developer sebaiknya menggunakan library iOS seperti Login dengan Google untuk iOS atau AppAuth for iOS dari OpenID Foundation.

Developer web dapat mengalami error ini saat aplikasi iOS atau macOS membuka link web umum di agen pengguna tersemat dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum untuk dibuka di pengendali link default sistem operasi, yang 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 mendapatkan informasi selengkapnya tentang opsi konfigurasi ini, lihat bagian Jenis pengguna di artikel bantuan Menyiapkan layar izin OAuth Anda.

invalid_grant

Jika Anda menggunakan pemverifikasi dan verifikasi kode, parameter code_callenge tidak valid atau tidak ada. Pastikan parameter code_challenge disetel dengan benar.

Saat memuat ulang token akses, masa berlaku token mungkin telah habis atau dibatalkan. Autentikasi pengguna lagi dan minta izin pengguna untuk mendapatkan token baru. Jika terus mengalami error ini, pastikan aplikasi Anda telah dikonfigurasi dengan benar dan gunakan 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 diotorisasi 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 mungkin merujuk ke alur out-of-band (OOB) OAuth yang tidak digunakan lagi dan tidak lagi didukung. Lihat panduan migrasi untuk memperbarui integrasi Anda.

invalid_request

Ada yang salah dengan permintaan yang Anda buat. Hal ini dapat disebabkan oleh beberapa alasan:

• Permintaan tidak diformat dengan benar
• Permintaan tidak memiliki parameter yang diperlukan
• Permintaan tersebut menggunakan metode otorisasi yang tidak didukung oleh Google. Memverifikasi bahwa integrasi OAuth Anda menggunakan metode integrasi yang direkomendasikan
• Skema kustom digunakan untuk URI pengalihan : Jika Anda melihat pesan error Skema URI kustom tidak didukung pada aplikasi Chrome atau Skema URI kustom tidak diaktifkan untuk klien Android, artinya Anda menggunakan skema URI kustom yang tidak didukung pada 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, 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 di 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	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 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 memberikan otorisasi permintaan Google API.
expires_in	Sisa masa berlaku 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 yang ditandatangani secara digital tentang pengguna.
refresh_token	Token yang dapat Anda gunakan untuk mendapatkan token akses yang baru. Token refresh berlaku hingga pengguna mencabut akses. Perhatikan bahwa token refresh selalu ditampilkan untuk aplikasi terinstal.
scope	Cakupan akses yang diberikan oleh access_token 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.

Penting: Aplikasi Anda harus menyimpan kedua token di lokasi yang aman dan tahan lama, yang dapat diakses di antara berbagai pemanggilan aplikasi Anda. Dengan token refresh, aplikasi Anda dapat memperoleh token akses baru jika token yang Anda miliki sudah tidak berlaku. Oleh karena itu, jika aplikasi Anda kehilangan token refresh, pengguna harus mengulangi alur izin OAuth 2.0 agar aplikasi Anda bisa mendapatkan token refresh baru.

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"
}

Catatan: Aplikasi Anda harus mengabaikan kolom tidak dikenal yang disertakan dalam respons.

Memanggil Google API

Setelah aplikasi memperoleh 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 dalam 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 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 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

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

Memuat ulang token akses

Token akses akan habis masa berlakunya secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat me-refresh token akses tanpa meminta izin kepada pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token tersebut.

Untuk me-refresh token akses, aplikasi Anda akan mengirimkan permintaan POST HTTPS ke server otorisasi Google (https://oauth2.googleapis.com/token) yang menyertakan parameter berikut:

Kolom
client_id	Client ID yang diperoleh dari API Console.
client_secret	Rahasia klien yang diperoleh dari API Console. (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 batasan per kombinasi klien/pengguna, dan satu batas 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 mencapai batas ini, yang dalam hal ini token refresh yang lebih lama akan berhenti berfungsi.

Mencabut token

Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Pengguna dapat mencabut akses dengan membuka Setelan Akun. Lihat 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 sangat penting jika pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan 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 terkait, token refresh juga akan dicabut.

Jika pencabutan berhasil diproses, kode status HTTP respons adalah 200. Untuk kondisi error, kode status HTTP 400 akan ditampilkan bersama dengan kode error.

Catatan: Setelah respons pencabutan berhasil, mungkin perlu waktu beberapa saat sebelum pencabutan diterapkan sepenuhnya.

Bacaan Lebih Lanjut

Best Current Practice OAuth 2.0 untuk Aplikasi Native menetapkan banyak praktik terbaik yang didokumentasikan di sini.