OAuth 2.0 untuk Aplikasi Seluler & Desktop

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 server otorisasi. Pilih jenis klien yang direkomendasikan untuk aplikasi, beri nama klien OAuth, dan setel kolom lain dalam formulir sebagai yang sesuai.

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.

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

Mendapatkan token akses OAuth 2.0

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

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

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:

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.

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

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.

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:

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:

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

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:

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.

Bacaan Lebih Lanjut

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