OAuth 2.0 untuk TV dan aplikasi perangkat input terbatas

Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses YouTube Data 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, sekaligus menjaga kerahasiaan nama pengguna, sandi, dan informasi mereka lainnya. Misalnya, aplikasi TV dapat menggunakan OAuth 2.0 untuk mendapatkan izin guna memilih file yang disimpan di Google Drive.

Karena aplikasi yang menggunakan alur ini didistribusikan ke perangkat individual, diasumsikan bahwa aplikasi tidak dapat menyimpan rahasia. Aplikasi tersebut dapat mengakses Google API saat pengguna berada 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 membuat pengguna login dengan Akun Google mereka dan menggunakan token ID JWT untuk mendapatkan informasi profil pengguna dasar, lihat Login di TV dan Perangkat dengan Input Terbatas.

Prasyarat

Aktifkan API untuk project Anda

Setiap aplikasi 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. Gunakan halaman Library untuk menemukan dan mengaktifkan YouTube Data API. Temukan API lain yang akan digunakan aplikasi Anda dan aktifkan juga API tersebut.

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. Aplikasi Anda kemudian dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk project tersebut.

1. Go to the Credentials page.
2. Klik Buat Klien.
3. Pilih jenis aplikasi TV dan Perangkat Input Terbatas.
4. Beri nama klien OAuth 2.0 Anda, lalu klik Buat.

Mengidentifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan sekaligus memungkinkan pengguna mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Oleh karena itu, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan yang izin aksesnya akan diperlukan oleh aplikasi Anda.

YouTube Data API v3 menggunakan cakupan berikut:

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

Mendapatkan 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 izin aksesnya oleh aplikasi Anda.
2. Server merespons dengan beberapa informasi yang digunakan dalam langkah-langkah berikutnya, seperti kode perangkat dan kode pengguna.
3. Anda menampilkan informasi yang dapat dimasukkan pengguna di perangkat terpisah untuk mengizinkan aplikasi Anda.
4. Aplikasi Anda mulai melakukan polling server otorisasi Google untuk menentukan apakah pengguna telah mengizinkan aplikasi Anda.
5. Pengguna beralih ke perangkat dengan kemampuan input yang lebih kaya, meluncurkan browser web, membuka URL yang ditampilkan di langkah 3 dan memasukkan kode yang juga ditampilkan di langkah 3. Pengguna kemudian dapat memberikan (atau menolak) akses ke aplikasi Anda.
6. Respons berikutnya terhadap permintaan polling Anda berisi token yang dibutuhkan 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:

Bagian berikut menjelaskan langkah-langkah ini secara detail. Mengingat berbagai kemampuan dan lingkungan runtime yang mungkin dimiliki perangkat, contoh yang ditampilkan dalam dokumen ini menggunakan utilitas command line curl. Contoh ini harus mudah di-porting 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 aplikasi Anda atas nama pengguna. Anda harus mengambil URL ini dari Dokumen penemuan menggunakan nilai metadata device_authorization_endpoint. Sertakan parameter permintaan HTTP berikut:

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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

Contoh ini menunjukkan perintah curl untuk mengirim permintaan yang sama:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Langkah 2: Tangani respons server otorisasi

Server otorisasi akan menampilkan salah satu respons berikut:

Respons keberhasilan

Jika permintaan valid, respons Anda akan berupa objek JSON yang berisi properti berikut:

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 kuota terlampaui

Jika permintaan kode perangkat Anda telah melampaui kuota yang terkait dengan ID klien Anda, Anda akan menerima respons 403, yang berisi error berikut:

{
  "error_code": "rate_limit_exceeded"
}

Dalam hal ini, gunakan strategi backoff untuk mengurangi frekuensi permintaan.

Langkah 3: Tampilkan kode pengguna

Tampilkan verification_url dan user_code yang diperoleh pada langkah 2 kepada pengguna. Kedua nilai dapat berisi karakter yang dapat dicetak dari set karakter US-ASCII. Konten yang Anda tampilkan kepada pengguna harus menginstruksikan pengguna untuk membuka verification_url di perangkat terpisah dan memasukkan user_code.

Rancang antarmuka pengguna (UI) Anda dengan mempertimbangkan aturan berikut:

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

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 menanggapi permintaan akses. Oleh karena itu, perangkat yang meminta perlu melakukan polling server otorisasi Google untuk menentukan kapan pengguna telah merespons permintaan.

Perangkat yang meminta harus terus mengirim permintaan polling hingga menerima respons yang menunjukkan bahwa pengguna telah merespons permintaan akses atau hingga device_code dan user_code yang diperoleh pada langkah 2 berakhir. interval yang ditampilkan pada langkah 2 menentukan jumlah waktu, dalam detik, untuk menunggu di antara permintaan.

URL endpoint yang akan di-polling adalah https://oauth2.googleapis.com/token. Permintaan polling berisi parameter berikut:

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" \
         https://oauth2.googleapis.com/token

Langkah 5: Pengguna merespons permintaan akses

Gambar berikut menampilkan halaman yang serupa dengan yang dilihat pengguna saat mereka membuka verification_url yang Anda tampilkan di langkah 3:

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

Langkah 6: Menangani 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 perangkat.)

Dalam hal ini, respons API berisi kolom berikut:

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 jangka waktu yang lama, aplikasi tersebut dapat menggunakan token refresh untuk mendapatkan token akses baru. Jika aplikasi Anda memerlukan 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 menunggu keputusan

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 mengirim permintaan polling terlalu sering, 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 nilai parameter yang salah. Permintaan ini biasanya memiliki kode status respons HTTP 400 (Bad Request) atau 401 (Unauthorized). Error tersebut mencakup:

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 header HTTP Authorization Bearer. Jika memungkinkan, header HTTP lebih disarankan, karena string kueri cenderung terlihat dalam log server. Dalam sebagian besar kasus, Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil YouTube Live Streaming API).

Perhatikan bahwa YouTube Live Streaming API tidak mendukung alur akun layanan. Karena tidak ada cara untuk menautkan Akun Layanan ke akun YouTube, upaya untuk mengizinkan permintaan dengan alur ini akan menghasilkan error NoLinkedYouTubeAccount.

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

Contoh HTTP GET

Panggilan ke liveBroadcasts.list endpoint (YouTube Live Streaming API) menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda harus menentukan token akses Anda sendiri:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Contoh curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Atau, opsi parameter string kueri:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Memperbarui token akses

Token akses akan habis masa berlakunya secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat memperbarui token akses tanpa meminta izin pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token.

Untuk memperbarui token akses, aplikasi Anda mengirim permintaan HTTPS POST 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 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 https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Perhatikan bahwa ada batasan jumlah token refresh yang akan dikeluarkan; satu batasan per kombinasi klien/pengguna, dan batasan lainnya per pengguna di semua klien. Anda harus menyimpan token refresh di penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika aplikasi Anda meminta terlalu banyak token refresh, aplikasi tersebut mungkin 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 membuka Setelan Akun. Lihat bagian Hapus akses situs atau aplikasi di dokumen dukungan 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 akses secara terprogram penting dalam kasus saat 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 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 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:

Akses berbasis waktu

Akses berbasis waktu memungkinkan pengguna memberikan akses aplikasi Anda ke datanya selama durasi terbatas untuk menyelesaikan tindakan. Akses berbasis waktu tersedia di produk Google tertentu selama alur izin, sehingga pengguna dapat memberikan akses untuk jangka waktu terbatas. Contohnya adalah Data Portability API yang memungkinkan transfer data satu kali.

Saat pengguna memberikan akses berbasis waktu ke aplikasi Anda, masa berlaku token refresh akan berakhir setelah durasi yang ditentukan. Perhatikan bahwa token refresh dapat dibatalkan lebih awal dalam keadaan tertentu; lihat kasus ini untuk mengetahui detailnya. Kolom refresh_token_expires_in yang ditampilkan dalam respons penukaran kode otorisasi menunjukkan waktu yang tersisa hingga token refresh habis masa berlakunya dalam kasus tersebut.