Implementasi aplikasi OAuth 2.0

Open Cloud mendukung alur otorisasi OAuth 2.0 dengan dan tanpa PKCE, tergantung pada apakah klien Anda bersifat rahasia atau publik.

• Klien rahasia adalah aplikasi yang dapat menjaga kredensial tetap rahasia, seperti situs web yang dapat menyimpan dan mengambil rahasia secara aman di backend-nya.
• Klien publik adalah aplikasi yang tidak dapat menjaga rahasia, seperti aplikasi seluler dan aplikasi browser web.

Kami merekomendasikan alur kode otorisasi OAuth 2.0 dengan PKCE untuk semua klien dan mewajibkannya untuk klien publik.

Untuk menerapkan alur kode otorisasi, aplikasi Anda melakukan langkah-langkah berikut:

1. Menghasilkan penilai kode dan tantangan kode (hanya untuk PKCE). Ini memungkinkan Anda menyertakan tantangan dalam permintaan Anda daripada rahasia klien, yang meningkatkan keamanan.
2. Kirim permintaan GET ke endpoint otorisasi dengan parameter yang sesuai.
3. Tangani callback otorisasi. Setelah memperoleh otorisasi, gunakan kode otorisasi dari Roblox dalam permintaan pengalihan ke URL yang Anda tentukan selama pembuatan aplikasi. Dapatkan kode otorisasi untuk digunakan nanti.
4. Kirim permintaan POST ke endpoint token dengan kode otorisasi. Jika berhasil, Anda akan menerima token akses dan token penyegaran untuk melakukan panggilan API.
5. Panggil API Open Cloud mana pun yang mendukung autentikasi OAuth 2.0 berdasarkan dokumentasi referensi untuk sumber daya yang ingin Anda akses.

Bagian berikut menjelaskan setiap langkah dengan lebih mendalam.

Menghasilkan tantangan kode (hanya untuk PKCE)

Sebelum memulai proses otorisasi, Anda perlu menghasilkan tantangan kode dari penilai kode. Anda dapat menggunakan pustaka atau fungsi bawaan dalam bahasa pemrograman pilihan Anda untuk membuat penilai kode, menghitung hash, dan melakukan pengkodean Base64 untuk menghasilkan tantangan kode.

Saat membuat penilai kode, hanya gunakan karakter yang tidak dipreservasi, termasuk huruf besar dan kecil (A-Z, a-z), digit desimal (0-9), tanda hubung (-), titik (.), garis bawah (_), dan tild (~), dengan panjang minimum 43 karakter dan maksimal 128 karakter.

Contoh berikut menunjukkan cara menggunakan Javascript untuk membuat penilai kode dan menghasilkan tantangan kode menggunakan algoritma hashing SHA-256:

Menghasilkan Tantangan Kode
const crypto = require('crypto');

// pengkodean base64URL untuk penilai dan tantangan
function base64URLEncode(str) {
  return str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
}

// membuat hash sha256 dari penilai kode
function sha256(buffer) {
  return crypto.createHash('sha256').update(buffer).digest(`base64`);
}

// membuat penilai kode acak
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// menghasilkan tantangan dari penilai kode
var code_challenge = base64URLEncode(sha256(code_verifier));

Untuk PKCE, Anda memerlukan baik nilai penilai kode maupun tantangan pada langkah-langkah selanjutnya.

Membangun URL otorisasi

Untuk memulai proses otorisasi pengguna, bangun sebuah URL otorisasi dengan parameter yang diperlukan:

• client_id: ID klien aplikasi Anda yang diperoleh setelah mendaftarkan aplikasi Anda.
• redirect_uri: URI pengalihan aplikasi Anda, titik masuk kembali aplikasi Anda.
• scope: Lingkup yang diminta yang mendefinisikan izin akses yang dibutuhkan aplikasi Anda dalam daftar yang dipisahkan dengan spasi.
• response_type: Setel ini ke code untuk menunjukkan alur kode otorisasi.

Diperlukan hanya untuk PKCE

• code_challenge: Tantangan kode yang dihasilkan dari penilai kode.
• code_challenge_method: Setel nilai parameter ini ke S256 untuk menunjukkan bahwa tantangan kode telah diubah menggunakan algoritma SHA-256, metode tantangan kode yang paling banyak didukung dan aman.
• state: Nilai acak yang tidak terlihat dan aman untuk mempertahankan keadaan antara permintaan dan callback.

Diperlukan hanya untuk non-PKCE

• client_secret: Rahasia klien aplikasi Anda yang diperoleh setelah mendaftarkan aplikasi Anda. Jika Anda menggunakan autentikasi dengan PKCE, hilangkan parameter ini. URL permintaan otorisasi Anda harus diformat dengan baik, seperti dalam contoh berikut:

Contoh URL Otorisasi PKCE
https://apis.roblox.com/oauth/v1/authorize?client_id=7290610391231237934964
    &code_challenge=PLEKKVCjdD1V_07wOKlAm7P02NC-LZ_1hQfdu5XSXEI
    &code_challenge_method=S256
    &redirect_uri=https://example.com/redirect
    &scope=openid%20profile
    &response_type=code
    &state=abc123

Ketika pengguna mengunjungi URL tersebut, mereka akan melalui alur otorisasi. Jika berhasil, Roblox mengarahkan pengguna ke redirect_uri yang ditentukan.

Menangani callback otorisasi

Ketika alur otorisasi berhasil, aplikasi Anda menerima permintaan GET dari server otorisasi Roblox di redirect_uri yang Anda tentukan. Dalam permintaan tersebut, Anda menerima parameter code (kode otorisasi) dan state (jika Anda memberikan nilai sebelumnya).

• Parameter code berisi kode otorisasi yang dapat ditukar aplikasi untuk mendapatkan token akses dari server otorisasi. Sebagian besar bahasa server backend memiliki cara standar untuk mengakses parameter kueri sebagai objek yang telah di-dekode. Anda perlu mendapatkan parameter code dan menggunakannya untuk ditukar dengan token akses.

• Parameter state adalah nilai yang tidak jelas yang awalnya Anda berikan dalam permintaan otorisasi. Anda dapat menggunakan parameter ini untuk mempertahankan keadaan atau konteks dari proses otorisasi.

Sebagai contoh, Anda mungkin menerima permintaan GET dengan URL berikut jika Anda menentukan URI pengalihan Anda menjadi https://example.com/redirect.

Contoh URL Pengalihan
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

Jika otorisasi gagal, aplikasi Anda menerima permintaan GET ke URL pengalihan yang ditentukan dengan parameter error, error_description, dan state (jika berlaku).

• Parameter error menunjukkan kesalahan OAuth 2.0 spesifik yang terjadi selama proses otorisasi.
• Parameter error_description memberikan detail tambahan tentang kesalahan.
• Parameter state membantu aplikasi Anda mempertahankan keadaan dalam kasus gagal.

Menukar kode otorisasi untuk token akses

Ketika Anda telah mendapatkan kode otorisasi code, tukarkan dengan token untuk mengakses sumber daya Roblox yang diinginkan:

1. Minta token akses dan token penyegaran dengan mengirimkan permintaan POST ke endpoint pertukaran token. Permintaan harus mencakup kode otorisasi, ID klien, dan nilai penilai kode (PKCE) atau rahasia klien (non-PKCE) dalam format x-www-form-urlencoded.

2. Dapatkan token yang berlaku dari respons yang diterima. Token akses berlaku selama 15 menit. Simpan token penyegaran dengan aman, biasanya di sisi server, agar Anda dapat menggunakannya untuk mendapatkan token baru di masa depan.

   Contoh Respons Endpoint Token
   {
     "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlBOeHhpb2JFNE8zbGhQUUlUZG9QQ3FCTE81amh3aXZFS1pHOWhfTGJNOWMiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwiYWlkIjoiM2Q2MWU3NDctM2ExNS00NTE4LWJiNDEtMWU3M2VhNDUyZWIwIiwic2NvcGUiOiJvcGVuaWQ6cmVhZCBwcm9maWxlOnJlYWQiLCJqdGkiOiJBVC5QbmFWVHpJU3k2YkI5TG5QYnZpTCIsIm5iZiI6MTY5MTYzOTY5OCwiZXhwIjoxNjkxNjQwNTk4LCJpYXQiOjE2OTE2Mzk2OTgsImlzcyI6Imh0dHBzOi8vYXBpcy5yb2Jsb3guY29tL29hdXRoLyIsImF1ZCI6IjcyOTA2MTAzOTc5ODc5MzQ5Nj1234.BjwMkC8Q5a_iP1Q5Th8FrS7ntioAollv_zW9mprF1ats9CD2axCvupZydVzYphzQ8TawunnYXp0Xe8k0t8ithg",
     "refresh_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoidGpHd1BHaURDWkprZEZkREg1dFZ5emVzRWQyQ0o1NDgtUi1Ya1J1TTBBRSIsInR5cCI6IkpXVCJ9..nKYZvjvXH6msDG8Udluuuw.PwP-_HJIjrgYdY-gMR0Q3cabNwIbmItcMEQHx5r7qStVVa5l4CbrKwJvjY-w9xZ9VFb6P70WmXndNifnio5BPZmivW5QkJgv5_sxLoCwsqB1bmEkz2nFF4ANLzQLCQMvQwgXHPMfCK-lclpVEwnHk4kemrCFOvfuH4qJ1V0Q0j0WjsSU026M67zMaFrrhSKwQh-SzhmXejhKJOjhNfY9hAmeS-LsLLdszAq_JyN7fIvZl1fWDnER_CeDAbQDj5K5ECNOHAQ3RemQ2dADVlc07VEt2KpSqUlHlq3rcaIcNRHCue4GfbCc1lZwQsALbM1aSIzF68klXs1Cj_ZmXxOSOyHxwmbQCHwY7aa16f3VEJzCYa6m0m5U_oHy84iQzsC-_JvBaeFCachrLWmFY818S-nH5fCIORdYgc4s7Fj5HdULnnVwiKeQLKSaYsfneHtqwOc_ux2QYv6Cv6Xn04tkB2TEsuZ7dFwPI-Hw2O30vCzLTcZ-Fl08ER0J0hhq4ep7B641IOnPpMZ1m0gpJJRPbHX_ooqHol9zHZ0gcLKMdYy1wUgsmn_nK_THK3m0RmENXNtepyLw_tSd5vqqIWZ5NFglKSqVnbomEkxneEJRgoFhBGMZiR-3FXMaVryUjq-N.Q_t4NGxTUSMsLVEppkTu0Q6rwt2rKJfFGuvy3s12345",
     "token_type": "Bearer",
     "expires_in": 899,
     "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkNWWDU1Mi1zeWh4Y1VGdW5vNktScmtReFB1eW15YTRQVllodWdsd3hnNzgiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg",
     "scope": "openid profile"
   }

Melakukan panggilan ke metode sumber daya

Sekarang Anda telah memperoleh token akses yang diperlukan, Anda dapat menggunakannya untuk melakukan panggilan terautentikasi ke metode sumber daya. Sertakan token akses dalam header dari semua permintaan API untuk mengotorisasinya.

Sebagai contoh, Anda dapat menguji apakah aplikasi Anda berfungsi dengan benar dengan melewati seluruh alur otorisasi dan kemudian melakukan permintaan GET ke endpoint informasi pengguna dengan token akses. Pastikan Anda memiliki scope openid atau baik openid dan profile sebelum memanggil endpoint ini. Jika berhasil, respons dari endpoint tersebut terlihat seperti ini:

Contoh Respons Informasi Pengguna
{
  "sub": "12345678",
  "name": "Jane Doe",
  "nickname": "robloxjanedoe",
  "preferred_username": "robloxjanedoe",
  "created_at": 1607354232,
  "profile": "https://www.roblox.com/users/12345678/profile"
}