OAuth 2.0 untuk TV dan Aplikasi Perangkat Input Terbatas

Dokumen ini menjelaskan cara menerapkan otorisasi OAuth 2.0 untuk mengakses Google API melalui aplikasi yang berjalan di perangkat seperti TV, konsol game, dan printer. Lebih khusus lagi, aliran ini dirancang untuk perangkat yang tidak memiliki akses ke browser atau memiliki kemampuan masukan yang terbatas.

OAuth 2.0 memungkinkan pengguna untuk berbagi data tertentu dengan aplikasi sambil tetap menjaga kerahasiaan nama pengguna, sandi, dan informasi lainnya. Misalnya, aplikasi TV dapat menggunakan OAuth 2.0 untuk mendapatkan izin memilih file yang disimpan di Google Drive.

Karena aplikasi yang menggunakan aliran ini didistribusikan ke perangkat individu, diasumsikan bahwa aplikasi tidak dapat menyimpan rahasia. Mereka 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 Platform Windows Universal), yang memiliki akses ke browser dan kemampuan input penuh, gunakan aliran OAuth 2.0 untuk aplikasi seluler dan desktop . (Anda harus menggunakan alur tersebut meskipun aplikasi Anda adalah alat baris perintah tanpa antarmuka grafis.)

Prasyarat

Aktifkan API untuk proyek Anda

Aplikasi apa pun yang memanggil Google API harus mengaktifkan API tersebut di API Console.

Untuk mengaktifkan API untuk proyek 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, dikelompokkan menurut kelompok produk dan popularitas. Jika API yang ingin Anda aktifkan tidak terlihat dalam daftar, gunakan penelusuran untuk menemukannya, atau klik Lihat Semua di keluarga 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.

Buat kredensial otorisasi

Aplikasi apa pun yang menggunakan OAuth 2.0 untuk mengakses Google API harus memiliki kredensial otorisasi yang mengidentifikasi aplikasi tersebut ke server OAuth 2.0 Google. Langkah-langkah berikut menjelaskan cara membuat kredensial untuk proyek Anda. Aplikasi Anda kemudian dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk proyek itu.

  1. Go to the Credentials page.
  2. Klik Buat kredensial> ID klien OAuth .
  3. Pilih jenis aplikasi TV dan perangkat Input Terbatas .
  4. Beri nama klien OAuth 2.0 Anda dan klik Buat .

Identifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

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

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

Mendapatkan token akses OAuth 2.0

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

  1. Aplikasi Anda mengirimkan permintaan ke server otorisasi Google yang mengidentifikasi cakupan yang akan diminta izin aksesnya oleh aplikasi Anda.
  2. Server merespons dengan beberapa bagian 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 mengotorisasi aplikasi Anda.
  4. Aplikasi Anda mulai memeriksa server otorisasi Google untuk menentukan apakah pengguna telah memberi otorisasi pada aplikasi Anda.
  5. Pengguna beralih ke perangkat dengan kemampuan masukan yang lebih kaya, meluncurkan browser web, menavigasi ke 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 untuk permintaan polling Anda berisi token yang diperlukan aplikasi Anda untuk mengotorisasi permintaan atas nama pengguna. (Jika pengguna menolak akses ke aplikasi Anda, responsnya tidak berisi token.)

Gambar di bawah mengilustrasikan proses ini:

Pengguna login di perangkat terpisah yang memiliki browser

Bagian berikut menjelaskan langkah-langkah ini secara mendetail. Mengingat berbagai kemampuan dan lingkungan waktu proses yang mungkin dimiliki perangkat, contoh yang ditampilkan dalam dokumen ini menggunakan utilitas baris perintah curl . Contoh-contoh ini harus mudah dikirim ke berbagai bahasa dan waktu proses.

Langkah 1: Minta kode perangkat dan pengguna

Pada langkah ini, perangkat Anda mengirim 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 pada pengguna kepentingan. Anda harus mengambil URL ini dari dokumen Discovery menggunakan nilai metadata device_authorization_endpoint . Sertakan parameter permintaan HTTP berikut:

Parameter
client_id Yg dibutuhkan

ID klien untuk aplikasi Anda. Anda dapat menemukan nilai ini di API Console Credentials page.

scope Yg dibutuhkan

Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai-nilai ini menginformasikan layar persetujuan yang ditampilkan Google kepada pengguna. Lihat daftar Cakupan yang diizinkan untuk aplikasi atau perangkat yang diinstal.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Jadi, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

Contoh

Cuplikan berikut menunjukkan permintaan sampel:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

Contoh ini menunjukkan perintah curl untuk mengirim permintaan yang sama:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

Langkah 2: Tangani respons server otorisasi

Server otorisasi akan mengembalikan salah satu tanggapan berikut:

Respon sukses

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

Properti
device_code Nilai yang ditetapkan Google secara unik untuk mengidentifikasi perangkat yang menjalankan aplikasi yang meminta otorisasi. Pengguna akan mengotorisasi perangkat tersebut dari perangkat lain dengan kemampuan masukan yang lebih kaya. Misalnya, pengguna mungkin menggunakan laptop atau ponsel untuk mengotorisasi aplikasi yang berjalan di TV. Dalam hal ini, device_code mengidentifikasi TV.

Kode ini memungkinkan perangkat yang menjalankan aplikasi dengan aman menentukan apakah pengguna telah memberikan atau menolak akses.

expires_in Lamanya waktu, dalam detik, device_code dan user_code valid. Jika, pada saat itu, pengguna tidak menyelesaikan aliran 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 Lamanya waktu, dalam detik, perangkat Anda harus 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 lebih jelasnya.
user_code Nilai peka huruf besar / kecil yang mengidentifikasi ke Google cakupan yang diminta aksesnya oleh aplikasi. Antarmuka pengguna Anda akan menginstruksikan pengguna untuk memasukkan nilai ini pada perangkat terpisah dengan kemampuan masukan yang lebih kaya. Google kemudian menggunakan nilai tersebut untuk menampilkan kumpulan cakupan yang benar saat meminta pengguna untuk memberikan akses ke aplikasi Anda.
verification_url URL yang harus dinavigasi oleh pengguna, pada 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 tanggapan:

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

Kuota melebihi respons

Jika permintaan kode perangkat Anda telah melebihi kuota yang terkait dengan ID klien Anda, Anda akan menerima tanggapan 403, yang berisi kesalahan berikut:

{
  "error_code": "rate_limit_exceeded"
}
.dll

Dalam kasus tersebut, gunakan strategi backoff untuk mengurangi tingkat permintaan.

Langkah 3: Tampilkan kode pengguna

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

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

  • user_code
    • user_code harus ditampilkan di bidang yang dapat menangani karakter berukuran 15 'W.' Dengan kata lain, jika Anda dapat menampilkan kode WWWWWWWWWWWWWWW dengan benar, UI Anda valid, dan kami merekomendasikan penggunaan nilai string tersebut saat menguji cara tampilan user_code di UI Anda.
    • user_code peka huruf besar kecil dan tidak boleh dimodifikasi dengan cara apa pun, seperti mengubah huruf besar atau kecil atau memasukkan 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 tampilan secara opsional. Jika Anda berencana untuk menghapus skema (misalnya https:// ) dari URL karena alasan tampilan, pastikan aplikasi Anda dapat menangani varian http dan https .

Langkah 4: Lakukan polling pada server otorisasi Google

Karena pengguna akan menggunakan perangkat terpisah untuk menavigasi ke verification_url dan memberikan (atau menolak) akses, perangkat yang meminta tidak diberi tahu secara otomatis saat pengguna menanggapi permintaan akses. Oleh karena itu, perangkat yang meminta perlu memeriksa server otorisasi Google untuk menentukan kapan pengguna menanggapi permintaan tersebut.

Perangkat yang meminta harus terus mengirimkan permintaan polling hingga menerima respons yang menunjukkan bahwa pengguna telah menanggapi permintaan akses atau hingga device_code dan user_code diperoleh di langkah 2 telah kedaluwarsa. interval dikembalikan di langkah 2 menentukan jumlah waktu, dalam detik, untuk menunggu di antara permintaan.

URL titik akhir untuk polling adalah https://oauth2.googleapis.com/token . Permintaan polling berisi parameter berikut:

Parameter
client_id ID klien untuk aplikasi Anda. Anda dapat menemukan nilai ini di API Console Credentials page.
client_secret Rahasia klien untuk client_id disediakan. Anda dapat menemukan nilai ini di API Console Credentials page.
device_code device_code dikembalikan oleh server otorisasi pada langkah 2 .
grant_type Setel nilai ini ke urn:ietf:params:oauth:grant-type:device_code .

Contoh

Cuplikan berikut menunjukkan permintaan sampel:

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 menanggapi permintaan akses

Gambar berikut menunjukkan halaman yang mirip dengan apa 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 masuk, masuk ke Google, pengguna melihat layar persetujuan seperti yang ditunjukkan di bawah ini:

Contoh layar persetujuan untuk klien perangkat

Langkah 6: Tangani respons untuk permintaan polling

Server otorisasi Google menanggapi setiap permintaan polling dengan salah satu tanggapan berikut:

Akses diberikan

Jika pengguna diberikan akses ke perangkat (dengan mengklik Allow di layar persetujuan), maka responsnya berisi token akses dan token penyegaran. Token memungkinkan perangkat Anda mengakses Google API atas nama pengguna. (Properti scope dalam respons menentukan API mana yang dapat diakses perangkat.)

Dalam kasus ini, respons API berisi bidang-bidang berikut:

Fields
access_token Token yang dikirim aplikasi Anda untuk mengotorisasi permintaan Google API.
expires_in Masa pakai token akses yang tersisa dalam hitungan detik.
refresh_token Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Segarkan token valid hingga pengguna mencabut akses. Perhatikan bahwa token penyegaran selalu dikembalikan untuk perangkat.
scope Cakupan akses yang diberikan oleh access_token dinyatakan sebagai daftar string peka huruf besar / kecil yang dipisahkan spasi.
token_type Jenis token yang dikembalikan. Saat ini, nilai bidang ini selalu disetel ke Bearer .

Cuplikan berikut menunjukkan contoh tanggapan:

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

Akses ditolak

Jika pengguna menolak memberikan akses ke perangkat, respons server memiliki kode status respons HTTP 403 ( Forbidden ). Tanggapan tersebut berisi kesalahan berikut:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Otorisasi menunggu keputusan

Jika pengguna belum menyelesaikan aliran otorisasi, server mengembalikan kode status tanggapan HTTP 428 ( Precondition Required ). Tanggapan tersebut berisi kesalahan berikut:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Polling terlalu sering

Jika perangkat mengirim permintaan polling terlalu sering, server mengembalikan kode status respons HTTP 403 ( Forbidden ). Tanggapan tersebut berisi kesalahan berikut:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Kesalahan lainnya

Server otorisasi juga mengembalikan kesalahan jika permintaan polling kehilangan parameter yang diperlukan atau memiliki nilai parameter yang salah. Permintaan ini biasanya memiliki kode status respons HTTP 400 ( Bad Request ) atau 401 ( Unauthorized ). Kesalahan tersebut meliputi:

Kesalahan Kode Status HTTP Deskripsi
invalid_client 401 Klien OAuth tidak ditemukan. Misalnya, kesalahan 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 memasukkan parameter kueri access_token atau nilai Bearer header HTTP Authorization . Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam kebanyakan kasus, Anda dapat menggunakan pustaka klien untuk menyiapkan panggilan Anda 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 yang diautentikasi 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 baris perintah 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

Token akses kedaluwarsa secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat menyegarkan token akses tanpa meminta izin dari pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token tersebut.

Untuk menyegarkan token akses, aplikasi Anda mengirimkan permintaan HTTPS POST ke server otorisasi Google ( https://oauth2.googleapis.com/token ) yang menyertakan parameter berikut:

Fields
client_id ID klien diperoleh dari API Console.
client_secret Rahasia klien diperoleh dari API Console.
grant_type Seperti yang ditentukan dalam spesifikasi OAuth 2.0 , nilai bidang ini harus disetel ke refresh_token .
refresh_token Token penyegaran dikembalikan dari pertukaran kode otorisasi.

Cuplikan berikut menunjukkan permintaan sampel:

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 mengembalikan objek JSON yang berisi token akses baru. Cuplikan berikut menunjukkan contoh tanggapan:

{
  "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 penyegaran yang akan dikeluarkan; satu batas per kombinasi klien / pengguna, dan satu lagi per pengguna di semua klien. Anda harus menyimpan token penyegaran dalam penyimpanan jangka panjang dan terus menggunakannya selama masih valid. Jika aplikasi Anda meminta terlalu banyak token penyegaran, itu mungkin mengalami batasan ini, dalam hal ini token penyegaran yang lebih lama akan berhenti berfungsi.

Mencabut token

Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Seorang pengguna dapat mencabut akses dengan mengunjungi Pengaturan Akun . Lihat bagian Menghapus situs atau akses aplikasi di Situs & aplikasi pihak ketiga dengan akses ke dokumen dukungan akun Anda untuk informasi selengkapnya.

Mungkin juga aplikasi mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan terprogram penting jika pengguna berhenti berlangganan, menghapus aplikasi, atau sumber daya API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan dapat menyertakan permintaan API untuk memastikan izin yang sebelumnya diberikan ke aplikasi tersebut 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 penyegaran. Jika token adalah token akses dan memiliki token penyegaran yang sesuai, token penyegaran juga akan dicabut.

Jika pembatalan berhasil diproses, maka kode status HTTP dari responsnya adalah 200 . Untuk kondisi kesalahan, kode status HTTP 400 dikembalikan bersama dengan kode kesalahan.

Cakupan yang diizinkan

Alur OAuth 2.0 untuk perangkat hanya didukung untuk cakupan berikut:

OpenID Connect , Masuk dengan Google

  • email
  • openid
  • profile

Drive API

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

API YouTube

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