OAuth 2.0 untuk Aplikasi Seluler & Desktop

Catatan: Jika Anda baru menggunakan OAuth 2.0, sebaiknya baca Ringkasan OAuth 2.0 sebelum memulai. Tujuan merangkum alur OAuth 2.0 yang didukung Google, yang dapat membantu Anda memastikan Anda telah memilih alur yang tepat untuk aplikasi Anda.

Dokumen ini menjelaskan cara aplikasi diinstal pada perangkat seperti ponsel, tablet, dan komputer menggunakan endpoint OAuth 2.0 Google untuk mengotorisasi akses ke Google API.

OAuth 2.0 memungkinkan pengguna untuk berbagi data tertentu dengan aplikasi sambil tetap mempertahankan nama pengguna, {i>password<i}, dan informasi lainnya secara rahasia. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna untuk menyimpan file di Google Drive mereka.

Aplikasi terinstal didistribusikan ke setiap perangkat, dan diasumsikan bahwa aplikasi tersebut tidak bisa menyimpan rahasia. Pengguna 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 menyediakan URI pengalihan lokal untuk menangani respons dari server otorisasi Google.

Alternatif

Untuk aplikasi seluler, Anda dapat memilih menggunakan Masuk dengan Google untuk Android atau iOS. Login dengan Google {i>library<i} klien menangani otentikasi dan otorisasi pengguna, dan mungkin lebih mudah untuk daripada protokol tingkat yang lebih rendah yang dijelaskan di sini.

Untuk aplikasi yang berjalan di perangkat yang tidak mendukung browser sistem atau yang memiliki input terbatas yang berbeda, 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: Windows Contoh

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:

1. Open the API Library di Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library mencantumkan semua API yang tersedia, yang dikelompokkan menurut produk keluarga dan popularitas. Jika API yang ingin Anda aktifkan tidak terlihat dalam daftar, gunakan penelusuran untuk temukan, atau klik Lihat Semua di kategori produknya.
4. Pilih API yang ingin Anda aktifkan, lalu klik tombol Aktifkan.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Membuat 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 > Client ID OAuth yang baru.
3. Bagian di bawah ini menjelaskan jenis klien dan metode pengalihan yang didukung oleh server otorisasi. Pilih jenis klien yang direkomendasikan untuk aplikasi, beri nama klien OAuth, dan setel kolom lain dalam formulir sebagai yang sesuai.

Android

1. Pilih jenis aplikasi Android.
2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan pada Credentials page untuk mengidentifikasi klien.
3. Masukkan nama paket aplikasi Android Anda. Nilai ini ditentukan dalam kolom Atribut package dari elemen <manifest> dalam file manifes aplikasi.
4. Masukkan sidik jari sertifikat penandatanganan SHA-1 dari distribusi aplikasi.
   • Jika aplikasi Anda menggunakan penandatanganan aplikasi oleh Google Play, salin SHA-1 sidik jari dari halaman penandatanganan aplikasi Konsol Play.
   • Jika Anda mengelola keystore dan kunci penandatanganan Anda sendiri, gunakan utilitas keytool disertakan dengan Java untuk mencetak informasi sertifikat dalam format yang dapat dibaca manusia. Salin Nilai SHA1 di bagian Certificate fingerprints pada output keytool. Lihat Mengautentikasi Klien di Dokumentasi Google API untuk Android untuk informasi selengkapnya.
5. (Opsional) Verifikasi kepemilikan Android Anda aplikasi.
6. Klik Buat.

iOS

1. Pilih jenis aplikasi iOS.
2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan pada Credentials page untuk mengidentifikasi klien.
3. Masukkan ID paket untuk aplikasi Anda. ID paket adalah nilai CFBundleIdentifier dalam file resource daftar properti informasi aplikasi Anda (info.plist). Nilainya paling sering ditampilkan di panel {i>General<i} atau Panel kemampuan pada Editor project Xcode. ID paket juga ditampilkan di bagian Informasi Umum laman Informasi Aplikasi untuk aplikasi 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 kotak dan panah ke atas).
   4. Pilih Salin Link.
   5. Tempelkan link ke editor teks. ID App Store adalah bagian akhir dari URL.

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

5. (Opsional)

   Masukkan ID Tim Anda. Lihat Menemukan ID Tim di dokumentasi Akun Developer Apple untuk mengetahui informasi selengkapnya.

6. Klik Buat.

UWP

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

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.

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

Alternatif untuk menggunakan skema URI kustom di Android

Gunakan Login dengan Google untuk Android SDK yang memberikan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga URI pengalihan.

Cara bermigrasi ke Login dengan Google untuk Android SDK

Jika saat ini Anda menggunakan skema kustom untuk integrasi OAuth di Android, Anda harus selesaikan tindakan di bawah untuk bermigrasi sepenuhnya agar dapat menggunakan Login dengan Google SDK Android:

1. Perbarui kode Anda untuk menggunakan SDK Login dengan Google.
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 Google Sign-In Android SDK:
   1. Periksa kode untuk mengidentifikasi lokasi 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 di contoh di atas. Lihat redirect_uri definisi parameter untuk detail selengkapnya tentang format nilai skema URI kustom.
   2. Catat parameter permintaan scope dan client_id yang Anda harus mengonfigurasi Google Sign-In SDK.
      Catatan: Jika Anda menggunakan library pihak ketiga, tinjau file konfigurasi untuk menemukan informasi ini.
   3. Ikuti Mulai Mengintegrasikan Login dengan Google ke dalam Aplikasi Android Anda petunjuk untuk menyiapkan SDK. Anda dapat melewati Dapatkan langkah OAuth 2.0 client ID server backend Anda seperti yang akan Anda gunakan kembali client_id yang Anda ambil dari langkah sebelumnya.
   4. Ikuti Mengaktifkan akses API Sisi Server petunjuk. Hal ini mencakup langkah-langkah berikut:
      1. Gunakan metode getServerAuthCode untuk mengambil kode autentikasi untuk cakupan yang izinnya Anda minta.
      2. Mengirim kode autentikasi ke backend aplikasi untuk menukarnya dengan akses & memuat ulang sebelumnya yang benar.
      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 Kredensial OAuth 2.0 dan pilih klien Android Anda.
   2. Buka bagian Setelan Lanjutan, hapus centang pada Kotak centang Enable Custom URI Scheme, lalu klik Save untuk menonaktifkan dukungan skema URI kustom.

Mengaktifkan skema URI kustom

Jika alternatif yang disarankan tidak berhasil, Anda dapat mengaktifkan skema URI kustom untuk Klien Android dengan mengikuti petunjuk di bawah ini:

1. Buka Daftar kredensial OAuth 2.0 dan pilih klien Android Anda.
2. Buka bagian Setelan Lanjutan, periksa Kotak centang Enable Custom URI Scheme, lalu klik Save untuk mengaktifkan dukungan skema URI kustom.

Alternatif untuk menggunakan skema URI kustom di aplikasi Chrome

Gunakan Chrome Identity API yang memberikan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga 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 Google Play aplikasi.

Untuk menyelesaikan proses verifikasi, Anda dapat menggunakan Akun Developer Google Play jika Anda memilikinya dan aplikasi Anda terdaftar di Konsol Google Play. Hal berikut persyaratan 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 sebagai klien OAuth Android yang Anda untuk menyelesaikan verifikasi.
• Anda harus memiliki izin Admin untuk aplikasi di Konsol Google Play. Pelajari lebih lanjut tentang 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 dari 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 menggunakan ID item yang sama dengan klien OAuth Ekstensi Chrome, Anda sedang menyelesaikan verifikasi.
• Anda harus menjadi penayang untuk item Chrome Web Store. Pelajari lebih lanjut tentang 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: Setelah menyelesaikan proses verifikasi, tunggu beberapa menit yang memberikan akses ke akun Anda.

Jika verifikasi berhasil, notifikasi akan ditampilkan untuk mengonfirmasi keberhasilan dari proses verifikasi. Jika tidak, dialog error akan ditampilkan.

Untuk memperbaiki verifikasi yang gagal, coba langkah berikut:

• Pastikan ada item yang terdaftar di Dasbor Pengembang Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang sedang Anda selesaikan verifikasinya.
• Pastikan Anda adalah penayang aplikasi, yaitu Anda harus merupakan penerbit perorangan aplikasi atau anggota penerbit grup aplikasi. Pelajari lebih lanjut tentang pengelolaan akses di Dasbor Developer Chrome Web Store.
• Jika Anda baru saja memperbarui daftar penayang grup, pastikan keanggotaan penayang grup tersebut disinkronkan di Dasbor Developer Chrome Web Store. Pelajari lebih lanjut tentang menyinkronkan daftar keanggotaan penayang Anda.

Alamat IP loopback (macOS, Linux, desktop Windows)

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

Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus memantau 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.

Ketika 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	Setel jenis aplikasi ke Aplikasi desktop.

Catatan: Lihat Definisi parameter redirect_uri untuk informasi lebih lanjut tentang alamat IP {i>loopback<i}. Anda juga dapat menggunakan localhost sebagai pengganti IP loopback, tetapi konfigurasi ini dapat menyebabkan masalah pada {i>firewall<i} klien. Sebagian besar, tetapi tidak semua, firewall memungkinkan komunikasi loopback.

Salin/tempel manual

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

Mengidentifikasi cakupan akses

Dengan cakupan, aplikasi Anda dapat hanya meminta akses ke resource yang diperlukannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Oleh karena itu, mungkin merupakan hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan aplikasi Anda memerlukan izin untuk mengaksesnya.

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

Dokumen Cakupan OAuth 2.0 API berisi daftar cakupan yang dapat Anda gunakan untuk mengakses Google API.

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

Mendapatkan token akses OAuth 2.0

Langkah-langkah berikut menunjukkan cara aplikasi Anda berinteraksi dengan server OAuth 2.0 Google untuk mendapatkan izin pengguna untuk melakukan permintaan API atas nama pengguna. Permohonan Anda harus memiliki izin sebelum dapat mengeksekusi permintaan Google API yang memerlukan otorisasi pengguna.

Langkah 1: Buat pemverifikasi kode dan verifikasi

Google mendukung Kunci Bukti untuk Pertukaran Kode (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 entropi tinggi yang menggunakan string 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 tidak praktis untuk menebak nilai.

Membuat tantangan kode

Dua metode pembuatan tantangan kode didukung.

Metode Pembuatan Tantangan Kode
S256 (direkomendasikan)	Tantangan kode adalah hash kode SHA256 yang dienkode Base64URL (tanpa padding) pemverifikasi data. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
biasa	Tantangan kode adalah nilai yang sama dengan pemverifikasi kode yang dihasilkan 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, mengotentikasi 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:

Parameter
client_id	Wajib Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di kolom 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 harus menyiapkan kredensial otorisasi dengan metode pengalihan tertentu saat ini. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk OAuth 2.0 klien, yang Anda konfigurasikan di API Console Credentials page. Jika nilai ini tidak sesuai dengan URI yang diberi otorisasi, Anda akan mendapatkan error redirect_uri_mismatch. Tabel di bawah menampilkan nilai parameter 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 di bagian kendali Anda. Skema kustom harus berisi titik agar valid. com.googleusercontent.apps.123 adalah notasi DNS terbalik dari dengan ID klien. redirect_uri_path adalah komponen jalur opsional, seperti /oauth2redirect. Perhatikan bahwa jalur harus dimulai dengan satu /, yang berbeda dari URL HTTP biasa. Catatan : Skema URI kustom tidak lagi didukung di aplikasi Chrome dan dinonaktifkan secara {i> default<i} di Android. Pelajari lebih lanjut alternatif skema kustom untuk aplikasi Android dan Chrome. Alamat IP berulang http://127.0.0.1:port atau http://[::1]:port Buat kueri untuk mendapatkan alamat IP loopback yang relevan pada platform Anda dan mulai lakukan HTTP pada porta acak yang tersedia. Ganti port dengan yang sebenarnya nomor porta yang didengarkan oleh aplikasi Anda. Perhatikan bahwa dukungan untuk opsi pengalihan alamat IP loopback di seluler aplikasi Anda adalah TIDAK DIGUNAKAN LAGI.
response_type	Wajib Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Setel nilai parameter ke code untuk aplikasi terinstal.
scope	Wajib J dipisahkan spasi daftar cakupan yang mengidentifikasi sumber daya yang dapat diakses aplikasi Anda di atas nama pengguna. Nilai ini memberi tahu layar izin yang ditampilkan Google kepada . Dengan cakupan, aplikasi Anda dapat hanya meminta akses ke resource yang diperlukan sekaligus memungkinkan pengguna mengontrol jumlah akses yang mereka berikan kepada Anda aplikasi. Jadi, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna.
code_challenge	Direkomendasikan Menentukan code_verifier yang dienkode yang akan digunakan sebagai sisi server selama pertukaran kode otorisasi. Lihat buat kode tantangan 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 bersama Parameter code_challenge dijelaskan di atas. Nilai code_challenge_method ditetapkan secara default ke 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 di antara permintaan otorisasi dan respons server otorisasi. Server menampilkan nilai tepat yang Anda kirimkan sebagai pasangan name=value di kolom ID fragmen URL (#) dari redirect_uri setelah pengguna menyetujui atau menolak akses permintaan akses. Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar dalam aplikasi Anda, mengirimkan nonce, dan memitigasi permintaan lintas situs pemalsuan. Karena redirect_uri Anda dapat ditebak, menggunakan state nilai tersebut dapat meningkatkan jaminan bahwa koneksi masuk adalah hasil dari permintaan autentikasi. Jika Anda menghasilkan string acak atau mengenkode {i>hash<i} cookie atau nilai lain yang mencatat status klien, Anda dapat memvalidasi respons untuk pastikan juga bahwa permintaan dan respons berasal dari browser yang sama, memberikan perlindungan terhadap serangan seperti permintaan lintas situs pemalsuan. Lihat OpenID Connect dokumentasi untuk contoh cara membuat dan mengonfirmasi token state. Penting: Klien OAuth harus mencegah CSRF sebagaimana disebutkan dalam Spesifikasi OAuth2 . Salah satu cara untuk mencapainya adalah dengan menggunakan parameter state untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi.
login_hint	Opsional Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, parameter ini dapat digunakan untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login baik dengan mengisi otomatis kolom email di formulir login atau dengan memilih sesi multi-login yang sesuai. Setel nilai parameter ke alamat email atau ID sub, yang merupakan setara dengan ID Google pengguna.

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

Contoh URL otorisasi

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

URL-nya identik kecuali untuk nilai parameter redirect_uri. URL juga berisi parameter response_type dan client_id yang diperlukan sebagai parameter state opsional. Setiap URL berisi baris baru dan spasi untuk keterbacaan.

Skema URI kustom

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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. Di tahap ini, Google akan menampilkan jendela izin yang menampilkan nama aplikasi Anda dan Google API layanan yang meminta izin akses untuk mengakses dengan kredensial otorisasi pengguna dan ringkasan dari cakupan akses yang akan diberikan. Tujuan pengguna dapat menyetujui untuk memberikan akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan.

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

Error

Permintaan ke endpoint otorisasi OAuth 2.0 Google mungkin menampilkan pesan error yang ditampilkan kepada pengguna alih-alih alur otentikasi dan otorisasi yang diharapkan. Kode error umum dan yang disarankan resolusi 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 data pihak ketiga & aplikasi internal mengakses data Google Workspace untuk informasi selengkapnya tentang bagaimana administrator dapat membatasi akses ke semua cakupan atau cakupan yang dibatasi hingga akses diberikan secara eksplisit ke ID klien OAuth Anda.

disallowed_useragent

Endpoint otorisasi ditampilkan di dalam agen pengguna tersemat yang tidak diizinkan oleh Kebijakan OAuth 2.0.

Android

Developer Android mungkin melihat pesan error ini saat membuka permintaan otorisasi di android.webkit.WebView Sebaiknya developer menggunakan library Android seperti Login dengan Google untuk Android atau OpenID Foundation AppAuth untuk Android.

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 di situs Anda. Developer harus mengizinkan link umum agar terbuka di pengendali link default sistem operasi, yang mencakup Link Aplikasi Android atau aplikasi browser default. Tujuan Tab Khusus Android library juga merupakan opsi yang didukung.

iOS

Developer iOS dan macOS mungkin mengalami error ini saat membuka permintaan otorisasi di WKWebView Sebaiknya developer menggunakan library iOS seperti Login dengan Google untuk iOS atau OpenID Foundation AppAuth untuk iOS.

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 di situs Anda. Developer harus mengizinkan link umum agar terbuka di pengendali link default sistem operasi, yang mencakup Link Universal atau aplikasi browser default. Tujuan SFSafariViewController library juga merupakan opsi yang didukung.

org_internal

Client ID OAuth dalam permintaan adalah bagian dari project yang membatasi akses ke Akun Google di tindakan Organisasi Google Cloud. Untuk informasi selengkapnya tentang opsi konfigurasi ini, lihat Jenis pengguna di artikel bantuan Menyiapkan layar izin OAuth.

invalid_grant

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

Saat memperbarui token akses, masa berlaku token mungkin telah berakhir atau telah dibatalkan. Autentikasi pengguna lagi dan minta izin pengguna untuk mendapatkan token baru. Jika Anda melanjutkan untuk melihat kesalahan ini, pastikan bahwa aplikasi Anda telah dikonfigurasi dengan benar dan bahwa Anda menggunakan token dan parameter yang benar dalam permintaan Anda. Jika tidak, akun pengguna mungkin memiliki telah dihapus atau dinonaktifkan.

redirect_uri_mismatch

redirect_uri yang diteruskan dalam permintaan otorisasi tidak cocok dengan URI pengalihan 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 memiliki tidak digunakan lagi dan tidak didukung lagi. Lihat panduan migrasi untuk memperbarui integrasi.

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. Verifikasi OAuth Anda menggunakan metode integrasi yang direkomendasikan
• Skema khusus digunakan untuk URI pengalihan : Jika Anda melihat pesan kesalahan Skema URI kustom tidak didukung di aplikasi Chrome atau Skema URI Kustom tidak diaktifkan untuk klien Android Anda, berarti Anda menggunakan URI kustom skema yang tidak didukung di aplikasi Chrome dan dinonaktifkan secara default di Android. Pelajari lebih lanjut skema URI kustom alternatif

Langkah 4: Tangani respons server OAuth 2.0

Cara aplikasi Anda menerima respons otorisasi bergantung pada skema URI pengalihan yang digunakannya. Terlepas dari skema ini, respons akan berisi kode otorisasi (code) atau error (error). Misalnya, error=access_denied menunjukkan bahwa pengguna menolak permintaan tersebut.

Jika pengguna memberikan akses ke aplikasi, Anda bisa menukar kode otorisasi dengan token akses dan token refresh seperti dijelaskan di langkah berikutnya.

Langkah 5: Tukarkan kode otorisasi untuk pembaruan dan akses token

Untuk menukar kode otorisasi dengan token akses, panggil metode Endpoint https://oauth2.googleapis.com/token, lalu 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 dijelaskan dalam OAuth 2.0 spesifikasi, 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 yang diberikan client_id.

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 akses jangka 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 yang ditandatangani secara digital tentang .
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 {i>string<i} yang peka huruf besar/kecil dan dipisahkan spasi.
token_type	Jenis token yang ditampilkan. Saat ini, nilai bidang ini selalu disetel ke Bearer.

Penting: Aplikasi Anda harus menyimpan kedua token di tempat yang aman berumur panjang yang dapat diakses di antara berbagai pemanggilan aplikasi Anda. Tujuan token refresh memungkinkan aplikasi Anda memperoleh token akses baru jika token yang Anda miliki tidak berlaku lagi. Oleh karena itu, jika aplikasi Anda kehilangan token refresh, pengguna harus mengulangi Alur izin OAuth 2.0 sehingga aplikasi Anda dapat memperoleh token refresh baru.

Cuplikan berikut menunjukkan contoh respons:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

Memanggil Google API

Setelah aplikasi Anda mendapatkan token akses, Anda bisa menggunakan token tersebut untuk melakukan panggilan ke API atas nama objek jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam sebagian besar Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil Drive Files API).

Anda dapat mencoba semua Google API dan melihat cakupannya di OAuth 2.0 Playground.

Contoh GET HTTP

Panggilan ke drive.files endpoint (Drive Files API) menggunakan HTTP Authorization: Bearer {i>header<i} akan terlihat seperti berikut. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Berikut adalah panggilan ke API yang sama untuk pengguna terautentikasi menggunakan access_token parameter string kueri:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Contoh curl

Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut adalah contoh yang menggunakan opsi header HTTP (lebih disukai):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Atau, sebagai alternatif, opsi parameter string kueri:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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.

Untuk memuat ulang token akses, aplikasi Anda mengirim POST HTTPS permintaan ke server otorisasi Google (https://oauth2.googleapis.com/token) yang mencakup 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 Android, iOS, atau Chrome.)
grant_type	Sebagai 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 menampilkan objek JSON yang berisi token akses baru. Cuplikan berikut menampilkan 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 diterbitkan; satu batas 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 masih valid. Jika pengajuan permohonan Anda meminta terlalu banyak token refresh, mungkin akan mencapai batas ini, sehingga 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 mengunjungi Setelan Akun. Lihat Hapus bagian akses situs atau aplikasi di situs pihak ketiga & aplikasi yang memiliki akses ke akun Anda dokumen dukungan untuk informasi selengkapnya.

Aplikasi juga dapat mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram penting jika pengguna berhenti berlangganan, menghapus aplikasi, atau sumber daya API yang dibutuhkan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, {i>SUMIF<i} memiliki daftar sel bagian dari proses penghapusan dapat mencakup permintaan API untuk memastikan yang diberikan ke aplikasi akan 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 tersebut adalah token akses dan memiliki token pembaruan yang sesuai, token pembaruan 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.

Catatan: Setelah respons pencabutan berhasil, mungkin diperlukan beberapa saat waktu sebelum pencabutan berlaku sepenuhnya.

Bacaan Lebih Lanjut

Praktik Terbaik Saat Ini IETF OAuth 2.0 untuk Aplikasi Native menerapkan banyak praktik terbaik yang didokumentasikan di sini.