Login di TV dan Perangkat Input Terbatas

Anda dapat mengizinkan pengguna login ke aplikasi Anda dengan Akun Google mereka di perangkat dengan kemampuan input terbatas, seperti TV yang terhubung ke internet.

Aplikasi menampilkan kode singkat dan URL login kepada pengguna. Kemudian, pengguna membuka URL login di browser web, memasukkan kode, dan memberikan izin aplikasi untuk mengakses informasi login pengguna. Terakhir, aplikasi menerima konfirmasi dan pengguna login.

Untuk menggunakan alur login ini, aplikasi harus berjalan di perangkat yang memenuhi kriteria berikut:

  • Perangkat harus dapat menampilkan URL 40 karakter dan kode pengguna 15 karakter, beserta petunjuk kepada pengguna.
  • Perangkat harus terhubung ke Internet.

Mendapatkan client ID dan rahasia klien

Aplikasi Anda memerlukan client ID dan rahasia klien OAuth 2.0 untuk membuat permintaan ke endpoint login Google.

Untuk menemukan client ID dan rahasia klien project Anda, lakukan hal berikut:

  1. Pilih kredensial OAuth 2.0 yang sudah ada atau buka halaman Credentials.
  2. Jika Anda belum melakukannya, buat kredensial OAuth 2.0 project Anda dengan mengklik Create credentials > OAuth client ID, dan memberikan informasi yang diperlukan untuk membuat kredensial.
  3. Cari Client ID di bagian OAuth 2.0 client IDs. Untuk mengetahui detailnya, klik client ID.

Jika Anda membuat client ID baru, pilih jenis aplikasi TV dan Perangkat Input Terbatas.

Mendapatkan kode pengguna dan URL verifikasi

Setelah pengguna meminta untuk login menggunakan Akun Google, Anda akan mendapatkan kode pengguna dan URL verifikasi dengan mengirimkan permintaan POST HTTP ke endpoint perangkat OAuth 2.0, https://oauth2.googleapis.com/device/code. Sertakan client ID dan daftar cakupan yang diperlukan bersama permintaan. Jika Anda hanya ingin memproses login pengguna dengan Akun Google mereka, minta hanya cakupan profile dan email; atau, jika Anda ingin meminta izin untuk memanggil API yang didukung atas nama pengguna, minta cakupan yang diperlukan selain cakupan profile dan email.

Berikut adalah contoh permintaan untuk kode pengguna:

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

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

Menggunakan curl:

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

Respons ditampilkan sebagai objek JSON:

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

Aplikasi Anda menampilkan nilai user_code dan verification_url kepada pengguna, dan, pada saat yang sama, melakukan polling endpoint login pada interval yang ditentukan hingga pengguna login atau waktu yang ditentukan oleh expires_in telah berlalu.

Menampilkan kode pengguna dan URL verifikasi

Setelah Anda menerima kode pengguna dan URL verifikasi dari endpoint perangkat, tampilkan dan minta pengguna untuk membuka URL dan memasukkan kode pengguna.

Nilai verification_url dan user_code dapat berubah sewaktu-waktu. Desain UI Anda dengan cara yang dapat menangani batasan berikut:

  • user_code harus ditampilkan dalam kolom yang cukup lebar untuk menangani 15 karakter berukuran W.
  • verification_url harus ditampilkan di kolom yang cukup lebar untuk menangani string URL yang panjangnya 40 karakter.

Kedua string dapat berisi karakter apa pun yang bisa dicetak dari himpunan karakter US-ASCII.

Saat menampilkan string user_code, jangan ubah string dengan cara apa pun (seperti mengubah huruf besar/kecil atau menyisipkan karakter pemformatan lainnya), karena aplikasi Anda mungkin rusak jika format kode berubah di masa mendatang.

Anda dapat mengubah string verification_url dengan menghapus skema dari URL untuk tujuan tampilan jika Anda memilihnya. Jika ya, pastikan aplikasi Anda dapat menangani varian "http" dan "https". Jangan ubah string verification_url.

Saat membuka URL verifikasi, pengguna akan melihat halaman yang mirip dengan berikut:

Menghubungkan perangkat dengan memasukkan kode

Setelah pengguna memasukkan kode pengguna, situs login dengan Google akan menampilkan layar izin yang mirip dengan berikut ini:

Contoh layar izin untuk klien perangkat

Jika pengguna mengklik Izinkan, aplikasi Anda dapat memperoleh token ID untuk mengidentifikasi pengguna, token akses untuk memanggil Google API, dan token refresh untuk mendapatkan token baru.

Mendapatkan token ID dan token refresh

Setelah aplikasi menampilkan kode pengguna dan URL verifikasi, mulailah melakukan polling endpoint token (https://oauth2.googleapis.com/token) dengan kode perangkat yang Anda terima dari endpoint perangkat. Mengambil sampel endpoint token pada interval, dalam detik, yang ditentukan oleh nilai interval.

Berikut adalah contoh permintaan:

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

client_id=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

Menggunakan curl:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

Jika pengguna belum menyetujui permintaan, responsnya adalah sebagai berikut:

{
  "error" : "authorization_pending"
}

Aplikasi Anda harus mengulangi permintaan ini pada kecepatan yang tidak melebihi nilai interval. Jika aplikasi Anda melakukan polling terlalu cepat, responsnya adalah sebagai berikut:

{
  "error" : "slow_down"
}

Setelah pengguna login dan memberi aplikasi Anda akses ke cakupan yang Anda minta, respons terhadap permintaan berikutnya untuk aplikasi Anda akan mencakup token ID, token akses, dan token refresh:

{
  "access_token": "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

Setelah menerima respons ini, aplikasi Anda dapat mendekode token ID untuk mendapatkan informasi profil dasar tentang pengguna yang login, atau mengirim token ID ke server backend aplikasi Anda untuk mengautentikasi dengan server dengan aman. Selain itu, aplikasi Anda dapat menggunakan token akses untuk memanggil API Google yang telah diotorisasi pengguna.

Token ID dan akses memiliki masa berlaku terbatas. Agar pengguna tetap login setelah masa berlaku token berakhir, simpan token refresh dan gunakan untuk meminta token baru.

Mendapatkan informasi profil pengguna dari token ID

Anda bisa mendapatkan informasi profil tentang pengguna yang login dengan mendekode token ID menggunakan library dekode JWT. Misalnya, menggunakan library JavaScript Auth0 jwt-decode:

var user_profile = jwt_decode(<var>id_token</var>);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

Informasi selengkapnya