Autentikasi dan Otorisasi di Google Data Protocol

Peringatan: Halaman ini membahas API lama Google, yaitu Google Data API; halaman ini hanya relevan dengan API yang tercantum dalam direktori Google Data API, yang sebagian besar telah diganti dengan API yang lebih baru. Untuk mengetahui informasi tentang API baru tertentu, lihat dokumentasi API baru tersebut. Untuk mengetahui informasi tentang cara mengizinkan permintaan dengan API yang lebih baru, lihat Autentikasi dan Otorisasi Akun Google.

Aplikasi pihak ketiga sering kali memerlukan akses terbatas ke Akun Google pengguna untuk jenis aktivitas tertentu. Untuk memastikan bahwa data pengguna tidak disalahgunakan, semua permintaan akses harus disetujui oleh pemegang akun. Kontrol akses memiliki dua komponen, yaitu autentikasi dan otorisasi.

Layanan autentikasi memungkinkan pengguna login ke aplikasi Anda menggunakan Akun Google.

Layanan otorisasi memungkinkan pengguna memberi aplikasi Anda akses ke data yang telah mereka simpan di aplikasi Google. Google menganggap privasi secara serius, dan setiap aplikasi yang memerlukan akses ke data pengguna harus diberi otorisasi oleh pengguna.

Layanan autentikasi dan otorisasi sering disebut secara kolektif sebagai auth.

Autentikasi dan otorisasi untuk Google API memungkinkan aplikasi pihak ketiga mendapatkan akses terbatas ke Akun Google pengguna untuk jenis aktivitas tertentu. Dokumen ini memperkenalkan mekanisme autentikasi yang tersedia dan menjelaskan apa yang disediakan setiap mekanisme untuk aplikasi Anda.

  • Login dengan Google menyediakan cara mudah untuk mengizinkan pengguna menggunakan kredensial Google mereka untuk login ke situs Anda. API ini mencakup serangkaian alat yang mudah diintegrasikan di berbagai perangkat.
  • OAuth 2.0 adalah protokol otorisasi untuk semua Google API. OAuth 2.0 mengandalkan SSL untuk keamanan, bukan mengharuskan aplikasi Anda melakukan penandatanganan kriptografis secara langsung. Protokol ini memungkinkan aplikasi Anda meminta akses ke data yang terkait dengan Akun Google pengguna.
  • Login dengan OAuth 2.0 (OpenID Connect) mengautentikasi pengguna dengan meminta mereka login menggunakan akun Google mereka. Ini adalah pengganti OpenID, dan pengguna OpenID harus berencana untuk bermigrasi ke Login dengan OAuth 2.0.

Jika aplikasi Anda adalah gadget (untuk digunakan di iGoogle atau penampung OpenSocial lainnya), lihat bagian Autentikasi untuk Gadget.

Catatan: Dokumen ini dimaksudkan untuk memberikan ringkasan setiap metode autentikasi. Untuk mengetahui informasi mendetail tentang setiap metode, lihat dokumentasi lengkap Google Account Authentication API.

Lihat juga Grup API Akun Google untuk diskusi tentang penggunaan API Akun Google.

OAuth - otorisasi untuk aplikasi web dan aplikasi yang diinstal

Banyak layanan Google mengizinkan akses pihak ketiga ke data buatan pengguna, seperti data Kalender atau Dokumen, selama akses tersebut diizinkan oleh pengguna. Fitur ini memungkinkan pengguna membagikan dan menukar data antara aplikasi Google mereka dan aplikasi pihak ketiga untuk berbagai tujuan.

Google mendukung dua versi OAuth untuk mendapatkan akses yang sah ke data Google pengguna: OAuth 1.0 dan OAuth 2.0, yang keduanya menawarkan akses ke aplikasi web dan aplikasi yang terinstal.

OAuth 2.0 untuk aplikasi web dan aplikasi yang terinstal

Aplikasi web atau aplikasi yang diinstal dapat menggunakan protokol OAuth 2.0 baru yang disederhanakan untuk mengotorisasi akses ke data yang terkait dengan Akun Google. Untuk mengetahui detail dan contoh cara menerapkan OAuth 2.0 dengan Google, lihat dokumentasi kami tentang OAuth 2.0.

OAuth 1.0 untuk aplikasi web

Aplikasi web yang memerlukan akses resmi ke data yang terkait dengan Akun Google atau Akun Google Apps dapat menggunakan penerapan OAuth API Google. Untuk mengetahui informasi lengkap tentang penerapan OAuth untuk aplikasi berbasis web, termasuk contoh, lihat panduan OAuth untuk Aplikasi Web, atau lihat ringkasan dalam dokumen ini.

OAuth 1.0 untuk aplikasi terinstal

Aplikasi yang diinstal di komputer dan perangkat seluler pengguna dapat menggunakan OAuth untuk mengizinkan akses ke data yang terkait dengan Akun Google. Untuk mengetahui informasi lengkap tentang penerapan OAuth untuk aplikasi yang diinstal, lihat panduan OAuth untuk Aplikasi yang Diinstal, atau lihat ringkasan dalam dokumen ini.

Menggunakan OAuth dengan aplikasi web

Semua Google Data API mendukung OAuth, standar terbuka untuk memberikan otorisasi penggunaan data di aplikasi web. Semua aplikasi web yang membuat permintaan OAuth harus mengupload sertifikat keamanan dan mendaftar ke Google. Lihat Pendaftaran untuk Aplikasi Berbasis Web untuk mengetahui informasi selengkapnya.

Library Klien Google Data API menyediakan metode untuk membantu Anda menggunakan OAuth di aplikasi web. Secara khusus, ada metode untuk membuat token permintaan, mengizinkan token permintaan, dan menukar token permintaan yang diizinkan dengan token akses. Library ini juga menangani algoritma penandatanganan yang diperlukan saat membuat permintaan ke layanan Data Google. Untuk contoh ekstensif tentang cara menggunakan OAuth dengan Library Klien Google Data API,lihat Using OAuth with the Google Data APIs Client Libraries.

Proses otorisasi OAuth

Proses otorisasi OAuth melibatkan serangkaian interaksi antara aplikasi web Anda, server otorisasi Google, dan pengguna akhir.

Pada tingkat dasar, prosesnya adalah sebagai berikut:

  1. Aplikasi Anda meminta akses dan mendapatkan token permintaan tidak sah dari server otorisasi Google.
  2. Google meminta pengguna untuk memberi Anda akses ke data yang diperlukan.
  3. Aplikasi Anda mendapatkan token permintaan yang diberi otorisasi dari server otorisasi.
  4. Anda menukar token permintaan yang diizinkan dengan token akses.
  5. Anda menggunakan token akses untuk meminta data dari server akses layanan Google.

Saat aplikasi Anda pertama kali meminta akses ke data pengguna, Google akan menerbitkan token permintaan yang tidak sah ke aplikasi Anda.

Jika pengguna belum login, Google akan meminta pengguna untuk login. Kemudian, Google akan menampilkan halaman otorisasi yang memungkinkan pengguna melihat data layanan Google yang aksesnya diminta oleh aplikasi Anda.

Jika pengguna menyetujui permintaan akses aplikasi Anda, Google akan menerbitkan token permintaan yang sah. Setiap token permintaan hanya valid selama satu jam. Hanya token permintaan yang sah yang dapat ditukar dengan token akses, dan penukaran ini hanya dapat dilakukan satu kali per token permintaan yang sah.

Secara default, token akses memiliki masa berlaku yang lama. Setiap token akses khusus untuk akun pengguna yang ditentukan dalam permintaan otorisasi asli, dan memberikan akses hanya ke layanan yang ditentukan dalam permintaan tersebut. Aplikasi Anda harus menyimpan token akses dengan aman, karena token ini diperlukan untuk semua akses ke data pengguna.

Mempersiapkan OAuth

Sebelum dapat menyiapkan aplikasi untuk menggunakan layanan Otorisasi Google dengan OAuth, Anda harus menyelesaikan tugas berikut.

Menentukan apakah akan mendaftarkan aplikasi web Anda

Untuk memberikan jaminan tambahan kepada pengguna tentang keamanan data mereka, Anda dapat memilih untuk mendaftarkan aplikasi web Anda ke Google dan menandatangani permintaan Anda dengan sertifikat keamanan terdaftar. Beberapa feed Google Data API hanya tersedia untuk aplikasi terdaftar. Lihat dokumentasi untuk Google Data API yang Anda minati untuk menentukan apakah API tersebut hanya berfungsi dengan aplikasi terdaftar.

Aplikasi Anda harus menandatangani setiap permintaan OAuth yang dibuatnya. Jika Anda memilih untuk menggunakan tanda tangan RSA-SHA1 untuk menandatangani permintaan, Anda harus mengupload sertifikat keamanan sebagai bagian dari proses pendaftaran.

Atau, Anda dapat menggunakan tanda tangan HMAC-SHA1 untuk menandatangani permintaan Anda. Tidak ada sertifikat yang diperlukan untuk tanda tangan HMAC-SHA1. Sebagai gantinya, Google membuat nilai consumer secret OAuth, yang ditampilkan di halaman pendaftaran domain Anda setelah Anda mendaftar.

Untuk mengetahui informasi selengkapnya tentang proses pendaftaran, lihat Pendaftaran untuk Aplikasi Web.

Menentukan cakupan data yang akan diakses aplikasi Anda

Setiap layanan Google menetapkan batas pada akses yang diizinkannya melalui Google Data API. Akses ini dinyatakan sebagai nilai cakupan. Beberapa layanan menyediakan berbagai nilai cakupan, untuk memungkinkan pengguna memilih aplikasi mana yang harus memiliki akses ke data mana. Untuk mengetahui informasi tentang nilai cakupan yang tersedia untuk layanan Google yang ingin Anda akses, lihat dokumentasi untuk layanan tersebut.

Secara umum, Anda harus meminta token untuk cakupan tersempit yang mencakup data yang Anda butuhkan. Misalnya, jika aplikasi Anda memerlukan akses ke feed "Semua Kalender" pengguna, Anda harus meminta token untuk cakupan http://www.google.com/calendar/feeds/default/allcalendars/full.

Menyiapkan mekanisme untuk mengelola token OAuth

Saat Anda mendapatkan token akses OAuth untuk data pengguna, Anda harus menggunakan token akses tersebut untuk semua interaksi mendatang dengan layanan Google yang ditentukan atas nama pengguna.

Aplikasi Anda harus mengelola penyimpanan token dengan aman, termasuk melacak layanan Google yang valid untuk setiap token. Jika memerlukan akses ke lebih dari satu layanan Google, Anda dapat memperoleh beberapa token akses, tetapi tidak lebih dari sepuluh token akses per pengguna dan aplikasi yang dapat beredar kapan saja.

Jika aplikasi Anda mendukung beberapa akun pengguna, Anda harus melacak akun yang terkait dengan setiap token. Setiap token OAuth khusus untuk pengguna yang mengizinkan akses. Aplikasi Anda harus dapat mengaitkan token dengan pengguna yang benar. Salah satu cara untuk mengelola hal ini adalah dengan mengeluarkan cookie kepada pengguna sebelum membuat permintaan token. Setelah pengguna memberikan akses ke data yang diminta, Google akan mengirimkan token permintaan yang sah dan mengalihkan pengguna ke aplikasi Anda. Kemudian, Anda dapat menggunakan cookie aplikasi untuk mengaitkan token dengan pengguna yang benar.

Menyiapkan mekanisme untuk meminta akses ke layanan Google

Setiap permintaan ke layanan Google harus ditandatangani, dan harus menyertakan token akses OAuth yang valid. Secara umum, setiap permintaan dibuat dalam bentuk permintaan HTTP GET, dengan token akses dan tanda tangan disertakan dalam header. Permintaan yang menulis data baru harus menggunakan HTTP POST.

Untuk mengetahui informasi selengkapnya tentang format permintaan yang tepat untuk setiap Google Data API, lihat dokumentasi untuk API tersebut.

Menerapkan OpenID (opsional)

Jika Anda menerapkan OpenID untuk autentikasi pengguna, pertimbangkan untuk menggunakan protokol hybrid untuk menggabungkan kedua proses. Dengan OpenID+OAuth, tugas mendapatkan token permintaan dan mengizinkannya ditangani sebagai bagian dari permintaan OpenID dengan ekstensi OAuth. Seperti OAuthGetRequestToken, ekstensi ini digunakan untuk mengidentifikasi layanan Google yang akan diakses. Respons berhasil terhadap permintaan OpenID berisi token permintaan yang sah. Setelah token ini diterima, gunakan OAuthGetAccessToken untuk menukarkannya dengan token akses.

Menggunakan token OAuth

Untuk menggunakan OAuth, aplikasi Anda harus membuat panggilan permintaan token yang ditandatangani dan dibuat dengan baik, serta menangani respons, untuk urutan berikut:

  1. Mendapatkan token permintaan yang tidak sah (OAuthGetRequestToken)
  2. Mengizinkan token permintaan (OAuthAuthorizeToken)
  3. Menukarkan token permintaan yang diotorisasi dengan token akses (OAuthGetAccessToken)

Semua permintaan OAuth harus ditandatangani, terlepas dari apakah aplikasi Anda terdaftar atau tidak. Untuk mengetahui informasi lebih lanjut, lihat Menandatangani Permintaan OAuth.

Anda dapat bereksperimen dengan meminta dan menerima token otorisasi di OAuth Playground.

Untuk dokumentasi mendetail, lihat Referensi API OAuth.

Menetapkan URL callback

Anda dapat menentukan nilai untuk oauth_callback dalam permintaan OAuthGetRequestToken, untuk menentukan ke mana Google mengalihkan pengguna setelah mereka mengizinkan permintaan akses Anda. URL callback dapat mencakup parameter kueri. Pengalihan akan menyertakan parameter kueri yang sama, serta token permintaan yang sah, yang harus dapat diuraikan oleh aplikasi Anda.

Misalnya, saat mendukung beberapa bahasa, Anda dapat menyertakan parameter kueri yang mengidentifikasi versi aplikasi yang dilihat pengguna. Nilai oauth_callback "http://www.yoursite.com/Retrievetoken?Lang=de akan menghasilkan pengalihan "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Mengurai token dan parameter bahasa memastikan pengguna dialihkan kembali ke versi situs yang benar.

Jika parameter oauth_callback tidak disertakan, Google akan mengarahkan pengguna ke halaman web yang menampilkan nomor verifikasi (lihat contoh), setelah mengizinkan permintaan akses Anda. Pengguna harus kembali ke aplikasi Anda secara manual dan memasukkan nomor verifikasi sebelum Anda dapat memperoleh token permintaan yang sah.

Mengidentifikasi aplikasi Anda kepada pengguna

Google biasanya menampilkan nama aplikasi saat meminta izin akses dari pengguna (lihat contoh).

Jika aplikasi Anda tidak terdaftar, gunakan parameter xoauth_displayname dalam permintaan OAuthGetRequestToken untuk menentukan nama aplikasi Anda. Jika parameter tersebut tidak ditentukan, Google akan menampilkan nama domain URL yang diberikan oleh parameter oauth_callback. Jika tidak ada URL callback yang diberikan, Google akan menampilkan string "anonymous".

Jangan tetapkan parameter ini jika aplikasi Anda terdaftar. Secara default, Google menampilkan nama tampilan yang ditentukan selama pendaftaran. Jika Anda menetapkan nama tampilan dalam permintaan OAuthGetRequestToken, Google akan menggunakan nama ini, bukan nama tampilan terdaftar Anda, dan akan menyertakan pesan bahwa identitas aplikasi Anda tidak dapat diverifikasi.

Catatan: Untuk menyetel parameter xoauth_displayname di OAuth Playground, centang kotak "Advanced" sebelum mengambil token permintaan.

Bekerja dengan domain Google Apps

Jika aplikasi Anda dirancang untuk pengguna di domain Akun Google yang dihosting, pertimbangkan untuk menggunakan parameter hd saat mengizinkan token. Untuk mengetahui informasi selengkapnya tentang parameter hd, lihat Menangani Pengguna dengan Beberapa Akun.

Informasi selengkapnya tentang OAuth

Untuk mengetahui informasi mendetail tentang penerapan OAuth oleh Google, termasuk cara mendaftarkan aplikasi dan membuat parameter OAuth yang diperlukan, lihat referensi tambahan berikut:

Kembali ke atas

Menggunakan OAuth dengan aplikasi terinstal

Semua Google Data API mendukung OAuth, standar terbuka untuk memberikan otorisasi penggunaan data dalam aplikasi. Aplikasi yang diinstal tidak perlu didaftarkan ke Google untuk menggunakan OAuth.

Proses otorisasi OAuth

Proses otorisasi OAuth melibatkan serangkaian interaksi antara aplikasi Anda, server otorisasi Google, dan pengguna akhir.

Pada tingkat dasar, prosesnya adalah sebagai berikut:

  1. Aplikasi Anda meminta akses dan mendapatkan token permintaan tidak sah dari server otorisasi Google.
  2. Google meminta pengguna untuk memberi Anda akses ke data yang diperlukan.
  3. Aplikasi Anda mendapatkan token permintaan yang diberi otorisasi dari server otorisasi.
  4. Anda menukar token permintaan yang diizinkan dengan token akses.
  5. Anda menggunakan token akses untuk meminta data dari server akses layanan Google.

Saat aplikasi Anda pertama kali meminta akses ke data pengguna, Google akan menerbitkan token permintaan yang tidak sah ke aplikasi Anda.

Jika pengguna belum login, Google akan meminta pengguna untuk login. Kemudian, Google akan menampilkan halaman otorisasi yang memungkinkan pengguna melihat data layanan Google yang aksesnya diminta oleh aplikasi Anda.

Jika pengguna menyetujui permintaan akses aplikasi Anda, Google akan menerbitkan token permintaan yang sah. Setiap token permintaan hanya valid selama satu jam. Hanya token permintaan yang sah yang dapat ditukar dengan token akses, dan penukaran ini hanya dapat dilakukan satu kali per token permintaan yang sah.

OAuth mendukung aplikasi yang diinstal menggunakan mode tidak terdaftar. Karena ada berbagai metode untuk mendapatkan token permintaan yang sah, aplikasi Anda dapat menggunakan OAuth untuk mengotorisasi aplikasi meskipun perangkat tempat aplikasi diinstal tidak memiliki browser web.

Secara default, token akses memiliki masa berlaku yang lama. Setiap token akses khusus untuk akun pengguna yang ditentukan dalam permintaan otorisasi asli, dan memberikan akses hanya ke layanan yang ditentukan dalam permintaan tersebut. Aplikasi Anda harus menyimpan token akses dengan aman, karena token ini diperlukan untuk semua akses ke data pengguna.

Mempersiapkan OAuth

Sebelum dapat menyiapkan aplikasi untuk menggunakan layanan Otorisasi Google dengan OAuth, Anda harus menyelesaikan tugas berikut.

Menentukan cakupan data yang akan diakses aplikasi Anda

Setiap layanan Google menetapkan batas pada akses yang diizinkannya melalui Google Data API. Akses ini dinyatakan sebagai nilai cakupan. Beberapa layanan menyediakan berbagai nilai cakupan, untuk memungkinkan pengguna memilih aplikasi mana yang harus memiliki akses ke data mana. Untuk mengetahui informasi tentang nilai cakupan yang tersedia untuk layanan Google yang ingin Anda akses, lihat dokumentasi untuk layanan tersebut.

Secara umum, Anda harus meminta token untuk cakupan tersempit yang mencakup data yang Anda butuhkan. Misalnya, jika aplikasi Anda memerlukan akses ke feed "Semua Kalender" pengguna, Anda harus meminta token untuk cakupan http://www.google.com/calendar/feeds/default/allcalendars/full.

Menyiapkan mekanisme untuk mengelola token OAuth

Saat Anda mendapatkan token akses OAuth untuk data pengguna, Anda harus menggunakan token akses tersebut untuk semua interaksi mendatang dengan layanan Google yang ditentukan atas nama pengguna.

Aplikasi Anda harus mengelola penyimpanan token dengan aman, termasuk melacak layanan Google yang valid untuk setiap token.

Jika aplikasi Anda mendukung beberapa akun pengguna, Anda harus melacak akun yang terkait dengan setiap token.

Menyiapkan mekanisme untuk meminta akses ke layanan Google

Setiap permintaan ke layanan Google harus ditandatangani, dan harus menyertakan token akses OAuth yang valid. Secara umum, setiap permintaan dibuat dalam bentuk permintaan HTTP GET, dengan token akses dan tanda tangan disertakan dalam header. Permintaan yang menulis data baru harus menggunakan HTTP POST.

Untuk mengetahui informasi selengkapnya tentang format permintaan yang tepat untuk setiap Google Data API, lihat dokumentasi untuk API tersebut.

Menggunakan token OAuth

Untuk menggunakan OAuth, aplikasi Anda harus membuat panggilan permintaan token yang ditandatangani dan dibuat dengan baik, serta menangani respons, untuk urutan berikut:

  1. Mendapatkan token permintaan yang tidak sah (OAuthGetRequestToken)
  2. Memberi otorisasi token permintaan (OAuthAuthorizeToken)
  3. Menukarkan token permintaan yang diotorisasi dengan token akses (OAuthGetAccessToken)

Semua permintaan OAuth harus ditandatangani, terlepas dari apakah aplikasi Anda terdaftar atau tidak. Untuk mengetahui informasi lebih lanjut, lihat Menandatangani Permintaan OAuth. Aplikasi yang diinstal harus mengikuti petunjuk untuk aplikasi yang tidak terdaftar.

Anda dapat bereksperimen dengan meminta dan menerima token otorisasi di OAuth Playground.

Untuk dokumentasi mendetail, lihat Referensi API OAuth.

Mengidentifikasi aplikasi Anda kepada pengguna

Google biasanya menampilkan nama aplikasi saat meminta izin akses dari pengguna (lihat contoh).

Gunakan parameter xoauth_displayname dalam permintaan OAuthGetRequestToken untuk menentukan nama aplikasi Anda. Jika parameter tersebut tidak ditentukan, Google akan menampilkan nama domain URL yang diberikan oleh parameter oauth_callback. Jika tidak ada URL callback yang diberikan, Google akan menampilkan string "anonymous".

Catatan: Untuk menyetel parameter xoauth_displayname di OAuth Playground, centang kotak "Advanced" sebelum mengambil token permintaan.

Meluncurkan browser web

Sebagai bagian dari proses otorisasi OAuth, aplikasi Anda harus membuat permintaan OAuthAuthorizeToken. Pengguna kemudian harus login ke halaman web Google dan mengizinkan permintaan akses aplikasi Anda.

  • Mode AutoDetect harus digunakan untuk sebagian besar aplikasi
  • Mode perangkat harus digunakan untuk aplikasi yang tidak dapat meluncurkan browser web penuh.
  • Mode pengembangan hanya boleh digunakan selama pengembangan awal.

Mode Deteksi Otomatis

Jika memungkinkan, aplikasi Anda harus meluncurkan jendela browser dan membuat permintaan OAuthAuthorizeToken untuk membuka halaman Google. Saat Google menampilkan token yang sah, aplikasi Anda harus mendeteksinya dan mendapatkan kembali fokus dari browser web.

Mode ini mengharuskan Anda memberikan URL callback yang menjadi tujuan pengalihan pengguna setelah mereka mengizinkan permintaan akses Anda. URL ini harus diberikan sebagai parameter oauth_callback dari permintaan OAuthGetRequestToken, dan sebagai parameter verifier dari permintaan OAuthGetAccessToken.

Untuk meningkatkan pengalaman pengguna, aplikasi Anda harus mencoba mendeteksi secara otomatis saat pengguna dialihkan ke URL ini, dan segera membawa dirinya ke latar depan dan membuat permintaan OAuthGetAccessToken untuk menyelesaikan proses OAuth.

Untuk mengetahui informasi dan praktik terbaik selengkapnya, lihat Persetujuan Deteksi Otomatis.

Jika aplikasi Anda tidak dapat mendeteksi secara otomatis saat pengguna dialihkan ke URL callback, atau tidak dapat menampilkan dirinya di latar depan, URL callback harus menampilkan halaman yang menjelaskan cara menampilkan aplikasi Anda di latar depan dan cara memulai permintaan OAuthGetAccessToken dari dalam aplikasi Anda.

Mode perangkat

Jika aplikasi Anda tidak dapat meluncurkan browser web lengkap, perangkat klien kaya juga dapat mengizinkan tanpa browser web.

Mode ini memungkinkan developer menyiapkan situs tempat pengguna dapat mengizinkan permintaan akses. Setelah otorisasi, pengguna akan diberi kode yang dibuat oleh Google, dan dialihkan ke situs developer. Situs ini harus menjelaskan kepada pengguna cara memasukkan kode ke perangkat mereka untuk menyelesaikan proses otorisasi.

Mode pengembangan

Mode ini direkomendasikan untuk digunakan selama pengembangan awal aplikasi saja.

Seperti dalam mode DeteksiOtomatis, aplikasi Anda harus meluncurkan browser, dan pengguna harus mengizinkan permintaan Anda. Namun, alih-alih membuat halaman web untuk URL callback, Anda dapat menetapkan nilai parameter oauth_callback ke "oob" (di luar band).

Dalam hal ini, setelah pengguna mengizinkan permintaan Anda, Google akan mengarahkan pengguna ke halaman Akun Google yang menampilkan nomor verifikasi (lihat contoh).

Pengguna harus kembali ke aplikasi Anda dan memasukkan nomor verifikasi sebelum Anda dapat membuat permintaan OAuthGetAccessToken.

Informasi selengkapnya tentang OAuth

Untuk mengetahui informasi mendetail tentang penerapan OAuth oleh Google, termasuk cara mendaftarkan aplikasi dan membuat parameter OAuth yang diperlukan, lihat referensi tambahan berikut:

Kembali ke atas

Menggunakan AuthSub untuk otorisasi

AuthSub adalah API otorisasi eksklusif Google, yang tersedia sebagai alternatif untuk OAuth bagi sebagian besar Google API. Sebaiknya hindari penggunaan AuthSub jika memungkinkan. Jika sudah memiliki aplikasi yang menggunakan AuthSub, Anda harus bermigrasi ke OAuth atau protokol hybrid.

Proses otorisasi AuthSub

Otorisasi dengan AuthSub melibatkan serangkaian interaksi antara tiga entitas: aplikasi web, layanan Google, dan pengguna. Diagram ini menggambarkan urutannya:

Proses otorisasi

  1. Saat aplikasi web perlu mengakses layanan Google pengguna, aplikasi tersebut melakukan panggilan AuthSub ke layanan Proxy Otorisasi Google.
  2. Layanan Otorisasi merespons dengan menampilkan halaman Permintaan Akses. Halaman yang dikelola Google ini akan meminta pengguna untuk memberikan/menolak akses ke layanan Google mereka. Pengguna mungkin diminta untuk login ke akunnya terlebih dahulu.
  3. Pengguna memutuskan apakah akan memberikan atau menolak akses ke aplikasi web. Jika pengguna menolak akses, mereka akan diarahkan ke halaman Google, bukan kembali ke aplikasi web.
  4. Jika pengguna memberikan akses, layanan Otorisasi akan mengalihkan pengguna kembali ke aplikasi web. Pengalihan berisi token otorisasi yang berlaku untuk satu kali penggunaan; token ini dapat ditukar dengan token yang memiliki masa aktif lama.
  5. Aplikasi web menghubungi layanan Google dengan permintaan, menggunakan token otorisasi untuk bertindak sebagai agen bagi pengguna.
  6. Jika layanan Google mengenali token, layanan tersebut akan memberikan data yang diminta.

Bekerja dengan AuthSub

Untuk menyertakan AuthSub ke dalam aplikasi web Anda, Anda harus melakukan tugas berikut:

  1. Tentukan apakah akan mendaftarkan aplikasi web Anda atau tidak.

    Aplikasi web terdaftar memiliki keuntungan karena diakui oleh Google; peringatan standar yang ditampilkan kepada pengguna di halaman login Google diubah atau dihilangkan. Selain itu, aplikasi web terdaftar diidentifikasi dengan nama deskriptif, bukan hanya URL panggilan. Perlu diingat bahwa beberapa layanan Google hanya mengizinkan akses terbatas ke aplikasi web yang tidak terdaftar. Jika Anda memilih untuk mendaftar, gunakan proses pendaftaran otomatis ini.

    Jika mendaftar, Anda juga dapat memberikan sertifikat dan kunci keamanan. Aplikasi web terdaftar dengan sertifikat yang tercatat dapat memperoleh token aman untuk digunakan saat meminta data dari layanan Google. (Mereka juga dapat menggunakan token tidak aman jika diperlukan.)

  2. Tentukan jenis token yang akan digunakan dan cara mengelolanya.

    Token otorisasi yang diterima dari Google dimaksudkan untuk digunakan untuk semua interaksi mendatang dengan layanan Google tertentu untuk pengguna tersebut. Jenis token yang Anda pilih untuk digunakan--sekali pakai atau sesi--bergantung pada jenis interaksi yang akan dilakukan aplikasi web Anda dengan layanan Google. Misalnya, token sekali pakai mungkin sudah cukup jika interaksinya adalah peristiwa satu kali atau jarang terjadi.

    Jika Anda memilih untuk mendapatkan token sesi dan menggunakannya secara rutin untuk mengakses layanan Google, aplikasi web Anda harus mengelola penyimpanan token, termasuk melacak pengguna dan layanan Google yang valid untuk token tersebut. Akun Google tidak disiapkan untuk mengelola sejumlah besar token, dan bahkan tidak mengizinkan lebih dari sepuluh token valid (per pengguna, per aplikasi web) yang belum digunakan dalam satu waktu. Batasan ini memungkinkan aplikasi web mendapatkan beberapa token untuk mencakup layanan yang berbeda, jika perlu; batasan ini tidak mendukung perolehan token baru setiap kali aplikasi web perlu mengakses layanan Google. Jika Anda memutuskan untuk menyimpan token sesi, token tersebut harus diperlakukan seaman informasi sensitif lainnya yang disimpan di server.

    Atau, Anda dapat memilih untuk mendapatkan token baru secara rutin selama Anda menyiapkan mekanisme pencabutan token. Aplikasi Anda harus mencabut token yang ada sebelum meminta token lain. Dalam skenario ini, pengguna akan diminta untuk login dan memberikan akses setiap kali token baru diminta.

  3. Tentukan cakupan yang diperlukan oleh layanan Google yang akan diakses.

    Setiap layanan Google menentukan jumlah dan jenis akses yang akan diizinkan. Akses ini dinyatakan sebagai nilai cakupan. Cakupan layanan dapat berupa URL sederhana yang mengidentifikasi seluruh layanan, atau dapat menentukan akses yang lebih terbatas. Beberapa layanan membatasi akses secara ketat, seperti hanya mengizinkan akses hanya baca ke informasi terbatas. Untuk mendapatkan cakupan yang diizinkan untuk layanan Google yang ingin Anda akses, lihat dokumentasi untuk layanan tersebut. Anda harus meminta token dengan cakupan yang paling sempit. Misalnya, jika mencoba mengakses fitur feed Atom Gmail, gunakan cakupan "http://www.google.com/calendar/feeds/", bukan "http://www.google.com/calendar/". Layanan Google jauh lebih ketat dengan permintaan cakupan besar.

  4. Siapkan mekanisme untuk meminta dan menerima token otorisasi.

    Mekanisme ini harus membuat panggilan AuthSubRequest yang terbentuk dengan baik, termasuk menentukan nilai URL next dan scope yang sesuai (ditentukan pada langkah 3). Jika Anda menggunakan token aman dan/atau mengelola token sesi, permintaan juga harus menyertakan nilai untuk variabel ini.

    URL berikutnya dapat menyertakan parameter kueri. Misalnya, saat mendukung beberapa bahasa, sertakan parameter kueri yang mengidentifikasi versi aplikasi web yang dilihat pengguna. Nilai next sebesar http://www.yoursite.com/Retrievetoken?Lang=de akan menghasilkan pengalihan http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. Mem-parsing token dan parameter Lang memastikan pengguna dialihkan kembali ke versi situs yang benar.

    Dalam situasi tertentu, penggunaan parameter hd dapat membantu menyederhanakan pengalaman pengguna saat mereka diminta untuk memberikan akses di situs Akun Google. Biasanya, prosesnya cukup dengan login ke akun mereka dan memilih apakah akan memberikan akses atau tidak. Namun, pengguna yang memiliki lebih dari satu Akun Google (akun gmail biasa dan/atau satu atau beberapa akun yang dihosting Google Apps) mungkin perlu mengikuti proses "login universal" tambahan untuk mengidentifikasi akun mana yang ingin mereka akses. Jika aplikasi Anda dirancang untuk satu domain terkelola tertentu, Anda dapat menghilangkan langkah-langkah tambahan ini dengan menggunakan parameter ini untuk mengidentifikasi domain tersebut. Anda juga dapat menggunakan parameter hd jika aplikasi Anda mengakses layanan yang tidak tersedia di akun yang dihosting. Menetapkan nilai ke 'default' akan membatasi otorisasi hanya untuk akun reguler. Jika nilai hd ditetapkan, Google akan otomatis memilih akun yang benar untuk otorisasi.

    Mekanisme token harus dilengkapi untuk mengurai pengalihan yang diterima dari Google, yang berisi token sekali pakai, dan mengambil tindakan dengannya. Karena token otorisasi khusus untuk pengguna, aplikasi Anda harus dapat mengaitkan token dengan penggunanya. Opsi yang lebih disukai adalah mengeluarkan cookie kepada pengguna sebelum membuat permintaan token. Kemudian, saat Google mengalihkan pengguna kembali ke situs Anda dengan token yang ditambahkan, aplikasi Anda dapat membaca cookie dan mengaitkan token dengan identifikasi pengguna yang benar.

  5. Siapkan mekanisme untuk meminta token sesi dan menyimpan atau mencabutnya, jika relevan.

    Bergantung pada keputusan pengelolaan token yang Anda buat di langkah 2, Anda mungkin perlu membuat mekanisme untuk mendapatkan dan mencabut token sesi (AuthSubSessionToken dan AuthSubRevokeToken). Untuk menguji mekanisme sesi dan pencabutan, gunakan AuthSubTokenInfo, yang menunjukkan apakah token tertentu valid atau tidak. Jika menyimpan token, aplikasi harus melacak ID pengguna dan layanan (cakupan) yang tercakup oleh token.

  6. Siapkan mekanisme untuk meminta akses ke layanan Google.

    Lihat dokumentasi untuk layanan Google guna mengetahui informasi tentang format permintaan yang tepat. Semua permintaan ke layanan Google harus menyertakan token otorisasi yang valid. Secara umum, permintaan ke layanan Google berbentuk HTTP GET (atau POST jika menulis data baru), dengan token yang dirujuk di header permintaan.

    Header permintaan harus menggunakan format berikut:

    Authorization: AuthSub token="token"

    dengan token adalah token otorisasi, sekali pakai atau sesi, yang diterima dari Google sebagai respons terhadap permintaan AuthSub. Jika token aman, token tersebut harus disertai dengan tanda tangan digital. Lihat "Menandatangani permintaan" untuk mengetahui petunjuk dan contohnya.

    Contoh di bawah ini menggambarkan header permintaan untuk panggilan ke layanan feed Google Kalender. Permintaan ini berisi token yang tidak aman: 

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

Informasi selengkapnya tentang AuthSub

Untuk mengetahui informasi tentang AuthSub, termasuk cara mendaftarkan aplikasi Anda ke Google dan penjelasan mendetail tentang cara menukar token sekali pakai dengan token sesi, lihat referensi tambahan berikut:

Kembali ke atas

Menggunakan ClientLogin untuk otorisasi

ClientLogin adalah API otorisasi eksklusif Google, yang tersedia sebagai alternatif untuk OAuth bagi sebagian besar Google API. Sebaiknya hindari penggunaan ClientLogin jika memungkinkan. Jika sudah memiliki aplikasi yang menggunakan ClientLogin, Anda harus bermigrasi ke OAuth atau protokol hybrid.

Autentikasi untuk Aplikasi Terinstal: ClientLogin

ClientLogin memungkinkan pengguna Anda login ke Akun Google mereka dari dalam aplikasi Anda. Kemudian, aplikasi menghubungi Google dengan data login dan meminta akses ke Google Data API tertentu. Setelah informasi login berhasil diautentikasi, Google akan menampilkan token, yang akan dirujuk oleh aplikasi Anda setiap kali aplikasi tersebut meminta akses ke akun pengguna, seperti untuk mendapatkan atau memposting data. Token tetap valid selama jangka waktu tertentu, yang ditentukan oleh layanan Google yang Anda gunakan.

Catatan: Library Klien Google Data API menyediakan metode untuk membantu Anda menggunakan ClientLogin di aplikasi yang terinstal. Secara khusus, ada metode untuk mendapatkan token autentikasi, menangani tantangan CAPTCHA, memanggil kembali token autentikasi untuk digunakan nanti, dan mengirim header Authorization yang benar dengan setiap permintaan. Jika Anda menggunakan salah satu library, lihat Menggunakan ClientLogin dengan Library Klien Google Data API.

Proses otorisasi ClientLogin

Otorisasi dengan ClientLogin melibatkan serangkaian interaksi antara tiga entitas: aplikasi yang diinstal, layanan Google, dan pengguna. Diagram ini menggambarkan urutannya:

Proses otorisasi

  1. Saat aplikasi pihak ketiga perlu mengakses layanan Google pengguna, aplikasi tersebut akan mengambil nama login dan sandi pengguna.
  2. Kemudian, aplikasi pihak ketiga melakukan panggilan ClientLogin ke layanan Otorisasi Google.
  3. Jika layanan Otorisasi Google memutuskan bahwa pemeriksaan tambahan diperlukan, layanan tersebut akan menampilkan respons kegagalan dengan token dan tantangan CAPTCHA, dalam bentuk URL untuk gambar CAPTCHA.
  4. Jika tantangan CAPTCHA diterima, aplikasi pihak ketiga akan menampilkan gambar CAPTCHA kepada pengguna dan meminta jawaban dari pengguna.
  5. Jika diminta, pengguna mengirimkan jawaban untuk tantangan CAPTCHA.
  6. Aplikasi pihak ketiga melakukan panggilan ClientLogin baru, kali ini menyertakan jawaban dan token CAPTCHA (diterima dengan respons kegagalan).
  7. Pada upaya login yang berhasil (dengan atau tanpa tantangan CAPTCHA), layanan Otorisasi Google akan menampilkan token ke aplikasi.
  8. Aplikasi menghubungi layanan Google dengan permintaan akses data, dengan merujuk ke token yang diterima dari layanan Otorisasi Google.
  9. Jika layanan Google mengenali token tersebut, layanan akan memberikan akses data yang diminta.

Menggunakan ClientLogin

Gunakan antarmuka ini di aplikasi yang Anda instal untuk mengakses Akun Google pengguna secara terprogram. Setelah mengumpulkan informasi login dari pengguna, panggil ClientLogin untuk meminta akses ke akun pengguna. Setelah informasi login berhasil diautentikasi, Google akan menampilkan token, yang akan dirujuk oleh aplikasi Anda setiap kali aplikasi meminta akses ke akun pengguna. Token tetap valid selama jangka waktu tertentu, yang ditentukan oleh layanan Google yang Anda gunakan.

Untuk menyertakan ClientLogin ke dalam aplikasi Anda, Anda harus melakukan tugas berikut:

  1. Buat elemen UI untuk merekam data login dari pengguna.

    UI perlu meminta nama pengguna (alamat email termasuk domain) dan sandi. UI juga harus dapat menampilkan gambar CAPTCHA menggunakan URL yang diterima dari Google, jika diperlukan, dan meminta jawaban yang benar dari pengguna. Idealnya, UI Anda akan menyertakan link ke halaman login Akun Google ("https://www.google.com/accounts/Login") jika pengguna perlu mendaftar untuk akun baru atau melakukan pemeliharaan akun lainnya.

  2. Tulis kode untuk membuat permintaan ClientLogin POST HTTPS yang terbentuk dengan baik dan kirimkan.

    Kode ini harus berisi logika untuk menangani verifikasi CAPTCHA dan menyertakan parameter logintoken dan logincaptcha. Aplikasi juga harus dapat mendeteksi saat pengguna menghilangkan informasi yang diperlukan--atau mengulangi data yang salah setelah kegagalan login--dan menampilkan error tanpa mengirim permintaan yang tidak diperlukan.

  3. Menangani respons dari Google.

    Ada empat kemungkinan respons terhadap permintaan login:

    • berhasil (HTTP 200)
    • kegagalan (HTTP 403) dengan kode error penjelasan
    • permintaan tidak valid, umumnya disebabkan oleh permintaan yang salah format
    • gagal menyelesaikan verifikasi CAPTCHA

    Respons keberhasilan berisi token otorisasi berlabel "Auth". Token ini harus disertakan dalam semua permintaan berikutnya ke layanan Google untuk akun ini. Token otorisasi harus dijaga dengan ketat dan tidak boleh diberikan ke aplikasi lain, karena token tersebut mewakili akses ke akun pengguna. Batas waktu token bervariasi, bergantung pada layanan yang menerbitkannya.

    Respons kegagalan mencakup satu atau beberapa kode error dan URL dengan pesan error yang dapat ditampilkan untuk pengguna. Perhatikan bahwa ClientLogin tidak membedakan antara kegagalan karena sandi yang salah atau karena nama pengguna yang tidak dikenal (misalnya, jika pengguna belum mendaftar untuk mendapatkan akun). Aplikasi Anda harus menangani semua kemungkinan pesan error dengan tepat.

    Respons kegagalan dengan tantangan CAPTCHA berarti Google telah memutuskan, karena alasan apa pun, bahwa tindakan keamanan tambahan harus dilakukan. Respons ini disertai dengan URL gambar CAPTCHA dan token yang merepresentasikan tantangan CAPTCHA tertentu.

  4. Menangani tantangan CAPTCHA dari Google.

    Untuk menangani tantangan, aplikasi harus menampilkan gambar CAPTCHA dan meminta jawaban dari pengguna. Untuk menampilkan gambar CAPTCHA, gunakan nilai CaptchaUrl yang ditampilkan dengan respons kegagalan, dengan menambahkan awalan URL Akun Google: "http://www.google.com/accounts/". Setelah pengguna memberikan jawaban, aplikasi harus mengirim ulang permintaan login, kali ini menyertakan token CAPTCHA (logintoken) dan jawaban pengguna (logincaptcha). Google memvalidasi jawaban pengguna sebelum mengizinkan akses ke akun.

    Ada alternatif bagi developer yang tidak ingin mengelola proses mendapatkan dan mengirimkan respons CAPTCHA pengguna. Sebagai respons terhadap tantangan CAPTCHA, aplikasi dapat mengarahkan pengguna ke halaman yang dihosting Google: "https://www.google.com/accounts/DisplayUnlockCaptcha". Setelah pengguna berhasil merespons tantangan, server Google akan memercayai komputer yang digunakan. Kemudian, aplikasi dapat mengirim ulang permintaan login asli untuk mendapatkan token otorisasi.

    5. Catatan: Google tidak memvalidasi upaya login sebelum mengeluarkan verifikasi CAPTCHA. Artinya, upaya login dapat gagal meskipun setelah verifikasi CAPTCHA.

* CAPTCHA adalah merek dagang Carnegie Mellon University

Kembali ke atas

Autentikasi untuk Gadget

Proxy OAuth

Jika Anda membuat gadget menggunakan Gadgets API standar, Anda dapat memanfaatkan fitur platform gadget yang disebut OAuth Proxy untuk mengakses Google Data API. OAuth (dijelaskan di atas) adalah standar autentikasi yang memungkinkan pengguna mengakses data pribadi mereka di layanan hosting gadget seperti iGoogle, MySpace, atau Orkut, atau membagikan data mereka ke situs atau gadget lain. OAuth Proxy dirancang untuk mempermudah pengembangan bagi developer gadget dengan menyembunyikan banyak detail autentikasi OAuth. Proxy ini didasarkan pada project open source bernama Shindig, yang merupakan implementasi spesifikasi gadget.

Catatan: OAuth Proxy hanya didukung untuk gadget yang menggunakan gadgets.* API dan berjalan di penampung OpenSocial. Layanan ini tidak didukung untuk API gadget lama.

Alur autentikasi

Gadget Anda harus mendapatkan token OAuth sebelum dapat mengakses data pengguna. OAuth Proxy mengelola alur autentikasi untuk Anda. Saat pengguna menginstal gadget Anda untuk pertama kalinya, proses berikut akan terjadi:

  1. Gadget Anda dimuat untuk pertama kalinya dan mencoba mengakses data pengguna menggunakan salah satu Google Data API.
  2. Permintaan gagal karena pengguna belum memberikan akses. Objek respons berisi URL (di response.oauthApprovalUrl) untuk halaman persetujuan OAuth. Gadget Anda harus menyediakan metode untuk meluncurkan jendela baru dengan URL tersebut.
  3. Di halaman persetujuan, pengguna memilih untuk memberikan atau menolak akses ke gadget Anda. Jika berhasil, pengguna akan diarahkan ke halaman oauth_callback yang Anda tentukan. Untuk mendapatkan pengalaman pengguna terbaik, gunakan http://oauth.gmodules.com/gadgets/oauthcallback.
  4. Selanjutnya, pengguna menutup jendela pop-up. Untuk memberi tahu gadget Anda bahwa pengguna telah menyetujui, Anda dapat menggunakan popup handler untuk mendeteksi penutupan jendela persetujuan. Atau, gadget Anda dapat menampilkan link (misalnya, "Saya telah menyetujui akses") yang dapat diklik pengguna setelah jendela ini ditutup.
  5. Gadget Anda mencoba mengakses Google Data API untuk kedua kalinya dengan meminta ulang data pengguna. Upaya ini berhasil.
  6. Gadget Anda diautentikasi dan dapat mulai beroperasi secara normal.

Penyiapan gadget

Untuk mengakses satu atau beberapa Google Data API, Anda harus terlebih dahulu memberi tahu gadget Anda untuk menggunakan OAuth sebagai metode autentikasi. Tambahkan elemen <OAuth> di bagian <ModulePrefs> XML gadget Anda:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

Di bagian ini, hanya ubah parameter kueri berikut:

scope
Parameter wajib di URL Permintaan. Gadget Anda dapat mengakses data dari scope yang digunakan dalam parameter ini. Dalam contoh ini, gadget dapat mengakses data Blogger dan Kalender. Gadget dapat meminta data untuk satu cakupan atau beberapa cakupan, seperti contoh ini.
oauth_callback
Parameter opsional di URL Otorisasi. Halaman persetujuan OAuth dialihkan ke URL ini setelah pengguna menyetujui akses ke data. Anda harus menyetel parameter ini ke http://oauth.gmodules.com/gadgets/oauthcallback untuk memberikan pengalaman pengguna terbaik saat pengguna menginstal gadget Anda. Halaman tersebut menyediakan cuplikan JavaScript yang otomatis menutup jendela pop-up. Atau, Anda dapat menetapkan parameter ini untuk mengarah ke halaman "yang disetujui" milik Anda, atau Anda cukup mengosongkan parameter ini.

Mengakses feed Google Data API yang diautentikasi

Setelah gadget Anda mengautentikasi pengguna, mengakses Google Data API menjadi mudah dengan library klien JavaScript Google Data API. Untuk mengetahui informasi tentang cara menggunakan library di OAuth Proxy, lihat Menggunakan Library Klien JavaScript.

Informasi selengkapnya tentang Gadget

Untuk mengetahui informasi lengkap tentang cara membuat Gadget Google Data API, termasuk detail tentang Proxy OAuth, artikel tentang cara memulai, dan spesifikasi gadgets.*, lihat referensi tambahan berikut:

Kembali ke atas