Muhammad Fari Madyan
Hire me
Spring Boot · bagian 7 dari 8

Java Spring Boot + React E-Learning Part 7: Refresh Cookie httpOnly, CSP & Scaling Multi-Instance dengan Redis dan S3

Memindahkan refresh token dari localStorage ke cookie httpOnly SameSite=Strict, menambahkan Content-Security-Policy lewat template envsubst nginx, dan membuat backend Spring Boot aman dijalankan sebagai beberapa instance: interface RateLimiter dengan implementasi Lua Redis, fan-out event STOMP lewat Redis pub/sub, dan storage S3/MinIO yang bisa diganti (PR #25).

Muhammad Fari Madyan

· 13 menit baca

Read in English →

Pendahuluan: Dua Sisa Pekerjaan dari Part 5

Di Part 5, saya membuat refresh token jadi sekali pakai dan bisa dicabut. Namun, masih ada dua hal yang mengganjal di kepala saya.

Pertama, tempat refresh token disimpan. Token dikembalikan di body JSON lalu disimpan di localStorage. Rotasi memang membatasi kerusakan kalau token dicuri, tetapi bug XSS tetap bisa membacanya lalu berlomba dengan user asli untuk refresh berikutnya. Menurut saya, tempat paling aman untuk kredensial berumur panjang adalah tempat yang sama sekali tidak bisa dibaca JavaScript.

Kedua, backend saya hanya bisa berjalan sebagai satu instance. Counter rate limit, broker STOMP, dan file upload semuanya tinggal di dalam satu JVM atau satu volume Docker. Coba jalankan instance kedua di belakang load balancer, maka limitnya jadi berlipat, guru kehilangan event live, dan separuh file mengembalikan 404.

Keduanya saya tangani di Pull Request #25: feat/roadmap-hardening, PR yang sama dengan pekerjaan integritas ujian di Part 6.

Dari satu VPS ke beberapa instance

Klik diagram untuk membukanya dalam ukuran penuh.


Backend: satu helper untuk semua endpoint yang menerbitkan token

Login, refresh, ganti password, registrasi, impersonasi, dan stop-impersonasi semuanya mengembalikan token. Daripada mengubah enam controller dengan enam cara berbeda, saya membuat satu komponen yang memindahkan refresh token dari body ke header Set-Cookie:

JAVA
@Component
public class RefreshTokenCookies {

    public static final String COOKIE_NAME = "refresh_token";
    /** Hanya endpoint auth (refresh, logout) yang menerima cookie ini. */
    public static final String COOKIE_PATH = "/api/v1/auth";

    public ResponseCookie issue(String refreshToken) {
        return base(refreshToken).maxAge(maxAge).build();
    }

    public ResponseCookie clear() {
        return base("").maxAge(Duration.ZERO).build();
    }

    /** Refresh token dipindahkan dari body JSON ke header Set-Cookie. */
    public ResponseEntity<ApiResponse<AuthResponse>> respond(AuthResponse auth, String message) {
        String refreshToken = auth.getRefreshToken();
        auth.setRefreshToken(null);
        ResponseEntity.BodyBuilder builder = ResponseEntity.ok();
        if (refreshToken != null && !refreshToken.isBlank()) {
            builder.header(HttpHeaders.SET_COOKIE, issue(refreshToken).toString());
        }
        return builder.body(ApiResponse.ok(auth, message));
    }

    private ResponseCookie.ResponseCookieBuilder base(String value) {
        return ResponseCookie.from(COOKIE_NAME, value)
                .httpOnly(true)
                .secure(secure)        // app.security.refresh-cookie.secure (default true)
                .sameSite(sameSite)    // app.security.refresh-cookie.same-site (default Strict)
                .path(COOKIE_PATH);
    }
}

Setiap atributnya punya tugas masing-masing:

AtributNilaiAlasan
HttpOnlyselaludocument.cookie tidak bisa membacanya, jadi script yang disuntikkan tidak bisa mencurinya
Securetrue (bisa diatur)Tidak pernah dikirim lewat HTTP biasa
SameSiteStrictTidak dikirim pada request lintas situs, sehingga memblokir CSRF ke refresh dan logout
Path/api/v1/authHanya endpoint auth yang menerimanya, bukan setiap panggilan API atau file statis
Max-AgeTTL refresh (7 hari)Sama dengan TTL jti di Redis

Controller membaca cookie lebih dulu, tetapi masih menerima body JSON lama. Dengan begitu, browser yang masih memuat frontend versi sebelumnya tetap berfungsi selama deploy:

JAVA
/** Cookie lebih dulu; body JSON masih diterima agar klien lama tetap berfungsi selama transisi. */
private static RefreshTokenRequest resolveRefreshToken(String cookieToken, RefreshTokenRequest body) {
    String token = cookieToken != null && !cookieToken.isBlank()
            ? cookieToken
            : (body != null ? body.getRefreshToken() : null);
    return RefreshTokenRequest.builder().refreshToken(token).build();
}

@PostMapping("/auth/refresh")
public ResponseEntity<ApiResponse<AuthResponse>> refreshToken(
        @CookieValue(name = RefreshTokenCookies.COOKIE_NAME, required = false) String cookieToken,
        @RequestBody(required = false) RefreshTokenRequest body) {
    AuthResponse response = authService.refreshToken(resolveRefreshToken(cookieToken, body));
    return refreshTokenCookies.respond(response, "Token refreshed successfully");
}

@PostMapping("/auth/logout")
public ResponseEntity<ApiResponse<Void>> logout(
        @CookieValue(name = RefreshTokenCookies.COOKIE_NAME, required = false) String cookieToken,
        @RequestBody(required = false) RefreshTokenRequest body) {
    authService.logout(resolveRefreshToken(cookieToken, body));
    return ResponseEntity.ok()
            .header(HttpHeaders.SET_COOKIE, refreshTokenCookies.clear().toString())
            .body(ApiResponse.ok(null, "Logged out"));
}

Frontend: kodenya justru berkurang

Interceptor Axios sekarang tidak lagi membaca atau menyimpan refresh token. Cukup panggil endpoint-nya, dan biar browser yang melampirkan cookie:

DIFF
-      const refreshToken = localStorage.getItem('refreshToken');
-      if (!refreshToken) {
+      // Refresh token ada di cookie httpOnly yang tidak bisa dibaca JavaScript,
+      // jadi access token-lah yang menandakan user sedang login.
+      if (!localStorage.getItem('token')) {
         // redirect ke /login
       }
-      const response = await axios.post('/api/v1/auth/refresh', { refreshToken });
+      // Browser mengirim cookie refresh httpOnly (path /api/v1/auth) dan menyimpan cookie hasil rotasi.
+      const response = await axios.post('/api/v1/auth/refresh', null, { withCredentials: true });

Logout dikirim dengan credentials: 'same-origin' dan keepalive: true (supaya request tetap selesai walaupun halaman pindah ke /login), dan initAuth menghapus refreshToken yang mungkin ditinggalkan build lama di localStorage:

TYPESCRIPT
// Build lama menyimpan refresh token di localStorage; hapus agar tidak bisa dicuri.
const removeLegacyRefreshToken = () => localStorage.removeItem('refreshToken');

Development lokal

Cookie Secure tidak dikirim lewat http://localhost di semua browser (Safari cukup ketat soal ini). Karena itu, docker-compose.yml untuk development memakai APP_REFRESH_COOKIE_SECURE=false, sedangkan produksi tetap memakai default true.

Yang masih terbuka

Saya akui, access token 15 menit masih ada di localStorage. Menyimpannya di memori dengan silent refresh saat halaman dimuat akan menutup celah itu, dan sudah saya catat sebagai item terbuka di roadmap. Untuk sementara, Content-Security-Policy di bagian berikutnya mempersempit risikonya.


2. Content-Security-Policy untuk SPA

CSP memberi tahu browser sumber mana yang boleh menjalankan script, memuat style, membuka koneksi, atau membingkai halaman. Bahkan kalau penyerang berhasil menyuntikkan markup, script-src yang ketat mencegah browser mengeksekusinya.

NGINX
# frontend/nginx.conf (di-render sebagai template, lihat di bawah)
add_header Content-Security-Policy "default-src 'self'; script-src 'self' ${CSP_SCRIPT_SRC_EXTRA}; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; media-src 'self' blob:; connect-src 'self' ${CSP_CONNECT_SRC_EXTRA}; frame-src 'self' blob:; frame-ancestors 'self'; object-src 'none'; base-uri 'self'; form-action 'self'" always;

Ini beberapa pilihan yang saya ambil, beserta alasannya:

  • script-src 'self' tanpa 'unsafe-inline': tidak ada <script> inline dan tidak ada eval.
  • style-src 'unsafe-inline': React dan beberapa library UI memasang atribut style inline. Mengizinkan style inline jauh lebih kecil risikonya dibanding script inline.
  • img-src/media-src/frame-src blob:: file terproteksi dari Part 5 dibuka sebagai URL blob:, dan PDF ditampilkan di iframe.
  • connect-src 'self': Axios dan WebSocket (/ws) berada di origin yang sama.
  • frame-ancestors 'self' dan object-src 'none': tidak ada clickjacking, tidak ada plugin.

Satu script inline harus dibuang

index.html saya punya script inline kecil, karena beberapa build browser SockJS mengharapkan global ala Node. Dengan script-src 'self', script itu akan diblokir, jadi saya memindahkannya ke file statis:

HTML
<!-- sebelum -->
<script>window.global = window; var global = window;</script>
<!-- sesudah -->
<script src="/global-shim.js"></script>

Analytics tanpa mengubah konfigurasi

Demo live saya memakai analytics, yang butuh host tambahan di script-src dan connect-src. Image resmi nginx me-render file di /etc/nginx/templates/ dengan envsubst saat startup, jadi Dockerfile menyalin konfigurasinya ke sana:

DOCKERFILE
COPY nginx.conf /etc/nginx/templates/default.conf.template
# hanya variabel berawalan CSP_ yang disubstitusi, sehingga $uri, $host, ... milik nginx tidak tersentuh
ENV NGINX_ENVSUBST_FILTER="^CSP_"
ENV CSP_SCRIPT_SRC_EXTRA=""
ENV CSP_CONNECT_SRC_EXTRA=""

NGINX_ENVSUBST_FILTER ini penting. Tanpanya, envsubst juga akan mengganti $uri dan $host dengan string kosong dan merusak routing. Sekarang, mengaktifkan analytics cukup dengan satu variabel environment:

BASH
CSP_SCRIPT_SRC_EXTRA="https://www.googletagmanager.com"
CSP_CONNECT_SRC_EXTRA="https://*.google-analytics.com"

Kalau kamu mau memeriksa policy-nya, buka DevTools: setiap resource yang diblokir muncul di console sebagai pelanggaran CSP, lengkap dengan direktif yang memblokirnya.


3. Apa yang Rusak Jika Ada Dua Instance Backend

Sebelum menulis kode, saya mendaftar dulu apa saja yang disimpan di dalam satu instance:

StateLokasiYang terjadi dengan 2+ instance
jti refresh tokenRedisSudah dibagi ✔
Access tokenJWT statelessBekerja di mana saja ✔
Job attempt kedaluwarsaSetiap instanceAman berkat @Version dari Part 6 ✔
Counter rate limitBucket4j di memoriSetiap instance menghitung sendiri: limit dikali N
Broker STOMPSimple broker di memoriGuru di instance A tidak menerima event dari instance B
File uploadVolume DockerFile yang diunggah ke A mengembalikan 404 saat diminta dari B

Tiga yang terakhir butuh tempat bersama. Redis sudah ter-deploy, dan storage yang kompatibel dengan S3 mudah ditambahkan, jadi masing-masing saya beri interface dengan implementasi lokal dan bersama, yang dipilih lewat satu pengaturan.


4. Rate Limit yang Dibagi Lewat Redis

JAVA
public interface RateLimiter {

    /** Mencatat satu request untuk key; false jika lebih dari capacity terjadi dalam window. */
    boolean tryAcquire(String key, int capacity, Duration window);

    /** Melupakan riwayat key (mis. setelah login sukses). */
    void reset(String key);
}

InMemoryRateLimiter mempertahankan kode Bucket4j + Caffeine dari Part 5. RedisRateLimiter memakai fixed window, dengan increment dan expiry dalam satu script Lua:

JAVA
static final DefaultRedisScript<Long> INCREMENT_SCRIPT = new DefaultRedisScript<>(
        "local current = redis.call('INCR', KEYS[1]) "
                + "if current == 1 then redis.call('PEXPIRE', KEYS[1], ARGV[1]) end "
                + "return current",
        Long.class);

@Override
public boolean tryAcquire(String key, int capacity, Duration window) {
    try {
        Long count = redis.execute(INCREMENT_SCRIPT, List.of(KEY_PREFIX + key), String.valueOf(window.toMillis()));
        return count == null || count <= capacity;
    } catch (RuntimeException e) {
        log.warn("Rate-limit store unavailable, allowing request for {}: {}", key, e.getMessage());
        return true;
    }
}

Kenapa harus script? Kalau pakai dua perintah terpisah (INCR, lalu PEXPIRE), crash di antara keduanya akan meninggalkan key tanpa expiry, dan klien itu terblokir selamanya. Redis menjalankan script Lua secara atomik, jadi keduanya terjadi atau tidak sama sekali.

Ada dua trade-off yang sengaja saya terima:

  • Fail open. Kalau Redis mati, request tetap diizinkan dan peringatan dicatat. Saat ujian berlangsung, membiarkan 500 siswa tetap bekerja lebih penting daripada limit yang ketat selama beberapa menit. Endpoint login sebuah bank tentu akan memilih sebaliknya.
  • Fixed window. Klien bisa mengirim sampai 2× kapasitas di batas window (akhir satu menit, awal menit berikutnya). Untuk perlindungan dari penyalahgunaan, itu masih bisa diterima, dan biayanya hanya satu panggilan Redis per request.

Implementasinya dipilih saat startup:

JAVA
@Bean
@ConditionalOnProperty(name = "app.rate-limit.store", havingValue = "memory", matchIfMissing = true)
public RateLimiter inMemoryRateLimiter() { return new InMemoryRateLimiter(); }

@Bean
@ConditionalOnProperty(name = "app.rate-limit.store", havingValue = "redis")
public RateLimiter redisRateLimiter(StringRedisTemplate redisTemplate) { return new RedisRateLimiter(redisTemplate); }

Sekarang RateLimitingFilter dan LoginRateLimiterService hanya bergantung pada interface.


5. Event Ujian Live Lintas Instance

Misalnya jawaban siswa ditangani instance B, tetapi WebSocket guru terhubung ke instance A. Dengan broker di memori, A tidak akan pernah tahu.

Jawaban yang umum untuk masalah ini adalah STOMP broker relay (RabbitMQ atau ActiveMQ). Saya memilih pendekatan yang lebih ringan dengan memakai ulang Redis: setiap instance tetap punya broker di memori, dan event berpindah antar-instance lewat Redis pub/sub.

JAVA
public void broadcastExamEvent(Long examId, String eventType, Object payload) {
    Envelope envelope = new Envelope("/topic/exams/" + examId + "/monitor",
            Map.of("eventType", eventType, "timestamp", System.currentTimeMillis(), "data", payload));

    if (TransactionSynchronizationManager.isSynchronizationActive()) {
        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
            @Override
            public void afterCommit() { dispatch(envelope); }
        });
    } else {
        dispatch(envelope);
    }
}

private void dispatch(Envelope envelope) {
    if (!redisFanout) {
        sendLocally(envelope);
        return;
    }
    try {
        redisTemplate.convertAndSend(REDIS_CHANNEL, objectMapper.writeValueAsString(envelope));
    } catch (Exception e) {
        // Monitoring live bersifat best effort: kirim lewat instance ini daripada event hilang.
        sendLocally(envelope);
    }
}

Setiap instance melakukan subscribe ke channel lalu meneruskan pesan yang diterima ke broker miliknya:

JAVA
@Configuration
@ConditionalOnProperty(name = "app.realtime.mode", havingValue = "redis")
public class RealtimeRedisConfig {

    @Bean
    public RedisMessageListenerContainer examEventsListenerContainer(
            RedisConnectionFactory connectionFactory, ExamRealtimeService realtimeService) {
        RedisMessageListenerContainer container = new RedisMessageListenerContainer();
        container.setConnectionFactory(connectionFactory);
        container.addMessageListener(
                (message, pattern) -> realtimeService.deliverFromRedis(new String(message.getBody(), StandardCharsets.UTF_8)),
                new ChannelTopic(ExamRealtimeService.REDIS_CHANNEL));   // "elearning:exam-events"
        return container;
    }
}

Kenapa saya memilih desain ini dan bukan broker relay?

  • Tanpa infrastruktur baru. Redis sudah ada untuk refresh token.
  • Jalur kode yang sama di kedua mode. Mode local melewati publish; mode redis melakukan publish dan setiap instance (termasuk pengirimnya) mengirim lewat deliverFromRedis.
  • Best effort sudah cukup. Monitor selalu bisa dibangun ulang dari GET /exams/{id}/monitor, jadi event yang hilang hanya masalah tampilan, bukan kehilangan data. Karena itu, kegagalan Redis jatuh ke pengiriman lokal, bukan menggagalkan request.

Kalau suatu saat volume pesan melebihi kemampuan pub/sub, relay tetap jadi opsi. Keputusan ini saya catat di docs/ARCHITECTURE.md (lihat Part 8).


6. Upload di S3 atau MinIO

Dulu FileStorageService menulis langsung ke disk. Sekarang ia memvalidasi dulu, baru mendelegasikan:

JAVA
public interface StorageBackend {
    void put(String key, InputStream content, long size, String contentType) throws IOException;
    /** Mengembalikan file, atau melempar RuntimeException jika tidak ada. */
    Resource get(String key);
    /** Menghapus file jika ada; file yang tidak ada diabaikan. */
    void delete(String key);
}

Bagian pentingnya justru apa yang tidak ikut pindah. Allow-list ekstensi, nama UUID acak, dan pengecekan path traversal tetap di FileStorageService, di depan semua backend:

JAVA
/** Menolak path absolut, backslash, dan key apa pun yang keluar dari root storage. */
static void validateKey(String key) {
    if (key.contains("\\") || key.startsWith("/")) {
        throw new SecurityException("Invalid file path: " + key);
    }
    Path normalized = Paths.get(key).normalize();
    if (normalized.isAbsolute() || normalized.startsWith("..") || normalized.toString().isEmpty()) {
        throw new SecurityException("Access to path outside upload directory is forbidden: " + key);
    }
}

Jadi, pertahanan dari Part 2 juga berlaku untuk S3, dan backend S3 bisa tetap sederhana. S3StorageBackend (AWS SDK v2) bekerja dengan AWS maupun MinIO:

JAVA
public static S3StorageBackend create(String bucket, String region, String endpoint,
                                      String accessKey, String secretKey, boolean pathStyle) {
    if (bucket == null || bucket.isBlank()) {
        throw new IllegalStateException("app.storage.s3.bucket is required when app.storage.type=s3");
    }
    AwsCredentialsProvider credentials = accessKey == null || accessKey.isBlank()
            ? DefaultCredentialsProvider.create()          // env var, instance role, ...
            : StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretKey));

    S3ClientBuilder builder = S3Client.builder()
            .region(Region.of(region))
            .credentialsProvider(credentials)
            .serviceConfiguration(S3Configuration.builder().pathStyleAccessEnabled(pathStyle).build());
    if (endpoint != null && !endpoint.isBlank()) {
        builder.endpointOverride(URI.create(endpoint));   // mis. http://minio:9000
    }
    return new S3StorageBackend(builder.build(), bucket);
}

Object key-nya sama dengan path relatif di disk (materials/3f2a….pdf), sehingga aturan otorisasi di FileAccessService tidak berubah sama sekali.


7. Cara Mengaktifkannya

Satu instance tetap jadi default, jadi tidak ada yang berubah untuk deploy single VPS saya saat ini. Untuk menjalankan beberapa instance, kamu cukup mengatur tiga switch:

Pengaturan1 instance (default)N instance
APP_REALTIME_MODElocalredis
APP_RATE_LIMIT_STOREmemoryredis
APP_STORAGE_TYPElocals3 ditambah APP_STORAGE_S3_BUCKET, _REGION, _ENDPOINT, _ACCESS_KEY, _SECRET_KEY, _PATH_STYLE
APP_REFRESH_COOKIE_SECUREtrue (false hanya untuk dev HTTP)true

Repo ini menyediakan switch-nya, bukan load balancer-nya. Contoh minimal dengan MinIO dan upstream Nginx kira-kira seperti ini (tidak ada di repositori, jadi sesuaikan dengan platform kamu):

YAML
# docker-compose.scale.yml (contoh override)
services:
  backend:
    container_name: !reset null      # nama tetap mencegah scaling
    environment:
      APP_REALTIME_MODE: redis
      APP_RATE_LIMIT_STORE: redis
      APP_STORAGE_TYPE: s3
      APP_STORAGE_S3_BUCKET: elearning-uploads
      APP_STORAGE_S3_ENDPOINT: http://minio:9000
      APP_STORAGE_S3_PATH_STYLE: "true"
      APP_STORAGE_S3_ACCESS_KEY: ${MINIO_ROOT_USER}
      APP_STORAGE_S3_SECRET_KEY: ${MINIO_ROOT_PASSWORD}
  minio:
    image: minio/minio               # pin tag rilis di produksi
    command: server /data
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio_data:/data
volumes:
  minio_data:
NGINX
upstream elearning_backend {
    ip_hash;   # sticky: transport fallback SockJS menyimpan state sesi di satu instance
    server backend-1:8080;
    server backend-2:8080;
    server backend-3:8080;
}

Koneksi WebSocket native berumur panjang dan otomatis tetap di satu instance. Sticky session penting untuk fallback SockJS (XHR streaming dan polling), yang menyebar satu sesi logis ke banyak request HTTP.


8. Checklist

AreaSebelumSetelah PR #25
Penyimpanan refresh tokenlocalStorageCookie httpOnly, Secure, SameSite=Strict di /api/v1/auth
Klien lama selama deploy—Cookie lebih dulu, body JSON tetap diterima
Script inlineDiizinkanDiblokir CSP; shim pindah ke /global-shim.js
Host analyticsHardcodeCSP_SCRIPT_SRC_EXTRA / CSP_CONNECT_SRC_EXTRA
Rate limitPer instanceInterface RateLimiter; fixed window Lua di Redis, fail open
Event liveHanya satu instanceDispatch setelah commit, fan-out Redis pub/sub, fallback lokal
UploadVolume DockerStorageBackend: lokal atau S3/MinIO, validasi tidak berubah

Kesimpulan & Selanjutnya

Sekarang refresh token sudah di luar jangkauan JavaScript, SPA menolak script inline, dan backend bisa berjalan sebagai beberapa instance hanya dengan mengubah variabel environment. Setiap switch punya default yang aman, sehingga deploy single VPS dari Part 4 tetap bekerja persis seperti sebelumnya.

Setelah tiga pull request besar, README saya tidak lagi menggambarkan sistemnya dengan akurat. Di bagian terakhir, Part 8, saya cerita soal docs/ARCHITECTURE.md, 55 test backend yang menyertai perubahan ini, dan coverage JaCoCo di CI.

BagikanLinkedInXWhatsApp

Ditulis oleh Muhammad Fari Madyan

Senior Full Stack Engineer dan co-founder LampungDev. Saya menuliskan apa yang saya bangun supaya orang lain bisa ikut belajar.

Ajak kerja sama
← bagian 6Integritas Ujian Saat Konkurenbagian 8 →Dokumentasi Arsitektur yang Sesuai Kode

Muhammad Fari Madyan

Senior Full Stack Engineer building web and mobile systems that hold up in production. Co-founder of LampungDev. Based in Bandar Lampung, Indonesia (UTC+7), working remote.

Work

Case studiesCahTixExam platform, 4 stacksOpen source

© 2026 Muhammad Fari Madyan

Designed and built by Muhammad Fari Madyan