Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses Google API melalui aplikasi yang berjalan pada perangkat seperti TV, konsol game, dan printer. Lebih khusus lagi, alur ini dirancang untuk perangkat yang tidak memiliki akses ke browser atau memiliki kemampuan input yang terbatas.
OAuth 2.0 memungkinkan pengguna berbagi data tertentu dengan aplikasi sambil menjaga nama pengguna, sandi, dan informasi lainnya tetap pribadi. Misalnya, aplikasi TV dapat menggunakan OAuth 2.0 untuk mendapatkan izin memilih file yang disimpan di Google Drive.
Karena aplikasi yang menggunakan alur ini didistribusikan ke setiap perangkat, diasumsikan bahwa aplikasi tidak dapat menyimpan rahasia. Pengguna dapat mengakses Google API saat pengguna ada di aplikasi atau saat aplikasi berjalan di latar belakang.
Alternatif
Jika Anda menulis aplikasi untuk platform seperti Android, iOS, macOS, Linux, atau Windows (termasuk Universal Windows Platform), yang memiliki akses ke browser dan kemampuan input penuh, gunakan alur OAuth 2.0 untuk aplikasi seluler dan desktop. (Anda harus menggunakan alur tersebut meskipun aplikasi Anda adalah alat command line tanpa antarmuka grafis.)
Jika Anda hanya ingin memproses login pengguna dengan Akun Google mereka dan menggunakan token ID JWT untuk mendapatkan informasi profil pengguna dasar, lihat Login di TV dan Perangkat Input Terbatas.
Prasyarat
Mengaktifkan API untuk project Anda
Aplikasi apa pun yang memanggil Google API harus mengaktifkan API tersebut di API Console.
Untuk mengaktifkan API untuk project Anda:
- Open the API Library di Google API Console.
- If prompted, select a project, or create a new one.
- API Library mencantumkan semua API yang tersedia, yang dikelompokkan berdasarkan kelompok produk dan popularitas. Jika API yang ingin Anda aktifkan tidak terlihat dalam daftar, gunakan penelusuran untuk mencarinya, atau klik Lihat Semua dalam kategori produknya.
- Pilih API yang ingin Anda aktifkan, lalu klik tombol Aktifkan.
- If prompted, enable billing.
- If prompted, read and accept the API's Terms of Service.
Membuat kredensial otorisasi
Setiap 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 Anda aktifkan untuk project tersebut.
- Go to the Credentials page.
- Klik Create credentials > OAuth client ID.
- Pilih jenis aplikasi TV dan Perangkat Input Terbatas.
- Beri nama klien OAuth 2.0, lalu klik Buat.
Mengidentifikasi cakupan akses
Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Oleh karena itu, 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 untuk diakses oleh aplikasi Anda.
Lihat daftar Cakupan yang diizinkan untuk aplikasi atau perangkat yang diinstal.
Mendapatkan token akses OAuth 2.0
Meskipun aplikasi Anda berjalan pada perangkat dengan kemampuan input yang terbatas, pengguna harus memiliki akses terpisah ke perangkat dengan kemampuan input yang lebih kaya untuk menyelesaikan alur otorisasi ini. Alur ini berisi langkah-langkah berikut:
- Aplikasi Anda mengirim permintaan ke server otorisasi Google yang mengidentifikasi cakupan yang akan diminta izin oleh aplikasi Anda untuk diakses.
- Server merespons dengan beberapa informasi yang digunakan pada langkah berikutnya, seperti kode perangkat dan kode pengguna.
- Anda menampilkan informasi yang dapat dimasukkan pengguna di perangkat terpisah untuk mengizinkan aplikasi Anda.
- Aplikasi Anda mulai memeriksa server otorisasi Google untuk menentukan apakah pengguna telah mengizinkan aplikasi Anda atau tidak.
- Pengguna beralih ke perangkat dengan kemampuan input yang lebih beragam, meluncurkan browser web, membuka URL yang ditampilkan di langkah 3, lalu memasukkan kode yang juga ditampilkan di langkah 3. Kemudian, pengguna dapat memberikan (atau menolak) akses ke aplikasi Anda.
- Respons berikutnya terhadap permintaan polling berisi token yang diperlukan aplikasi untuk mengizinkan permintaan atas nama pengguna. (Jika pengguna menolak akses ke aplikasi Anda, respons tidak berisi token.)
Gambar di bawah menggambarkan proses ini:
Bagian berikut menjelaskan langkah-langkah ini secara detail. Dengan mempertimbangkan rentang kemampuan dan lingkungan runtime yang mungkin dimiliki perangkat, contoh yang ditunjukkan dalam dokumen ini menggunakan utilitas command line curl. Contoh ini harus mudah ditransfer ke berbagai bahasa dan runtime.
Langkah 1: Minta kode perangkat dan pengguna
Pada langkah ini, perangkat Anda mengirimkan permintaan HTTP POST ke server otorisasi Google, di
https://oauth2.googleapis.com/device/code, yang mengidentifikasi aplikasi Anda
serta cakupan akses yang ingin diakses oleh aplikasi Anda atas nama pengguna.
Anda harus mengambil URL ini dari
dokumen Discovery menggunakan
nilai metadata device_authorization_endpoint. Sertakan parameter permintaan HTTP berikut:
| Parameter | |
|---|---|
client_id |
Wajib
Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Credentials page API Console. |
scope |
Wajib
Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menunjukkan layar izin yang ditampilkan Google kepada pengguna. Lihat daftar Cakupan yang diizinkan untuk aplikasi atau perangkat yang diinstal. Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan, sekaligus memungkinkan pengguna mengontrol jumlah akses yang diberikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan untuk mendapatkan izin pengguna. |
Contoh
Cuplikan berikut menunjukkan permintaan contoh:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=
Contoh ini menunjukkan perintah curl untuk mengirim permintaan yang sama:
curl -d "client_id=client_id&scope=" \
https://oauth2.googleapis.com/device/code
Langkah 2: Tangani respons server otorisasi
Server otorisasi akan menampilkan salah satu respons berikut:
Respons yang berhasil
Jika permintaan valid, respons Anda akan berupa objek JSON yang berisi properti berikut:
| Properti | |
|---|---|
device_code |
Nilai yang ditetapkan secara unik oleh Google untuk mengidentifikasi perangkat yang menjalankan aplikasi
yang meminta otorisasi. Pengguna akan mengotorisasi perangkat tersebut dari perangkat lain dengan kemampuan input yang lebih kaya. Misalnya, pengguna mungkin menggunakan laptop atau ponsel untuk mengizinkan
aplikasi yang berjalan di TV. Dalam hal ini, device_code mengidentifikasi TV.
Kode ini memungkinkan perangkat yang menjalankan aplikasi menentukan dengan aman apakah pengguna telah memberikan atau menolak akses. |
expires_in |
Durasi waktu, dalam detik, saat device_code dan user_code valid. Jika pada saat itu pengguna tidak menyelesaikan alur otorisasi dan perangkat Anda juga tidak melakukan polling untuk mengambil informasi tentang keputusan pengguna, Anda mungkin perlu memulai ulang proses ini dari langkah 1. |
interval |
Durasi waktu, dalam detik, saat perangkat harus menunggu di antara permintaan polling. Misalnya, jika nilainya adalah 5, perangkat Anda harus mengirimkan permintaan polling ke server otorisasi Google setiap lima detik. Lihat
langkah 3 untuk mengetahui detail selengkapnya. |
user_code |
Nilai peka huruf besar/kecil yang mengidentifikasi kepada Google cakupan yang diminta aksesnya oleh aplikasi. Antarmuka pengguna Anda akan meminta pengguna untuk memasukkan nilai ini di perangkat terpisah dengan kemampuan input yang lebih lengkap. Kemudian, Google akan menggunakan nilai tersebut untuk menampilkan kumpulan cakupan yang benar saat meminta pengguna untuk memberikan akses ke aplikasi Anda. |
verification_url |
URL yang harus dibuka pengguna, di perangkat terpisah, untuk memasukkan
user_code dan memberikan atau menolak akses ke aplikasi Anda. Antarmuka pengguna Anda
juga akan menampilkan nilai ini. |
Cuplikan berikut menunjukkan contoh respons:
{
"device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code": "GQVQ-JKEC",
"verification_url": "https://www.google.com/device",
"expires_in": 1800,
"interval": 5
}
Respons melampaui kuota
Jika permintaan kode perangkat Anda telah melebihi kuota yang terkait dengan client ID, Anda akan menerima respons 403, yang berisi error berikut:
{
"error_code": "rate_limit_exceeded"
}
Dalam hal ini, gunakan strategi backoff untuk mengurangi rasio permintaan.
Langkah 3: Tampilkan kode pengguna
Tampilkan verification_url dan user_code yang diperoleh pada langkah 2 kepada pengguna. Kedua nilai tersebut dapat berisi karakter apa pun yang dapat dicetak dari himpunan karakter US-ASCII. Konten
yang Anda tampilkan kepada pengguna harus meminta pengguna untuk membuka
verification_url di perangkat terpisah dan memasukkan user_code.
Rancang antarmuka pengguna (UI) Anda dengan mempertimbangkan aturan berikut:
user_codeuser_codeharus ditampilkan di kolom yang dapat menangani 15 karakter ukuran 'W'. Dengan kata lain, jika Anda dapat menampilkan kodeWWWWWWWWWWWWWWWdengan benar, UI Anda valid, dan sebaiknya gunakan nilai string tersebut saat menguji cara tampilanuser_codedi UI Anda.user_codepeka huruf besar/kecil dan tidak boleh dimodifikasi dengan cara apa pun, misalnya mengubah kasus atau menyisipkan karakter pemformatan lainnya.
verification_url- Ruang tempat Anda menampilkan
verification_urlharus cukup luas untuk menangani string URL yang terdiri dari 40 karakter. - Anda tidak boleh mengubah
verification_urldengan cara apa pun, kecuali jika ingin menghapus skema untuk ditampilkan. Jika Anda berencana menghapus skema (misalnyahttps://) dari URL untuk alasan tampilan, pastikan aplikasi Anda dapat menangani varianhttpdanhttps.
- Ruang tempat Anda menampilkan
Langkah 4: Polling server otorisasi Google
Karena pengguna akan menggunakan perangkat terpisah untuk membuka verification_url
dan memberikan (atau menolak) akses, perangkat yang meminta tidak akan otomatis diberi tahu saat pengguna
merespons permintaan akses. Karena alasan itu, perangkat yang meminta harus melakukan polling pada server
otorisasi Google untuk menentukan kapan pengguna merespons permintaan.
Perangkat yang meminta harus terus mengirimkan permintaan polling hingga perangkat menerima respons yang menunjukkan bahwa pengguna telah merespons permintaan akses atau hingga device_code dan user_code yang diperoleh dalam
langkah 2 sudah tidak berlaku. interval yang ditampilkan di langkah 2 menentukan jumlah
waktu, dalam detik, untuk menunggu di antara permintaan.
URL endpoint untuk polling adalah https://oauth2.googleapis.com/token. Permintaan polling
berisi parameter berikut:
| Parameter | |
|---|---|
client_id |
Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di Credentials page API Console. |
client_secret |
Rahasia klien untuk client_id yang disediakan. Anda dapat menemukan nilai ini di Credentials page API Console. |
device_code |
device_code yang ditampilkan oleh server otorisasi pada
langkah 2. |
grant_type |
Tetapkan nilai ini ke urn:ietf:params:oauth:grant-type:device_code. |
Contoh
Cuplikan berikut menunjukkan permintaan contoh:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
Contoh ini menunjukkan perintah curl untuk mengirim permintaan yang sama:
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
/token
Langkah 5: Pengguna merespons permintaan akses
Gambar berikut menampilkan halaman yang mirip dengan yang dilihat pengguna saat mereka membuka verification_url yang Anda tampilkan di langkah 3:
Setelah memasukkan user_code dan, jika belum login, pengguna melihat layar izin seperti yang ditampilkan di bawah:
Langkah 6: Tangani respons terhadap permintaan polling
Server otorisasi Google merespons setiap permintaan polling dengan salah satu respons berikut:
Akses diberikan
Jika pengguna memberikan akses ke perangkat (dengan mengklik Allow di layar izin),
respons akan berisi token akses dan token refresh. Token tersebut memungkinkan perangkat Anda mengakses Google API atas nama pengguna. (Properti scope
dalam respons menentukan API mana yang dapat diakses oleh
perangkat.)
Dalam hal ini, respons API berisi kolom berikut:
| Kolom | |
|---|---|
access_token |
Token yang dikirim aplikasi Anda untuk mengizinkan permintaan Google API. |
expires_in |
Masa berlaku token akses yang tersisa dalam hitungan detik. |
refresh_token |
Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token refresh valid hingga pengguna mencabut akses. Perhatikan bahwa token refresh selalu ditampilkan untuk perangkat. |
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. Pada saat ini, nilai kolom ini selalu ditetapkan ke Bearer. |
Cuplikan berikut menunjukkan contoh respons:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
"token_type": "Bearer",
"refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
Token akses memiliki masa berlaku terbatas. Jika aplikasi Anda memerlukan akses ke API dalam waktu yang lama, aplikasi dapat menggunakan token refresh untuk mendapatkan token akses yang baru. Jika aplikasi Anda memerlukan jenis akses ini, aplikasi harus menyimpan token refresh untuk digunakan nanti.
Akses ditolak
Jika pengguna menolak untuk memberikan akses ke perangkat, respons server akan memiliki
kode status respons HTTP 403 (Forbidden). Respons berisi
error berikut:
{
"error": "access_denied",
"error_description": "Forbidden"
}
Otorisasi tertunda
Jika pengguna belum menyelesaikan alur otorisasi, server akan menampilkan
kode status respons HTTP 428 (Precondition Required). Respons
berisi error berikut:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
Polling terlalu sering
Jika perangkat terlalu sering mengirim permintaan polling, server akan menampilkan kode status respons HTTP 403 (Forbidden). Respons berisi error berikut:
{
"error": "slow_down",
"error_description": "Forbidden"
}
Error lainnya
Server otorisasi juga akan menampilkan error jika permintaan polling tidak memiliki parameter yang diperlukan atau memiliki parameter value yang salah. Permintaan ini biasanya memiliki kode status respons HTTP 400 (Bad Request) atau 401 (Unauthorized). Error tersebut mencakup:
| Error | Kode Status HTTP | Deskripsi |
|---|---|---|
admin_policy_enforced |
400 |
Akun Google tidak dapat mengizinkan satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace miliknya. Lihat artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga dan internal yang mengakses data Google Workspace untuk mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke cakupan hingga akses diberikan secara eksplisit ke client ID OAuth Anda. |
invalid_client |
401 |
Klien OAuth tidak ditemukan. Misalnya, error ini terjadi jika
parameter value Jenis klien OAuth salah. Pastikan jenis aplikasi untuk client ID ditetapkan ke TV dan perangkat Input Terbatas. |
invalid_grant |
400 |
Parameter value code tidak valid, telah diklaim, atau tidak dapat diuraikan. |
unsupported_grant_type |
400 |
Nilai parameter grant_type tidak valid. |
org_internal |
403 |
Client ID OAuth dalam permintaan adalah bagian dari project yang membatasi akses ke Akun Google di Organisasi Google Cloud tertentu. Konfirmasi konfigurasi jenis pengguna untuk aplikasi OAuth Anda. |
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 lebih direkomendasikan, karena string kueri cenderung terlihat di log server. Dalam sebagian besar kasus, 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 HTTP GET
Panggilan ke endpoint
drive.files (Drive Files API) yang menggunakan header HTTP
Authorization: Bearer mungkin 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 parameter string kueri access_token:
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 ini
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 berakhir secara berkala dan menjadi tidak valid untuk permintaan API terkait. Anda dapat memperbarui token akses tanpa meminta izin pengguna (termasuk ketika pengguna tidak ada) jika meminta akses offline ke cakupan yang terkait dengan token.
Untuk memperbarui 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. |
grant_type |
Seperti
yang ditentukan dalam
spesifikasi OAuth 2.0,
nilai kolom ini harus ditetapkan ke refresh_token. |
refresh_token |
Token refresh ditampilkan dari pertukaran kode otorisasi. |
Cuplikan berikut menunjukkan permintaan contoh:
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 tidak 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 batas jumlah token refresh yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna di seluruh klien. Anda harus menyimpan token refresh dalam penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika meminta terlalu banyak token refresh, aplikasi Anda mungkin akan mencapai batas tersebut, 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 membuka Setelan Akun. Lihat bagian Menghapus situs atau aplikasi dari situs & aplikasi pihak ketiga yang memiliki akses ke akun Anda untuk mengetahui informasi selengkapnya.
Aplikasi juga dapat mencabut akses yang diberikan secara terprogram. Pencabutan terprogram diperlukan jika pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan ini dapat mencakup permintaan API untuk memastikan izin yang sebelumnya diberikan untuk 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 adalah
200. Untuk kondisi error, kode status HTTP 400 ditampilkan bersama dengan kode error.
Cakupan yang diizinkan
Alur OAuth 2.0 untuk perangkat hanya didukung untuk cakupan berikut:
OpenID Connect, Login dengan Google
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly