Halaman ini diterjemahkan oleh Cloud Translation API.

OAuth untuk Data Agent API

Dokumen Terkait

OAuth 2.0 distandardisasi sebagai RFC 6749. Dokumen mendetail tersedia di https://oauth.net/2. Autentikasi Dasar HTTP didefinisikan dalam bagian 2 RFC 2617.

Ringkasan

Biasanya, untuk memberikan akses aplikasi pihak ketiga ke resource yang dibatasi seperti paket data dan detail dompet, pengguna akhir (pemilik resource) perlu membagikan kredensialnya kepada pihak ketiga. Hal ini menimbulkan beberapa masalah dan batasan seperti penyimpanan kredensial, autentikasi sandi, akses luas ke resource pengguna akhir, dan kebocoran sandi, dll. OAuth2.0 mengatasi masalah ini dengan memperkenalkan lapisan otorisasi, sehingga mengamankan dan membatasi akses ke resource yang dilindungi milik pengguna akhir.

Daripada menggunakan kredensial pengguna akhir untuk mengakses resource yang dilindungi seperti detail paket data, GTAF mendapatkan token akses. Token akses dikeluarkan ke GTAF atas nama kredensial GTAF. Kemudian, GTAF menggunakan token akses untuk mengakses detail paket data yang dihosting oleh DPA.

Gambar berikut memberikan alur informasi tingkat tinggi:

Gambar 1. Alur OAuth Abstrak.

Token Akses

Token akses adalah kredensial yang digunakan oleh GTAF untuk mengakses detail paket data dari DPA operator. Token akses adalah string yang merepresentasikan otorisasi yang dikeluarkan untuk GTAF. String biasanya tidak transparan untuk GTAF. Token merepresentasikan cakupan dan durasi akses tertentu, yang diberikan oleh pengguna akhir kepada operator, dan diterapkan oleh DPA dan server OAuth operator.

Token akses menyediakan lapisan abstraksi, menggantikan berbagai konstruksi otorisasi (misalnya, nama pengguna dan sandi) dengan satu token yang dipahami oleh DPA. Abstraksi ini memungkinkan penerbitan token akses yang lebih ketat daripada pemberian otorisasi yang digunakan untuk mendapatkannya, serta menghilangkan kebutuhan DPA untuk memahami berbagai metode autentikasi.

Token akses dapat memiliki format, struktur, dan metode penggunaan yang berbeda-beda (misalnya, properti kriptografi) berdasarkan persyaratan keamanan operator. GTAF hanya mendukung token akses jenis pembawa yang ditentukan dalam [RFC6750].

Autentikasi Klien

GTAF berfungsi sebagai "klien rahasia" dan mampu menjaga keamanan sandi. Saat ini, GTAF hanya mendukung autentikasi Dasar HTTP untuk mengautentikasi dengan DPA. ID klien dienkode menggunakan algoritma encoding "application/x-www-form-urlencoded", dan nilai yang dienkode digunakan sebagai nama pengguna; sandi dienkode menggunakan algoritma yang sama dan digunakan sebagai sandi.

Klien rahasia seperti GTAF, yang diberi kredensial klien, melakukan autentikasi dengan server OAuth operator saat membuat permintaan ke endpoint token. Autentikasi klien digunakan untuk: \

Memulihkan klien yang disusupi dengan menonaktifkan klien atau mengubah kredensialnya, sehingga mencegah penyerang menyalahgunakan token refresh yang dicuri. Mengubah satu set kredensial klien jauh lebih cepat daripada mencabut seluruh set token refresh.
Menerapkan praktik terbaik pengelolaan autentikasi, yang memerlukan rotasi kredensial berkala.

GTAF menggunakan parameter permintaan "client_id" untuk mengidentifikasi dirinya sendiri saat mengirim permintaan ke endpoint token.

Yang sangat penting adalah kemampuan untuk mengganti kredensial klien. Server OAuth harus dapat mendukung dua pasangan kredensial simultan selama rotasi, dan harus memiliki kemampuan untuk menonaktifkan kredensial. Dalam rotasi kredensial yang umum:

Operator membuat kredensial baru di server OAuth dan mengirimkan kredensial tersebut kepada Technical Account Manager mereka dengan cara yang aman.
Google menguji kredensial baru dan mengubah konfigurasi GTAF untuk menggunakan kredensial baru.
Google memberi tahu operator bahwa kredensial lama mungkin dinonaktifkan.
Operator menonaktifkan kredensial dan memberi tahu Google
Google memverifikasi bahwa kredensial lama tidak lagi beroperasi

Server OAuth harus dapat mendukung proses rotasi di atas.

Endpoint Token

Endpoint token digunakan oleh GTAF untuk mendapatkan token akses dengan menyajikan pemberian otorisasi atau token refresh-nya. Endpoint token digunakan dengan setiap pemberian otorisasi kecuali untuk jenis pemberian implisit (karena token akses dikeluarkan secara langsung).

Berikut beberapa poin yang perlu dipertimbangkan saat mengonfigurasi endpoint token:

Lokasi endpoint token harus diberikan dalam dokumentasi layanan.
URI endpoint dapat menyertakan komponen kueri berformat "application/x-www-form-urlencoded" yang harus dipertahankan saat menambahkan parameter kueri tambahan. URI endpoint tidak boleh menyertakan komponen fragmen.
Karena permintaan ke endpoint token menghasilkan transmisi kredensial teks biasa (dalam permintaan dan respons HTTP), server OAuth operator harus menggunakan TLS untuk mengirim permintaan ke endpoint token.
GTAF menggunakan metode HTTP "POST" saat membuat permintaan token akses.
Parameter yang dikirim tanpa nilai harus diperlakukan sebagai tidak ada dalam permintaan. Server OAuth harus mengabaikan parameter permintaan yang tidak dikenal. Parameter permintaan dan respons tidak boleh disertakan lebih dari sekali.
GTAF hanya mendukung token akses jenis pembawa.

Cakupan Token Akses

Endpoint otorisasi dan token memungkinkan klien menentukan cakupan permintaan akses menggunakan parameter permintaan "scope". Selanjutnya, server otorisasi menggunakan parameter respons "scope" untuk memberi tahu klien tentang cakupan token akses yang dikeluarkan.

Nilai parameter cakupan dinyatakan sebagai daftar string yang peka huruf besar/kecil dan dibatasi spasi. String ditentukan oleh server otorisasi. Jika nilai berisi beberapa string yang dibatasi spasi, urutannya tidak penting, dan setiap string menambahkan rentang akses tambahan ke cakupan yang diminta.

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF tidak mewajibkan cakupan diterapkan, tetapi mendukung fitur ini. Untuk mengetahui informasi selengkapnya, lihat Bagian 3.3 dari RFC 6749.

Menerbitkan Token Akses

Jika permintaan token akses yang dikirim oleh GTAF valid dan diotorisasi, server OAuth akan mengeluarkan token akses dan token refresh opsional. Jika permintaan gagal autentikasi klien atau tidak valid, server OAuth akan menampilkan respons error seperti yang dijelaskan di bagian berikut.

Respons Berhasil

Saat GTAF mengirim permintaan, server OAuth akan mengeluarkan token akses dan token refresh opsional, serta membuat respons dengan menambahkan parameter berikut ke entity-body respons HTTP dengan kode status 200 (OK): \

access_token: WAJIB. Token akses yang dikeluarkan oleh server OAuth. GTAF mengharapkan endpoint token menampilkan token pembawa.
expires_in: WAJIB. Masa aktif token akses dalam detik. Misalnya, nilai "3600" menunjukkan bahwa masa berlaku token akses akan berakhir dalam satu jam sejak waktu respons dibuat. Jika tidak disertakan, server OAuth harus memberikan waktu habis masa berlaku melalui cara lain atau mendokumentasikan nilai default.
token_type: WAJIB. Jenis token yang diterbitkan. Untuk mengetahui informasi selengkapnya tentang berbagai jenis token, lihat Bagian 7.1 dari RFC 6749. Nilai ini tidak peka huruf besar/kecil. GTAF hanya mendukung token pembawa pada saat penulisan ini.
refresh_token: OPSIONAL. Token refresh, yang dapat digunakan untuk mendapatkan token akses baru menggunakan pemberian otorisasi yang sama.
scope: OPSIONAL, jika diterapkan dan identik dengan cakupan yang diminta oleh GTAF; jika tidak, wajib diisi.

Parameter disertakan dalam entity-body respons HTTP menggunakan "application/json". Parameter diserialisasi ke dalam struktur JavaScript Object Notation (JSON) dengan menambahkan setiap parameter di tingkat struktur tertinggi. Nama parameter dan nilai string disertakan sebagai string JSON. Nilai numerik disertakan sebagai angka JSON. Urutan parameter tidak menjadi masalah dan dapat bervariasi.

Server otorisasi HARUS menyertakan kolom header respons HTTP "Cache-Control" dengan nilai "no-store" dalam respons apa pun yang berisi token, kredensial, atau informasi sensitif lainnya, serta kolom header respons "Pragma" dengan nilai "no-cache".

Contoh:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Berikut beberapa poin penting yang perlu dipertimbangkan:

GTAF mengabaikan nama nilai yang tidak dikenal dalam respons.
Ukuran token dan nilai lain yang diterima dari server OAuth dibiarkan tidak ditentukan.
GTAF harus menghindari asumsi tentang ukuran nilai. Server OAuth harus mendokumentasikan ukuran nilai apa pun yang dikeluarkannya.

Respons Error

Jika permintaan otorisasi gagal karena alasan apa pun seperti URI pengalihan yang tidak ada, tidak valid, atau tidak cocok, atau jika ID klien tidak ada atau tidak valid, server OAuth harus merespons dengan kode status HTTP 400 (Permintaan Buruk) (kecuali ditentukan lain) dan harus menyertakan setidaknya salah satu parameter yang tercantum di bagian Respons dan Kode Error.

Pemberian Otorisasi di GTAF

Pemberian otorisasi adalah kredensial yang merepresentasikan otorisasi pengguna akhir (untuk mengakses resource yang dilindungi seperti informasi saldo data) yang digunakan oleh GTAF untuk mendapatkan token akses.

GTAF menggunakan jenis pemberian client_credentials. Dalam jenis pemberian client_credentials, GTAF meminta token menggunakan permintaan HTTP POST dan Autentikasi Dasar HTTP. Semua permintaan dikirim melalui TLS (yaitu, HTTPS), dan GTAF tidak dapat terintegrasi dengan server OAuth tanpa sertifikat TLS yang valid. GTAF dapat meneruskan cakupan token yang dapat dikonfigurasi dan akan meneruskan cakupan kosong jika cakupan tidak dikonfigurasi.

GTAF mengharapkan token akses ditampilkan bersama dengan nilai "expires_in" (waktu aktif). Nilai expires_in harus minimal 900 detik, dan tidak boleh lebih dari beberapa jam. Meminta token baru tidak boleh menyebabkan token yang ada berakhir lebih awal.

Untuk mengetahui detail selengkapnya tentang berbagai jenis pemberian, lihat bagian 1.3 dari RFC 6749.

Contoh Permintaan dan Respons

Misalkan GTAF memiliki konfigurasi berikut untuk server OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

Catatan: Rahasia klien untuk DPA sebenarnya harus jauh lebih aman daripada yang ditunjukkan dalam contoh.

Untuk menghasilkan string otorisasi, ID klien, ':', dan sandi digabungkan dan dienkode base64. Hal ini dapat direplikasi di antarmuka command line sebagai berikut:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

Kemudian, GTAF membuat permintaan POST HTTPS ke server OAuth menggunakan kredensial ini, jenis pemberian client_credentials, dan cakupan yang dikonfigurasi. Sebagai contoh, permintaan GTAF terlihat mirip dengan permintaan yang dihasilkan oleh:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

Header yang digunakan oleh GTAF tidak akan cocok dengan header yang dikirim oleh curl, meskipun header otorisasi akan identik.

GTAF mengharapkan respons dalam bentuk:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

Berikut adalah contoh respons yang valid:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

Catatan: Respons harus berupa JSON yang valid.

Respons dan Kode Error

Jika permintaan otorisasi dari GTAF gagal karena alasan apa pun yang dinyatakan di bagian Respons Error, server OAuth harus merespons dengan kode status HTTP 400 (Permintaan Buruk) (kecuali ditentukan lain) dan menyertakan salah satu parameter berikut dengan respons:

Contoh: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF mengharapkan server OAuth mendukung respons error berikut:

Kode Error	Respons	Alasan
HTTP 400	invalid_request	Permintaan tidak memiliki parameter wajib, menyertakan nilai parameter yang tidak didukung (selain jenis pemberian), mengulangi parameter, menyertakan beberapa kredensial, menggunakan lebih dari satu mekanisme untuk mengautentikasi dengan GTAF, atau salah bentuk.
HTTP 401	invalid_client	Autentikasi klien gagal (misalnya, klien tidak dikenal, tidak ada autentikasi klien yang disertakan, atau metode autentikasi tidak didukung). Server OAuth dapat menampilkan kode status HTTP 401 (Tidak Sah) untuk menunjukkan skema autentikasi HTTP yang didukung. Jika klien mencoba mengautentikasi melalui kolom header permintaan "Authorization", server OAuth harus merespons dengan kode status HTTP 401 (Tidak Sah) dan menyertakan kolom header respons "WWW-Authenticate" yang cocok dengan skema autentikasi yang digunakan oleh klien.
HTTP 500	Kegagalan server OAuth

Untuk mengetahui detail respons lain yang dapat digunakan untuk men-debug, lihat bagian 5.2 dari RFC 6749.

OAuth untuk Data Agent API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.