Halaman ini diterjemahkan oleh Cloud Translation API.

OAuth untuk Data Agent API

Dokumen Terkait

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

Ringkasan

Biasanya, untuk memberikan akses kepada resource 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 dan dengan demikian mengamankan dan membatasi akses ke resource yang dilindungi milik pengguna akhir.

GTAF mendapatkan token akses, bukan menggunakan kredensial pengguna akhir untuk mengakses resource yang dilindungi, seperti detail paket data. Token akses diterbitkan ke GTAF atas nama kredensial GTAF. GTAF kemudian 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 mewakili otorisasi yang dikeluarkan untuk GTAF. String ini biasanya tidak sama dengan GTAF. Token merepresentasikan cakupan dan durasi akses tertentu, yang diberikan oleh pengguna akhir ke operator, dan diterapkan oleh server OAuth serta server DPA dan operator.

Token akses memberikan 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 menghapus kebutuhan DPA untuk memahami berbagai metode autentikasi.

Token akses dapat memiliki format, struktur, dan metode penggunaan yang berbeda (misalnya, properti kriptografis) berdasarkan persyaratan keamanan operator. GTAF hanya mendukung token akses jenis pemilik yang ditetapkan di [RFC6750].

Autentikasi Klien

GTAF berfungsi sebagai "klien rahasia" dan mampu menjaga keamanan sandi. GTAF saat ini hanya mendukung autentikasi HTTP Basic untuk melakukan autentikasi dengan DPA. ID klien dienkode menggunakan algoritme encoding "application/x-www-form-url dienkode" dan nilai yang dienkode digunakan sebagai nama pengguna; sandi dienkode menggunakan algoritme yang sama dan digunakan sebagai sandi.

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

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

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

Yang sangat penting adalah kemampuan untuk merotasi kredensial klien. Server OAuth harus dapat mendukung dua pasang kredensial simultan selama rotasi, dan harus memiliki kemampuan untuk menonaktifkan kredensial. Dalam rotasi kredensial standar:

Operator membuat kredensial baru di server OAuth dan mengirimkan kredensial ke Manajer Akun Teknis dengan cara yang aman.
Google menguji kredensial baru dan mengubah konfigurasi GTAF untuk menggunakan kredensial baru.
Google akan 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 menunjukkan pemberian otorisasi atau token refresh. Endpoint token digunakan dengan setiap pemberian otorisasi kecuali untuk jenis pemberian implisit (karena token akses diterbitkan secara langsung).

Berikut adalah 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-urlusercontent" yang harus dipertahankan saat menambahkan parameter kueri tambahan. URI endpoint tidak boleh menyertakan komponen fragmen.
Karena permintaan ke endpoint token menghasilkan transmisi kredensial teks yang jelas (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 untuk token akses.
Parameter yang dikirim tanpa nilai harus diperlakukan sebagai dihilangkan dari 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 pemilik.

Cakupan Token Akses

Endpoint otorisasi dan token memungkinkan klien menentukan cakupan permintaan akses menggunakan parameter "scope" permintaan. 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 dipisahkan spasi dan peka huruf besar/kecil. String ditentukan oleh server otorisasi. Jika nilai berisi beberapa string yang dipisahkan spasi, urutannya tidak menjadi masalah, 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 memerlukan penerapan cakupan, tetapi mendukung fitur ini. Untuk informasi selengkapnya, lihat Bagian 3.3 tentang RFC 6749.

Memberikan Token Akses

Jika permintaan token akses yang dikirim oleh GTAF valid dan diotorisasi, server OAuth akan mengirimkan 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 yang Berhasil

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

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

Parameter tersebut disertakan dalam isi entity 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 "Cache-Control" HTTP 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 tidak ditentukan.
GTAF harus menghindari membuat 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 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 Tidak Valid) (kecuali ditentukan lain) dan harus menyertakan setidaknya salah satu parameter yang tercantum di bagian Respons Error dan Kode.

Pemberian Otorisasi di GTAF

Hibah otorisasi adalah kredensial yang mewakili otorisasi pengguna akhir (untuk mengakses resource terlindunginya seperti informasi saldo data) yang digunakan oleh GTAF untuk mendapatkan token akses.

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

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

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

Contoh Permintaan dan Respons

Misalnya 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, client ID, ':', dan sandi digabungkan dan dienkode base64. Hal ini dapat direplikasi dalam antarmuka command line sebagai berikut:

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

GTAF kemudian membuat permintaan POST HTTPS ke server OAuth menggunakan kredensial ini, jenis pemberian client_credentials, dan cakupan yang dikonfigurasi. Misalnya, 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 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 salah satu alasan yang dinyatakan di bagian Error Respons, 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	permintaan_tidak valid	Permintaan tidak memiliki parameter wajib, menyertakan parameter value yang tidak didukung (selain jenis pemberian), mengulangi parameter, menyertakan beberapa kredensial, menggunakan lebih dari satu mekanisme untuk mengautentikasi dengan GTAF, atau menggunakan format yang salah.
HTTP 401	tidak valid_client	Autentikasi klien gagal (misalnya, klien tidak diketahui, tidak termasuk autentikasi klien, 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 "Otorisasi", server OAuth harus merespons dengan kode status HTTP 401 (Tidak Sah) dan menyertakan kolom header "WWW-Authenticate" yang cocok dengan skema autentikasi yang digunakan oleh klien.
HTTP 500	Kegagalan server OAuth

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