Halaman ini diterjemahkan oleh Cloud Translation API.

Autentikasi dan Otorisasi di Protokol Data Google

Peringatan: Halaman ini membahas API lama Google, yaitu Google Data API; halaman ini hanya relevan dengan API yang tercantum dalam direktori Google Data API, banyak di antaranya telah diganti dengan API yang lebih baru. Untuk informasi tentang API baru tertentu, lihat dokumentasi API baru. Untuk informasi tentang memberi otorisasi permintaan dengan API 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 menangani privasi dengan serius, dan setiap aplikasi yang memerlukan akses ke data pengguna harus diizinkan oleh pengguna.

Layanan autentikasi dan otorisasi sering disebut sebagai auth.

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

Login dengan Google memberikan cara mudah untuk mengizinkan orang menggunakan kredensial Google-nya untuk login ke situs Anda. Platform 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 kriptografi 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 dengan Akun Google. Ini adalah pengganti OpenID, dan pengguna OpenID seharusnya berencana untuk bermigrasi ke Login dengan OAuth 2.0.

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

Catatan: Dokumen ini dimaksudkan untuk memberikan ringkasan dari setiap metode autentikasi. Untuk informasi mendetail tentang setiap metode, lihat dokumentasi lengkap API Autentikasi Akun Google.

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

OAuth - otorisasi untuk web dan aplikasi yang diinstal

Banyak layanan Google mengizinkan akses pihak ketiga ke data buatan pengguna, seperti data Kalender atau Dokumen, selama akses tersebut diotorisasi oleh pengguna. Fitur ini memungkinkan pengguna berbagi dan bertukar data antara aplikasi Google dan aplikasi pihak ketiga mereka 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 web dan aplikasi yang terinstal

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

OAuth 1.0 untuk aplikasi web

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

OAuth 1.0 untuk aplikasi yang terinstal

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

Menggunakan OAuth dengan aplikasi web

Semua Google Data API mendukung OAuth, yaitu standar terbuka untuk mengizinkan 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 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, memberi otorisasi pada token permintaan, dan menukar token permintaan yang diotorisasi dengan token akses. Library juga menangani algoritme penandatanganan yang diperlukan saat membuat permintaan ke layanan Data Google. Untuk mengetahui contoh lengkap tentang cara menggunakan OAuth dengan Library Klien Google Data API,lihat Menggunakan OAuth dengan Library Klien Google Data API.

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:

Aplikasi Anda meminta akses dan mendapatkan token permintaan yang tidak sah dari server otorisasi Google.
Google meminta pengguna memberi Anda akses ke data yang diperlukan.
Aplikasi Anda mendapatkan token permintaan yang diotorisasi dari server otorisasi.
Anda menukar token permintaan resmi dengan token akses.
Anda dapat menggunakan token akses untuk meminta data dari server akses layanan Google.

Saat aplikasi Anda awalnya meminta akses ke data pengguna, Google akan mengeluarkan 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 diminta oleh aplikasi Anda.

Jika pengguna menyetujui permintaan akses aplikasi Anda, Google akan menerbitkan token permintaan yang diotorisasi. Setiap token permintaan hanya berlaku selama satu jam. Hanya token permintaan resmi yang dapat ditukarkan dengan token akses, dan pertukaran ini hanya dapat dilakukan sekali per token permintaan yang diotorisasi.

Secara default, token akses berumur panjang. Setiap token akses khusus untuk akun pengguna yang ditentukan dalam permintaan otorisasi awal, dan hanya memberikan akses ke layanan yang ditentukan dalam permintaan tersebut. Aplikasi Anda harus menyimpan token akses dengan aman, karena diperlukan untuk semua akses ke data pengguna.

Bersiap untuk OAuth

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

Menentukan apakah akan mendaftarkan aplikasi web atau tidak

Untuk memberi pengguna jaminan tambahan terhadap keamanan data mereka, Anda dapat memilih untuk mendaftarkan aplikasi web Anda ke Google dan menandatangani permintaan Anda dengan sertifikat keamanan yang terdaftar. Beberapa feed Google Data API hanya tersedia untuk aplikasi yang 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 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. Tanda tangan tidak diperlukan untuk tanda tangan HMAC-SHA1. Sebaliknya, Google akan membuat nilai consumer secret OAuth, yang ditampilkan di halaman pendaftaran domain setelah Anda mendaftar.

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

Menentukan cakupan data yang akan diakses aplikasi Anda

Setiap layanan Google menetapkan batas akses yang diizinkan 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 tertentu. Untuk 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 menyertakan 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 mendapatkan token akses OAuth untuk data pengguna, Anda harus menggunakan token akses tersebut untuk semua interaksi mendatang dengan layanan Google tertentu atas nama pengguna.

Aplikasi Anda harus mengelola penyimpanan token dengan aman, termasuk melacak layanan Google yang valid untuk setiap token. Jika Anda 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 dapat masih berjalan kapan saja.

Jika aplikasi mendukung beberapa akun pengguna, Anda harus melacak akun mana yang terkait dengan setiap token. Setiap token OAuth dikhususkan untuk pengguna yang mengizinkan akses. Aplikasi Anda harus dapat mengaitkan token dengan pengguna yang benar. Salah satu cara untuk mengelolanya adalah dengan memberikan 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 Anda untuk mengaitkan token tersebut dengan pengguna yang tepat.

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 yang disertakan dalam header. Permintaan yang menulis data baru harus menggunakan HTTP POST.

Untuk mendapatkan informasi lebih lanjut 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 tersebut. Dengan OpenID+OAuth, tugas mendapatkan token permintaan dan mengotorisasinya ditangani sebagai bagian dari permintaan OpenID dengan ekstensi OAuth. Seperti halnya OAuthGetRequestToken, ekstensi ini digunakan untuk mengidentifikasi layanan Google yang akan diakses. Respons yang berhasil terhadap permintaan OpenID berisi token permintaan yang diotorisasi. Setelah token ini diterima, gunakan OAuthGetAccessToken untuk menukarnya dengan token akses.

Menggunakan token OAuth

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

Mendapatkan token permintaan yang tidak sah (OAuthGetRequestToken)
Mengizinkan token permintaan (OAuthAuthorizeToken)
Tukarkan token permintaan yang diotorisasi dengan token akses (OAuthGetAccessToken)

Semua permintaan OAuth harus ditandatangani, terlepas dari apakah aplikasi Anda sudah terdaftar atau belum. Untuk informasi selengkapnya, lihat Menandatangani Permintaan OAuth.

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

Untuk dokumentasi mendetail, lihat Referensi OAuth API.

Menetapkan URL callback

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

Misalnya, saat mendukung beberapa bahasa, Anda dapat menyertakan parameter kueri yang mengidentifikasi versi aplikasi yang sedang dilihat pengguna. Nilai oauth_callback "http://www.yoursite.com/Taketoken?Lang=de akan menghasilkan pengalihan "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Mengurai token dan parameter bahasa akan memastikan bahwa 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 Anda mengizinkan permintaan akses tersebut. Pengguna harus kembali secara manual ke aplikasi Anda dan memasukkan nomor verifikasi sebelum Anda bisa mendapatkan token permintaan yang diotorisasi.

Mengidentifikasi aplikasi Anda kepada pengguna

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

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

Jangan setel 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 menggunakannya, bukan nama tampilan terdaftar, dan akan menyertakan pesan yang menyatakan bahwa identitas aplikasi Anda tidak dapat diverifikasi.

Catatan: Untuk menetapkan parameter xoauth_displayname di OAuth Playground, centang kotak "Lanjutan" 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 memberi otorisasi token. Untuk informasi selengkapnya tentang parameter hd, lihat Menangani Pengguna dengan Beberapa Akun.

Informasi selengkapnya tentang OAuth

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

Menggunakan OAuth dengan Library Klien Google Data API
Artikel: Menggunakan OAuth dengan Google Data API, termasuk deskripsi OAuth Playground, alat interaktif untuk mencoba OAuth.
OAuth untuk Aplikasi Web (dokumentasi lengkap)
Pendaftaran untuk Aplikasi Berbasis Web
Membuat kunci dan sertifikat
Spesifikasi OAuth

Kembali ke atas

Menggunakan OAuth dengan aplikasi terinstal

Semua Google Data API mendukung OAuth, yaitu standar terbuka untuk mengizinkan penggunaan data di 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:

Aplikasi Anda meminta akses dan mendapatkan token permintaan yang tidak sah dari server otorisasi Google.
Google meminta pengguna memberi Anda akses ke data yang diperlukan.
Aplikasi Anda mendapatkan token permintaan yang diotorisasi dari server otorisasi.
Anda menukar token permintaan resmi dengan token akses.
Anda dapat menggunakan token akses untuk meminta data dari server akses layanan Google.

Saat aplikasi Anda awalnya meminta akses ke data pengguna, Google akan mengeluarkan token permintaan yang tidak sah ke aplikasi Anda.

OAuth mendukung aplikasi terinstal yang menggunakan mode tidak terdaftar. Karena ada berbagai metode untuk mendapatkan token permintaan yang diotorisasi, aplikasi Anda dapat menggunakan OAuth untuk mengizinkan aplikasi meskipun perangkat tempatnya diinstal tidak memiliki browser web.

Bersiap untuk OAuth

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

Menentukan cakupan data yang akan diakses aplikasi Anda

Menyiapkan mekanisme untuk mengelola token OAuth

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

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

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

Menyiapkan mekanisme untuk meminta akses ke layanan Google

Untuk mendapatkan informasi lebih lanjut tentang format permintaan yang tepat untuk setiap Google Data API, lihat dokumentasi untuk API tersebut.

Menggunakan token OAuth

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

Mendapatkan token permintaan yang tidak sah (OAuthGetRequestToken)
Mengizinkan token permintaan (OAuthAuthorizeToken)
Tukarkan token permintaan yang diotorisasi dengan token akses (OAuthGetAccessToken)

Semua permintaan OAuth harus ditandatangani, terlepas dari apakah aplikasi Anda sudah terdaftar atau belum. Untuk informasi selengkapnya, 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 OAuth API.

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 dari URL yang disediakan oleh parameter oauth_callback. Jika tidak ada URL callback yang diberikan, Google akan menampilkan string "anonim".

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

Meluncurkan browser web

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

Mode Deteksi Otomatis harus digunakan untuk sebagian besar aplikasi
Mode perangkat harus digunakan untuk aplikasi yang tidak dapat meluncurkan browser web lengkap.
Mode pengembangan sebaiknya digunakan selama pengembangan awal saja.

Mode Deteksi Otomatis

Jika memungkinkan, aplikasi Anda harus meluncurkan jendela browser dan membuat permintaan OAuthAuthorizeToken untuk membuka halaman Google. Saat Google menampilkan token yang diotorisasi, 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 disediakan sebagai parameter oauth_callback permintaan OAuthGetRequestToken, dan sebagai parameter verifier dari permintaan OAuthGetAccessToken.

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

Untuk informasi lebih lanjut dan praktik terbaik, lihat Persetujuan Deteksi Otomatis.

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

Mode perangkat

Jika aplikasi tidak dapat meluncurkan browser web lengkap, perangkat klien yang kaya juga dapat melakukan otorisasi tanpa browser web.

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

Mode pengembangan

Mode ini direkomendasikan untuk digunakan selama pengembangan awal aplikasi saja.

Seperti pada mode AutoDetect, aplikasi Anda harus meluncurkan browser, dan pengguna harus mengotorisasi 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 informasi mendetail tentang penerapan OAuth Google, termasuk cara mendaftarkan aplikasi dan membuat parameter OAuth yang diperlukan, lihat referensi tambahan berikut:

Menggunakan OAuth dengan Library Klien Google Data API
Artikel: Menggunakan OAuth dengan Google Data API, termasuk deskripsi OAuth Playground, alat interaktif untuk mencoba OAuth.
OAuth untuk Aplikasi yang Terinstal (dokumentasi lengkap)
Membuat kunci dan sertifikat
Spesifikasi OAuth

Kembali ke atas

Menggunakan AuthSub untuk otorisasi

AuthSub adalah API otorisasi eksklusif Google, yang tersedia sebagai alternatif OAuth untuk 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 urutan interaksi antara tiga entity: aplikasi web, layanan Google, dan pengguna. Diagram ini menggambarkan urutan:

Proses otorisasi

Saat aplikasi web perlu mengakses layanan Google, aplikasi web membuat panggilan AuthSub ke layanan Proxy Otorisasi Google.
Layanan Otorisasi merespons dengan menayangkan halaman Permintaan Akses. Halaman yang dikelola Google ini meminta pengguna untuk memberikan/menolak akses ke layanan Google mereka. Pengguna mungkin diminta untuk login ke akunnya terlebih dahulu.
Pengguna memutuskan apakah akan memberikan atau menolak akses ke aplikasi web. Jika menolak akses, pengguna akan diarahkan ke halaman Google, bukan kembali ke aplikasi web.
Jika pengguna memberikan akses, layanan Otorisasi akan mengalihkan pengguna kembali ke aplikasi web. Pengalihan tersebut berisi token otorisasi yang bagus untuk satu kali penggunaan. Token dapat ditukar dengan token yang tahan lama.
Aplikasi web menghubungi layanan Google dengan permintaan, menggunakan token otorisasi untuk bertindak sebagai agen bagi pengguna.
Jika layanan Google mengenali token tersebut, layanan akan akan memberikan data yang diminta.

Menangani AuthSub

Menggabungkan AuthSub ke dalam aplikasi web Anda memerlukan tugas-tugas berikut:

Putuskan apakah Anda akan mendaftarkan aplikasi web atau tidak.
Aplikasi web yang terdaftar memiliki keuntungan karena dikenali 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. Perhatikan 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 kunci dan sertifikat keamanan. Aplikasi web yang 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.)
Tentukan jenis token yang akan digunakan dan cara mengelolanya.
Token otorisasi yang diterima dari Google dimaksudkan untuk digunakan bagi semua interaksi di masa mendatang dengan layanan Google yang ditentukan untuk pengguna tersebut. Jenis token yang Anda pilih untuk digunakan, yaitu sekali pakai atau sesi, bergantung pada jenis interaksi yang akan dilakukan aplikasi web Anda dengan layanan Google. Misalnya, token sekali pakai mungkin cukup jika interaksinya adalah peristiwa satu kali atau jarang.

Jika Anda memilih untuk mendapatkan token sesi dan menggunakannya secara berkala 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 token dalam jumlah besar, dan faktanya tidak mengizinkan lebih dari sepuluh token yang valid (per pengguna, per aplikasi web) untuk diproses pada satu waktu. Batasan ini memungkinkan aplikasi web mendapatkan beberapa token untuk mencakup berbagai layanan, jika diperlukan; aplikasi ini tidak mendukung pengambilan 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 berkala selama Anda menyiapkan mekanisme pencabutan token. Aplikasi Anda harus mencabut token yang ada sebelum meminta token lain. Dalam skenario ini, pengguna akan diwajibkan untuk login dan memberikan akses setiap kali token baru diminta.
Tentukan cakupan yang diperlukan oleh layanan Google untuk diakses.
Setiap layanan Google menentukan seberapa banyak dan jenis akses apa yang akan diizinkan. Akses ini dinyatakan sebagai nilai cakupan. Cakupan layanan dapat berupa URL sederhana yang mengidentifikasi keseluruhan layanan, atau dapat menentukan akses yang lebih terbatas. Beberapa layanan sangat membatasi akses, seperti mengizinkan akses hanya baca ke informasi terbatas. Untuk mendapatkan cakupan yang diizinkan untuk layanan Google yang ingin Anda akses, lihat dokumentasi untuk layanan tersebut. Sebaiknya Anda meminta token dengan cakupan yang paling ketat. 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 yang besar.
Siapkan mekanisme untuk meminta dan menerima token otorisasi.
Mekanismenya harus menghasilkan panggilan AuthSubRequest yang diformat 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 berikutnya dari http://www.yoursite.com/Retrievetoken?Lang=de akan menghasilkan pengalihan http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE. Mengurai token dan parameter Lang akan memastikan bahwa pengguna dialihkan kembali ke versi situs yang benar.

Dalam keadaan tertentu, penggunaan parameter hd dapat membantu menyederhanakan pengalaman pengguna Anda saat mereka diminta untuk memberikan akses di situs Akun Google. Dalam kebanyakan kasus, proses ini cukup memudahkan untuk login ke akun mereka dan memilih apakah akan memberikan akses atau tidak. Namun, pengguna yang memiliki lebih dari satu Akun Google (akun gmail reguler dan/atau satu atau beberapa akun yang dihosting Google Apps), mungkin perlu mengikuti proses "login universal" tambahan untuk mengidentifikasi akun mana yang ingin diakses. Jika aplikasi Anda didesain 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 mengakses layanan yang tidak tersedia di akun yang dihosting--menyetel nilai ke 'default' akan membatasi otorisasi hanya untuk akun reguler. Jika nilai hd ditetapkan, Google akan secara otomatis memilih akun yang benar untuk otorisasi.

Mekanisme token harus dilengkapi untuk menguraikan pengalihan yang diterima dari Google, yang berisi token sekali pakai, dan mengambil tindakan terhadap token tersebut. Karena token otorisasi bersifat 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 tersebut dan mengaitkan token tersebut dengan identifikasi pengguna yang benar.
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 AuthSub UnplugToken). Untuk menguji mekanisme sesi dan pencabutan, gunakan AuthSubTokenInfo, yang menunjukkan apakah token tertentu valid atau tidak. Jika token disimpan, aplikasi harus melacak ID pengguna dan layanan (cakupan) yang dicakup oleh token.
Siapkan mekanisme untuk meminta akses ke layanan Google.
Lihat dokumentasi untuk layanan Google untuk informasi tentang format permintaan yang tepat. Semua permintaan ke layanan Google harus menyertakan token otorisasi yang valid. Secara umum, permintaan ke layanan Google berbentuk GET HTTP (atau POST jika menulis data baru), dengan token yang direferensikan di header permintaan.

Header permintaan harus dalam 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 harus disertai dengan tanda tangan digital. Lihat "Permintaan penandatanganan" untuk mendapatkan petunjuk dan contoh.

Contoh di bawah mengilustrasikan header permintaan untuk panggilan ke layanan feed Google Kalender. Permintaan ini berisi token 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 informasi tentang AuthSub, termasuk mendaftarkan aplikasi Anda ke Google dan penjelasan terperinci tentang pertukaran token satu kali dengan token sesi, lihat referensi tambahan berikut:

AuthSub Authentication untuk Aplikasi Web (dokumentasi lengkap)
Menggunakan AuthSub dengan Library Klien Google Data API
Membuat kunci dan sertifikat (Autentikasi AuthSub)
Menandatangani Permintaan dengan AuthSub (AuthSub aman)
Pendaftaran untuk Aplikasi Berbasis Web

Kembali ke atas

Menggunakan ClientLogin untuk otorisasi

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

Authentication untuk Aplikasi Terinstal: ClientLogin

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

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

Proses otorisasi ClientLogin

Otorisasi dengan ClientLogin melibatkan urutan interaksi antara tiga entitas: aplikasi terinstal, layanan Google, dan pengguna. Diagram ini menggambarkan urutan:

Proses otorisasi

Jika aplikasi pihak ketiga perlu mengakses layanan Google pengguna, aplikasi tersebut akan mengambil nama login dan sandi pengguna.
Aplikasi pihak ketiga kemudian melakukan panggilan ClientLogin ke layanan Otorisasi Google.
Jika layanan Otorisasi Google memutuskan pemeriksaan tambahan diperlukan, layanan tersebut akan menampilkan respons kegagalan dengan token dan tantangan CAPTCHA, dalam bentuk URL untuk gambar CAPTCHA.
Jika tantangan CAPTCHA diterima, aplikasi pihak ketiga akan menampilkan gambar CAPTCHA untuk pengguna dan meminta jawaban dari pengguna.
Jika diminta, pengguna akan mengirimkan jawaban atas tantangan CAPTCHA.
Aplikasi pihak ketiga melakukan panggilan ClientLogin baru, kali ini termasuk jawaban dan token CAPTCHA (diterima dengan respons kegagalan).
Jika upaya login berhasil (dengan atau tanpa verifikasi CAPTCHA), layanan Otorisasi Google akan menampilkan token ke aplikasi.
Aplikasi tersebut menghubungi layanan Google dengan permintaan akses data, dengan merujuk token yang diterima dari layanan Otorisasi Google.
Jika layanan Google mengenali token tersebut, layanan akan memberikan akses data yang diminta.

Menggunakan ClientLogin

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

Menyertakan ClientLogin ke dalam aplikasi Anda memerlukan tugas berikut:

Buat elemen UI untuk mengambil data login dari pengguna.
UI harus 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 akun baru atau melakukan pemeliharaan akun lainnya.
Tulis kode untuk membuat permintaan ClientLogin POST HTTPS yang dibentuk dengan baik dan mentransmisikannya.
Kode ini harus berisi logika untuk menangani tantangan CAPTCHA dan menyertakan parameter logintoken serta logincaptcha. Aplikasi juga harus dapat mendeteksi kapan pengguna menghapus informasi yang diperlukan--atau mengulangi data yang salah setelah kegagalan login--dan menampilkan error tanpa harus mengirim permintaan yang berlebihan.
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 hasil permintaan yang salah
- kegagalan dengan tantangan CAPTCHA
Respons sukses 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 menyertakan satu atau beberapa kode error dan URL dengan pesan error yang dapat ditampilkan untuk pengguna. Harap perhatikan bahwa ClientLogin tidak membedakan antara kegagalan karena sandi yang salah atau sandi karena nama pengguna tidak dikenal (misalnya, jika pengguna belum mendaftar untuk akun). Aplikasi Anda harus menangani semua kemungkinan pesan error sebagaimana mestinya.
Respons kegagalan dengan verifikasi CAPTCHA berarti Google telah memutuskan untuk mengambil tindakan keamanan tambahan karena alasan keamanan apa pun. Respons ini disertai dengan URL gambar CAPTCHA dan token yang mewakili tantangan CAPTCHA tertentu.
Tangani 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, awali dengan URL Akun Google: "http://www.google.com/accounts/". Setelah pengguna memberikan jawaban, aplikasi harus mengirim ulang permintaan login, kali ini termasuk token CAPTCHA (logintoken) dan jawaban pengguna (logincaptcha). Google akan memvalidasi jawaban pengguna sebelum mengizinkan akses ke akun.

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

Catatan: Google tidak memvalidasi upaya login sebelum mengeluarkan tantangan CAPTCHA. Ini berarti upaya login bisa gagal bahkan setelah tantangan CAPTCHA.

* CAPTCHA adalah merek dagang dari Carnegie Mellon University

Kembali ke atas

Autentikasi untuk Gadget

Proxy OAuth

Jika membuat gadget menggunakan Gadgets API standar, Anda dapat memanfaatkan fitur platform gadget yang disebut Proxy OAuth 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. Proxy OAuth dirancang untuk membuat pengembangan lebih mudah bagi developer gadget dengan menyembunyikan banyak detail autentikasi OAuth. Proxy ini didasarkan pada project open source yang disebut Shindig, yang merupakan implementasi dari spesifikasi gadget.

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

Alur autentikasi

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

Gadget Anda dimuat untuk pertama kali dan berupaya mengakses data pengguna menggunakan salah satu Google Data API.
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.
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 pengalaman pengguna terbaik, gunakan http://oauth.gmodules.com/gadgets/oauthcallback.
Selanjutnya, pengguna menutup jendela pop-up. Untuk memberi tahu gadget Anda bahwa pengguna telah menyetujui, Anda dapat menggunakan pengendali pop-up untuk mendeteksi penutupan jendela persetujuan. Atau, gadget Anda dapat menampilkan link (mis. "Saya telah menyetujui akses") untuk diklik pengguna setelah jendela ini ditutup.
Gadget Anda mencoba mengakses Google Data API untuk kedua kalinya dengan meminta kembali data pengguna. Upaya ini berhasil.
Gadget telah diautentikasi dan dapat mulai beroperasi secara normal.

Penyiapan gadget

Untuk mengakses satu atau beberapa Google Data API, Anda terlebih dahulu perlu memberi tahu gadget Anda untuk menggunakan OAuth sebagai metode autentikasi. Tambahkan elemen <OAuth> di bagian <ModulePrefs> pada 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 yang diperlukan 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 yang dilakukan pada contoh ini.
oauth_callback: Parameter opsional di URL Otorisasi. Halaman persetujuan OAuth akan 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 secara otomatis menutup jendela pop-up. Atau, Anda dapat menetapkan parameter ini agar mengarah ke halaman "disetujui" sendiri, atau cukup mengosongkan parameter.

Mengakses feed Google Data API yang diautentikasi

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

Informasi lebih lanjut tentang Gadget

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

Menggunakan Library Klien JavaScript
Membuat Gadget Google Data API (artikel)
Menulis Gadget OAuth (dokumentasi gadget lengkap)
Dokumentasi Gadgets API

Kembali ke atas