Penerapan OAuth 2.0 | Dokumentasi - Pusat Kreator Roblox

Open Cloud mendukung alirsi otorisasi OAuth 2.0 dengan dan tanpa PKCE, tergantung pada apakah klien Anda privat atau publik.

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

Kami merekomendasikan kode aliran otorisasi OAuth 2.0 dengan PKCE untuk semua client dan memerlukannya untuk client publik.

Simpan rahasia klien di tempat yang aman dan jangan pernah ekspos ke publik. Aktor jahat dapat menggunakannya untuk mengirimi aplikasi Anda.

Untuk menerapkan aliran kode autorisasi, aplikasi Anda melakukan langkah-langkah berikut:

Hasilkan verifikator kode dan tantangan kode (hanya PKCE). Ini memungkinkan Anda untuk mencakup tantangan dalam permintaan Anda, bukan rahasia klien, yang meningkatkan keamanan.
Kirim permintaan GET ke ujung autorisasi dengan parameter yang sesuai.
Mengelola panggilan otorisasi. Setelah mendapatkan otorisasi, gunakan kode otorisasi dari Roblox dalam permintaan arah ke URL yang Anda spesifikasikan selama kreasiaplikasi. Parahalaman kode otorisasi untuk penggunaan selanjutnya.
Kirim permintaan POST ke ujung token dengan kode otorisasi. Jika berhasil, Anda menerima akses dan menyegarkan token dengan which to make API calls.
Panggil salah satu API Open Cloud yang mendukung autentikasi OAuth 2.0 berdasarkan dokumen referensi untuk sumber daya yang ingin Anda akses.

Bagian berikut menjelaskan setiap langkah dalam kedalaman lebih lanjut.

Membuat Tantangan Kode (Untuk PKCE saja)

Sebelum menginisialisasi proses autorisasi, Anda perlu menghasilkan tantangan kode dari verifier kode. Anda dapat menggunakan library atau fungsi bawaan dalam bahasa pemrograman pilihan Anda untuk menghasilkan tantangan kode, menghitung hash, dan melakukan enkripsi Base64 untuk menghasilkan tantangan kode.

Saat membuat verifikator kode, hanya gunakan karakter yang tidak direservasi, termasuk huruf besar dan huruf kecil (A-Z, a-z), digit desimal (0-9), huruf (-), period (., underline_, dan tilde (~), dengan panjang minimum 43 karakter dan panjang maksimum 128 karakter.

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

Generate Code Challenge
const crypto = require('crypto');

// base64URL encode the verifier and challenge
function base64URLEncode(str) {
  return str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
}

// create sha256 hash from code verifier
function sha256(buffer) {
  return crypto.createHash('sha256').update(buffer).digest(`base64`);

// create a random code verifier
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generate a challenge from the code verifier
var code_challenge = base64URLEncode(sha256(code_verifier));

Untuk PKCE, Anda memerlukan kode verifier dan nilai tantangan di langkah selanjutnya.

Membangun URL Autorisasi

Lihat dokumen referensi ujung autorisasi untuk informasi lengkap tentang cara membangun URL autorisasi.

Untuk menginisialisasi proses otorisasi pengguna, buat URL otorisasi dengan parameter yang diperlukan:

client_id : ID klien aplikasi Anda diperoleh setelah mendaftarkan aplikasi Anda.
redirect_uri : URL redirect aplikasiAnda, titik masuk kembali dari aplikasiAnda.
scope : Scope yang diminta yang mendefinisikan izin akses yang dibutuhkan aplikasi Anda dalam daftar terpisah ruang.
response_type : Tetapkan ke code untuk menunjukkan aliran kode otorisasi. Diperlukan hanya untuk PKCE
code_challenge : Kode tantangan dihasilkan dari verifier kode.
code_challenge_method : Tetapkan nilai parameter ini ke S256 untuk menunjukkan bahwa tantangan kode dibuat menggunakan algoritma SHA-256, metode tantangan kode paling umum dan aman.
state :Nilai acak yang aman untuk menjaga antara tahap permintaan dan panggilan. Diperlukan untuk non-PKCE saja
client_secret : Klien rahasia aplikasi Anda diperoleh setelah mendaftarkan aplikasi Anda. Jika Anda menggunakan autentikasi dengan PKCE, omit parameter ini. URL permintaan autorisasi Anda harus benar-benar berbentuk, seperti dalam contoh berikut:

Contoh URL Autorisasi 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, mereka dibawa melalui aliran autorisasi. Jika berhasil, Roblox mengalihkan pengguna ke redirect_uri yang ditentukan.

Penanganan Panggilan Autorisasi

Ketika aliran otorisasi berhasil, aplikasi Anda menerima permintaan GET dari server otorisasi Roblox di redirect_uri yang Anda spesifikasi. Dalam permintaan, Anda menerima code (kode otorisasi) dan 1> state1> (jika Anda menyediakan nilai sebelumnya) parameter.

code parameter berisi kode otorisasi yang dapat ditebus oleh aplikasi untuk token akses dari server otorisasi. Kebanyakan bahasa server back-end memiliki cara standar untuk mengakses parameter pencarian sebagai objek yang dibuat. Anda akan perlu mengambil parameter code dan menggunakannya untuk menukar token akses.
state parameter adalah nilai opake yang Anda sajikan di permintaan autorisasi. Anda dapat menggunakan parameter ini untuk menjaga status atau konteks proses autorisasi.

Misalnya, Anda mungkin menerima permintaan GET dengan URL berikut jika Anda menyebutkan URL redireksi Anda untuk menjadi https://example.com/redirect .

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

Jika otorisasi gagal, aplikasi Anda menerima permintaan error ke URL redirim yang ditentukan dengan error_description , 1> error_description1> dan 4> state4> (jika berlaku) parameter.

Parameter error menunjukkan kesalahan OAuth 2.0 spesifik yang terjadi selama proses autorisasi.
Parameter error_description menyediakan rincian tambahan tentang kesalahan.
Parameter state membantu aplikasi Anda mempertahankan status dalam kasus kegagalan.

Menukarkan kode autorisasi untuk token akses

Ketika Anda telah menyiarkan otorisasi code , tukar untuk token untuk mengakses sumber daya Roblox yang diinginkan:

Permintaan token akses dan token refresh dengan mengirim permintaan POST ke token exchange endpoint . Permintaan harus mencakup kode otorisasi, ID klien, dan nilai verifikasi kode (PKCE) atau rahasia klien (tidak-PKCE) dalam x-www-form-urlencoded format.

Parse token yang berlaku dari respons yang diterima. Token akses berlaku selama 15 menit. Toko token pembaruan dengan aman, biasanya di sisi server, sehingga Anda dapat menggunakannya untuk mendapatkan token baru di masa depan.

Contoh Balas Denda 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"
}

Membuat panggilan ke metode sumber daya

Sekarang Anda memiliki token akses yang diperlukan, Anda dapat menggunakannya untuk membuat panggilan yang diawasi ke metode sumber daya. Masukkan token akses ke bagian atas dari semua permintaan API untuk menyetujui mereka.

Misalnya, Anda dapat menguji apakah aplikasi Anda berfungsi dengan benar dengan mengikuti seluruh aliran otorisasi dan kemudian membuat permintaan GET ke ponsel informasi pengguna dengan token akses. Pastikan Anda memiliki openid atau

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