OAuth 2.0 untuk TV dan Aplikasi Perangkat Input Terbatas

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
175

Dokumen ini menjelaskan cara mengimplementasikan otorisasi OAuth 2.0 untuk mengakses Google API melalui aplikasi yang berjalan di 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 bersifat 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 masing-masing 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 dan menggunakan token ID JWT untuk memperoleh 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:

  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 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 produk asalnya.
  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 Buat kredensial > client ID OAuth.
  3. Pilih jenis aplikasi TV dan Perangkat Input Terbatas.
  4. Beri nama klien OAuth 2.0 Anda, lalu klik Buat.

Identifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda untuk hanya meminta akses ke resource yang dibutuhkan, sekaligus memungkinkan pengguna untuk 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 untuk diakses oleh aplikasi Anda.

Lihat daftar Cakupan yang diizinkan untuk aplikasi atau perangkat yang diinstal.

Memperoleh token akses OAuth 2.0

Meskipun aplikasi Anda berjalan di perangkat dengan kemampuan input terbatas, pengguna harus memiliki akses terpisah ke perangkat dengan kemampuan input yang lebih kaya untuk menyelesaikan alur otorisasi ini. Alur ini memiliki langkah-langkah berikut:

  1. Aplikasi Anda mengirim permintaan ke server otorisasi Google yang mengidentifikasi cakupan yang akan diminta oleh aplikasi Anda untuk diakses.
  2. Server merespons dengan beberapa informasi yang digunakan pada langkah berikutnya, seperti kode perangkat dan kode pengguna.
  3. Anda menampilkan informasi yang dapat dimasukkan pengguna di perangkat terpisah untuk mengotorisasi aplikasi Anda.
  4. Aplikasi Anda memulai polling server otorisasi Google untuk menentukan apakah pengguna telah mengotorisasi aplikasi Anda.
  5. Pengguna beralih ke perangkat dengan kemampuan input yang lebih kaya, 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.
  6. Respons berikutnya terhadap permintaan polling berisi token yang diperlukan aplikasi Anda untuk mengizinkan permintaan atas nama pengguna. (Jika pengguna menolak akses ke aplikasi Anda, respons tidak berisi token.)

Gambar di bawah menggambarkan proses ini:

Pengguna login di perangkat terpisah yang memiliki browser

Bagian berikut menjelaskan langkah-langkah ini secara detail. Mengingat rentang kemampuan dan lingkungan runtime yang mungkin dimiliki perangkat, contoh yang ditampilkan 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 POST HTTP 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 API Console Credentials page.

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.

Dengan cakupan, aplikasi Anda hanya dapat 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 contoh permintaan:

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 sukses

Jika permintaan tersebut 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, yang menyatakan bahwa 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, yang dibutuhkan perangkat Anda untuk menunggu di antara permintaan polling. Misalnya, jika nilainya 5, perangkat Anda harus mengirimkan permintaan polling ke server otorisasi Google setiap lima detik. Lihat langkah 3 untuk detail selengkapnya.
user_code Nilai peka huruf besar/kecil yang mengidentifikasi kepada Google cakupan yang diminta oleh aplikasi. Antarmuka pengguna akan memerintahkan pengguna untuk memasukkan nilai ini pada perangkat terpisah dengan kemampuan input yang lebih kaya. Kemudian, Google menggunakan nilai untuk menampilkan kumpulan cakupan yang benar saat meminta pengguna untuk memberikan akses ke aplikasi Anda.
verification_url URL yang harus dibuka pengguna, pada perangkat terpisah, untuk memasukkan user_code dan memberikan atau menolak akses ke aplikasi Anda. Antarmuka pengguna juga akan menampilkan nilai ini.

Cuplikan berikut menunjukkan respons contoh:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Respons kuota terlampaui

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

Jika demikian, 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 dapat berisi setiap karakter yang dapat dicetak dari himpunan karakter US-ASCII. Konten yang Anda tampilkan kepada pengguna harus menginstruksikan pengguna untuk membuka verification_url pada perangkat terpisah dan memasukkan user_code.

Desain antarmuka pengguna (UI) Anda dengan memperhatikan aturan berikut:

  • user_code
    • user_code harus ditampilkan di kolom yang dapat menangani karakter berukuran 15 'W' Dengan kata lain, jika Anda dapat menampilkan kode WWWWWWWWWWWWWWW dengan benar, UI Anda akan valid, dan sebaiknya gunakan nilai string tersebut saat menguji cara tampilan user_code di UI Anda.
    • user_code peka huruf besar/kecil dan tidak boleh diubah dengan cara apa pun, seperti mengubah huruf besar/kecil atau memasukkan karakter pemformatan lainnya.
  • verification_url
    • Ruang tempat Anda menampilkan verification_url harus cukup lebar untuk menangani string URL yang terdiri dari 40 karakter.
    • Anda tidak boleh memodifikasi verification_url dengan cara apa pun, kecuali jika Anda ingin menghapus skema tampilan. Jika Anda berencana menghapus skema (misalnya https://) dari URL karena alasan tampilan, pastikan aplikasi Anda dapat menangani varian http dan https.

Langkah 4: Polling server otorisasi Google

Karena pengguna akan menggunakan perangkat terpisah untuk bernavigasi ke verification_url dan memberikan (atau menolak) akses, perangkat yang meminta tidak akan otomatis diberi tahu saat pengguna merespons permintaan akses. Karena alasan tersebut, perangkat yang meminta harus melakukan polling pada server otorisasi Google untuk menentukan kapan pengguna telah merespons permintaan tersebut.

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 pada langkah 2 telah berakhir. 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 API Console Credentials page.
client_secret Rahasia klien untuk client_id yang diberikan. Anda dapat menemukan nilai ini di API Console Credentials page.
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 contoh permintaan:

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:

Hubungkan perangkat dengan memasukkan kode

Setelah memasukkan user_code dan, jika belum login, login ke Google, pengguna akan melihat layar izin seperti yang ditunjukkan di bawah:

Contoh layar izin untuk klien perangkat

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 ini 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 dikirimkan aplikasi Anda untuk mengotorisasi permintaan Google API.
expires_in Sisa masa pakai token akses 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. Saat ini, nilai kolom ini selalu ditetapkan ke Bearer.

Cuplikan berikut menunjukkan respons contoh:

{
  "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 yang terbatas. Jika memerlukan akses ke API dalam jangka waktu yang lama, aplikasi dapat menggunakan token refresh untuk mendapatkan token akses yang baru. Jika aplikasi Anda membutuhkan jenis akses ini, aplikasi harus menyimpan token refresh untuk digunakan nanti.

Akses ditolak

Jika pengguna menolak 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 dalam proses

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 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
invalid_client 401 Klien OAuth tidak ditemukan. Misalnya, error ini terjadi jika nilai parameter client_id tidak valid.
invalid_grant 400 Nilai parameter code tidak valid.
unsupported_grant_type 400 Nilai parameter grant_type tidak valid.

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 disarankan, 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) 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 yang 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 adalah contoh yang menggunakan opsi header HTTP (lebih disukai):

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

Atau, opsi parameter string kueri:

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

Memperbarui token akses

Token akses berakhir masa berlakunya dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat memuat ulang token akses tanpa meminta izin pengguna (termasuk ketika pengguna tidak ada) jika Anda 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 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 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 batasan jumlah token refresh yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna untuk semua klien. Anda harus menyimpan token refresh dalam penyimpanan jangka panjang dan terus menggunakannya selama masih valid. Jika meminta terlalu banyak token refresh, aplikasi Anda mungkin akan mencapai batas tersebut. Jika tidak, 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 akses aplikasi dari Situs pihak ketiga & aplikasi yang memiliki akses ke akun Anda untuk informasi selengkapnya.

Aplikasi juga dapat mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram penting dilakukan 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 sebagai parameter:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Token tersebut dapat berupa token akses atau token refresh. Jika token tersebut 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

  • email
  • openid
  • profile

API Drive

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly