Belajar Quarkus - OAuth2 / OIDC & JWT

#Pendahuluan

Basic auth cukup untuk aplikasi kecil, tapi aplikasi modern butuh federasi identitas: pengguna login di satu tempat (Google, GitHub, Keycloak) lalu mengakses banyak layanan. Di sinilah OAuth2 dan OpenID Connect (OIDC) berperan.

Episode 13 membahas integrasi Quarkus dengan OIDC external identity provider, implementasi JWT authentication dan authorization, service-to-service auth dengan token introspection, serta best practice penyimpanan, refresh, dan scope token.

#Integrasi Quarkus OIDC untuk External Identity Provider

#Menambahkan Extension

./mvnw quarkus:add-extension -Dextensions=oidc

Perintah ./mvnw quarkus:add-extension -Dextensions=oidc menambahkan dukungan OIDC ke project.

#Konfigurasi OIDC

Hubungkan Quarkus ke identity provider (misalnya Keycloak) lewat konfigurasi:

quarkus.oidc.auth-server-url=https://auth.example.com/realms/demo
quarkus.oidc.client-id=quarkus-app
quarkus.oidc.credentials.secret=client-secret
quarkus.oidc.tls.verification=certificate-validation

• auth-server-url: endpoint realm OIDC provider.
• client-id dan credentials.secret: kredensial aplikasi untuk authorization code flow.
• tls.verification: pastikan sertifikat server divalidasi.

#Melindungi Endpoint

Setelah konfigurasi, endpoint bisa diproteksi hanya dengan konfigurasi:

quarkus.http.auth.permission.authenticated.paths=/api/*
quarkus.http.auth.permission.authenticated.policy=authenticated

Aturan ini menolak semua request ke /api/* tanpa token valid dari provider.

#Implementasi JWT Authentication dan Authorization

#Bagaimana JWT Bekerja

JWT (JSON Web Token) adalah token berformat header.payload.signature. Payload berisi klaim seperti sub, exp, dan roles. Signature menjamin token tidak dimodifikasi. Quarkus memvalidasi signature memakai key dari provider OIDC — tanpa memanggil server di setiap request.

#Membaca Klaim di Resource

Membaca klaim JWT

import jakarta.annotation.security.RolesAllowed;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import org.eclipse.microprofile.jwt.JsonWebToken;
 
@Path("/api/user")
public class UserResource {
 
    @Inject
    JsonWebToken jwt;
 
    @GET
    @RolesAllowed("user")
    public String info() {
        return "Halo " + jwt.getSubject();
    }
}

jwt.getSubject() mengembalikan klaim sub — identitas pengguna. Anotasi @RolesAllowed("user") memverifikasi klaim roles pada token.

#Klaim Roles

Pastikan identity provider mengirim klaim roles. Di Keycloak, pemetaan role menjadi klaim ini diatur di client scope. Jika nama klaim berbeda, peta lewat konfigurasi:

quarkus.oidc.roles.claim=roles

#Service-to-Service Auth dengan Token Introspection

#Introspection untuk Opaque Token

Tidak semua service memakai JWT. Opaque token perlu diverifikasi lewat introspection endpoint:

quarkus.oidc.token.audience=quarkus-app
quarkus.oidc.token-issuer=https://auth.example.com/realms/demo

Saat client mengirim token opaque ke Authorization: Bearer, Quarkus memanggil endpoint introspection provider untuk memvalidasi dan mengambil klaim. Ini umum dipakai untuk komunikasi antar service internal.

#Client Credentials Flow

Service-to-service tanpa intervensi pengguna memakai client credentials flow:

Client credentials flow

import io.quarkus.oidc.client.OidcClient;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
 
@ApplicationScoped
public class InternalApiClient {
 
    @Inject
    OidcClient oidcClient;
 
    public String panggilServiceInternal() {
        String token = oidcClient.getTokens().await().indefinitely()
            .getAccessToken();
        return kirimRequest(token);
    }
}

oidcClient.getTokens() memperoleh access token dengan client credentials. Token ini dipakai untuk memanggil service internal lain — pola umum pada arsitektur microservices.

#Best Practice Token Storage, Refresh, dan Scope

#Jangan Simpan JWT di Storage Tidak Aman

Di browser, simpan access token di memori, bukan localStorage (rentan XSS). Untuk aplikasi native, simpan aman di keychain. Di server, jangan pernah log token — JWT berisi identitas sensitif.

#Scope yang Minimal

Minta scope sekecil mungkin:

quarkus.oidc.scopes=openid,profile

quarkus.oidc.scopes menentukan klaim yang diminta dari provider. Semakin sedikit data yang diminta, semakin kecil permukaan serangan.

#Refresh Token dan Logout

Access token berumur pendek (misal 5 menit); refresh token memperoleh access token baru tanpa login ulang. Quarkus mengelola ini otomatis untuk aplikasi berbasis web. Aturan utama: refresh token hanya dikirim ke server, tidak pernah ke client-side JavaScript. Untuk logout, panggil endpoint logout provider:

quarkus.oidc.logout.path=/api/logout
quarkus.oidc.logout.post-logout-path=/

#Penutup

Episode 13 membawa kalian ke keamanan modern: memahami integrasi Quarkus OIDC dengan external identity provider, implementasi JWT authentication dan authorization, service-to-service auth dengan token introspection dan client credentials flow, serta best practice penyimpanan, refresh, dan scope token.

Inti yang harus dibawa pulang:

• OIDC memindahkan autentikasi ke identity provider eksternal.
• JWT divalidasi dengan signature tanpa memanggil server setiap request.
• @RolesAllowed membaca klaim roles dari token.
• Opaque token diverifikasi lewat introspection endpoint.
• Client credentials flow untuk komunikasi service-to-service.
• Access token disimpan di memori; refresh token hanya di server.
• Scope dibuat seminimal mungkin untuk mengurangi permukaan serangan.

Di episode 14 selanjutnya kita akan membahas secure microservices dan API gateway — pola secure microservices dengan Quarkus, integrasi dengan Istio, Envoy, atau API gateway, securing inter-service communication, serta rate limiting dan API policy.