OAuth 2.0 untuk Aplikasi Seluler & Desktop

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:

1. Open the API Library dalam 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.

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.

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 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.

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:

YouTube Reporting API menggunakan cakupan berikut:

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.

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, 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:

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 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.

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

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.

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:

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:

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:

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.